132 lines
4.3 KiB
Markdown
132 lines
4.3 KiB
Markdown
# Package barhelper
|
|
|
|
**Helper for `@douglasrechia/bar`**
|
|
*MIT License*
|
|
|
|
---
|
|
|
|
## What is this?
|
|
|
|
`barhelper` is a **demonstration helper package** that showcases how to build a KnitPkg package that **extends** another package (`@douglasrechia/bar`).
|
|
|
|
It provides:
|
|
|
|
- Simple crossover helpers like `CrossUp()` and `Cross()` for `ITimeSeries<double>`
|
|
- Indicator helpers like `NewTimeSeriesFromIndicator()` to convert indicator buffers into `ITimeSeries<double>`
|
|
|
|
This project is intended **only as an educational example** of how to structure, package, install dependencies, 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 `barhelper` also installs its dependency `@douglasrechia/bar`
|
|
- **MQL5 target** — designed for MetaTrader 5
|
|
- **Compile support** — `kp compile` compiles the unit test script(s)
|
|
- **Crossover detection** — helpers for time series crossover logic
|
|
- **Indicator helpers** — convert indicator buffers into `ITimeSeries<double>`
|
|
|
|
---
|
|
|
|
## Installing as a dependency (recommended)
|
|
|
|
To add `barhelper` to your KnitPkg project:
|
|
|
|
```bash
|
|
kp add @douglasrechia/barhelper
|
|
```
|
|
|
|
---
|
|
|
|
## 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/barhelper/<Header>.mqh"
|
|
```
|
|
|
|
Then use the helper functions to work with `ITimeSeries<double>` instances (for example, crossover detection).
|
|
|
|
> Note: The exact header names and function signatures depend on the package headers. Use MetaEditor IntelliSense (after `kp autocomplete`) 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/barhelper.git
|
|
cd barhelper
|
|
```
|
|
|
|
### 2) Generate autocomplete
|
|
|
|
```bash
|
|
# Generates autocomplete / IntelliSense support for MetaEditor
|
|
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/barhelper
|
|
```
|
|
|
|
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.
|