137 lines
4.2 KiB
Markdown
137 lines
4.2 KiB
Markdown
# Package calc
|
|
|
|
**Common indicators built on `@douglasrechia/bar`**
|
|
*MIT License*
|
|
|
|
---
|
|
|
|
## What is this?
|
|
|
|
`calc` is a **demonstration package** that showcases how to build a KnitPkg package that **depends on another KnitPkg package**.
|
|
|
|
It provides a small, self-contained library that implements common technical analysis functions (SMA, ATR, etc.) on top of the `IBar`
|
|
and `ITimeSeries` interfaces from `@douglasrechia/bar`.
|
|
|
|
This project is intended **only as an educational example** of how to structure, package, and compile **MQL5** code with KnitPkg.
|
|
It is **not** meant to be a production-grade library for large-scale use.
|
|
|
|
## Prerequisites
|
|
|
|
To use this project, you will need:
|
|
|
|
1. [**MetaTrader 5**](https://www.mql5.com/) installed.
|
|
2. **KnitPkg CLI**: The KnitPkg package manager for MetaTrader. If you don't have it, you can install it by following the instructions in the [main KnitPkg repository](https://github.com/knitpkg-dev/knitpkg-mt.git).
|
|
3. **KnitPkg homepage**: See [https://knitpkg.dev](https://knitpkg.dev) for an overview and [https://docs.knitpkg.dev](https://docs.knitpkg.dev) for documentation.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Package type** (`type: package`) — header-only library consumable by other KnitPkg projects
|
|
- **Transitive dependencies** — importing `calc` also makes `@douglasrechia/bar` available
|
|
- **MQL5 target** — designed for MetaTrader 5
|
|
- **Compile support** — `kp compile` compiles the unit test script(s)
|
|
- **Common indicators** — implements functions like SMA, ATR, etc.
|
|
|
|
---
|
|
|
|
## Installing as a dependency (recommended)
|
|
|
|
To add `calc` to your KnitPkg project:
|
|
|
|
```bash
|
|
kp add @douglasrechia/calc
|
|
```
|
|
|
|
> Note: Packages are meant to be consumed as dependencies. The `kp install` workflow is intended for other project types (Experts, Indicators, Libraries, etc.), not for packages.
|
|
|
|
---
|
|
|
|
## Basic usage (example)
|
|
|
|
In the case your MQL5 project uses `include_mode: include`, include headers from the KnitPkg include directory:
|
|
|
|
```mql5
|
|
#include "../knitpkg/include/douglasrechia/calc/<Header>.mqh"
|
|
```
|
|
|
|
Because `calc` depends on `@douglasrechia/bar`, you can also include `bar` headers (as needed) from:
|
|
|
|
```mql5
|
|
#include "../knitpkg/include/douglasrechia/bar/<Header>.mqh"
|
|
```
|
|
|
|
> Note: The exact header names and function signatures depend on the package headers. Use MetaEditor IntelliSense to browse the available APIs.
|
|
|
|
---
|
|
|
|
## Exploring the project locally (optional)
|
|
|
|
If you want to explore how a KnitPkg package with dependencies is structured, clone the repository and run the standard workflow.
|
|
|
|
### 1) Clone into MetaTrader `Scripts` folder (example)
|
|
|
|
```bash
|
|
# Go to your MetaTrader 'Scripts' directory.
|
|
# Tip: in MetaEditor, right-click the `Scripts` folder and choose "Open Folder".
|
|
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>\MQL5\Scripts"
|
|
|
|
git clone https://forge.mql5.io/DouglasRechia/calc.git
|
|
cd calc
|
|
```
|
|
|
|
### 2) Generate autocomplete
|
|
|
|
```bash
|
|
# Generates autocomplete / IntelliSense support for MetaEditor.
|
|
# This step will also resolve dependencies required by the test scripts.
|
|
kp autocomplete
|
|
```
|
|
|
|
### 3) Compile
|
|
|
|
```bash
|
|
kp compile
|
|
```
|
|
|
|
---
|
|
|
|
## Running unit tests
|
|
|
|
Unit tests are implemented as a MetaTrader **Script**.
|
|
|
|
1. Compile the project.
|
|
2. Restart MetaTrader (so the Navigator refreshes).
|
|
3. Run the generated unit test script from the Navigator on any chart.
|
|
4. Check results in the MetaTrader console (Experts/Scripts tab, depending on your setup).
|
|
|
|
The compiled binary is placed under the project `bin/` directory (and appears in the Navigator under the corresponding compiled location after refresh).
|
|
|
|
---
|
|
|
|
## One-command download/build via the registry (optional)
|
|
|
|
You can also use `kp get` to query the registry for metadata and automatically download/build the latest stable version.
|
|
|
|
Example (run from your MetaTrader *Data Folder* root):
|
|
|
|
```bash
|
|
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>"
|
|
|
|
kp get mql5 @douglasrechia/calc
|
|
```
|
|
|
|
Restart MetaTrader afterward to refresh the Navigator, then run the unit test script as described above.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
This project is released under the **MIT License**. See `LICENSE` for details.
|
|
|
|
---
|
|
|
|
## Disclaimer
|
|
|
|
This code is provided **as-is**, for **educational purposes only**.
|
|
No warranty (express or implied) is provided. Use at your own risk.
|