expertdemo/README.md

# EA expertdemo

**Expert Advisor demonstrating package reuse with KnitPkg for MetaTrader**  
*MIT License*  

---

## What is this?

EA `expertdemo` is a **demonstration project** that showcases how to build a MetaTrader Expert Advisor (EA) by consuming KnitPkg packages.  
It demonstrates best practices for structuring, packaging and compiling MQL5 code with KnitPkg – it is **not** meant to be a production-grade 
trading system, but rather an **educational example** of how to reuse packages from the community or your own library.

## Features

- **Expert Advisor type** (`type: expert`) – a complete, compilable EA that depends on multiple packages.  
- **Transitive dependencies** – automatically resolves and includes `@douglasrechia/bar` and `@douglasrechia/calc` when compiled.  
- **Flat include mode** (`include_mode: flat`) – generates a single flattened header with all dependencies resolved.  
- **MQL5 target** – works with MetaTrader 5.  
- **Compile support** – `kp compile` compiles the EA to `.ex5` binary.
- **Bar watcher for new bar detection** - Re-calculates every new bar, not every tick.

## How it works

This EA uses two KnitPkg packages:

1. **@douglasrechia/bar** – provides `BarWatcher` (detects bar changes) and `Bar` (OHLCV data access)
2. **@douglasrechia/calc** – provides technical analysis functions like `SMA()` and `ATR()`

When you run `kp install`, KnitPkg automatically downloads both packages and resolves their transitive dependencies.

## Prerequisites

To compile and run 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/DouglasRechia/kp).

## Downloading and install `expertdemo` in your MetaTrader

To learn how to structure your own EA with KnitPkg packages, clone this repository:

```bash
# Change to your MetaTrader 'Experts' directory.
# How to find it: in the MetaEditor navigator, right‑click the `Experts` folder and select "Open Folder".
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\D0E8209F77C8CF37AD8BF550E51FF075\MQL5\Experts"

# Clone the repository
git clone https://forge.mql5.io/DouglasRechia/expertdemo.git
cd expertdemo

# Install dependencies (downloads @douglasrechia/calc and @douglasrechia/bar automatically)
kp install

# Compile the EA
kp compile

# Close MetaTrader and launch it again (needed to refresh navigator Scripts). Open any chart you want.
# The compiled binary `KnitPkgExpertDemo.ex5` will appear in MetaTrader navigator under the Experts/expertdemo/bin entry.
# Double‑click it to run the tests. See logs in the 'Scripts' tab.
```

Alternatively, execute the `get` command to query the registry for project metadata, enabling the automatic 
download and compilation of the latest stable version.

``` bash
# Change to your MetaTrader Data folder directory. This is step is required only if you have
# more than one MetaTrader instalation.
# How to find it: in the MetaTrader navigator, click on menu File/Open data folder.
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\D0E8209F77C8CF37AD8BF550E51FF075"

kp get mql5 @douglasrechia/expertdemo

# Close MetaTrader and launch it again (needed to refresh navigator Scripts). Open any chart you want.
# The compiled binary `KnitPkgExpertDemo.ex5` will appear in MetaTrader navigator under the Experts/expertdemo/bin entry.
# Double‑click it to run the tests. See logs in the 'Scripts' tab.
```

## License

This project is released under the **MIT License**. See the `LICENSE` file for the full text.

## Disclaimer

*The author provides this code **as‑is**, for **educational purposes only*.  
No warranty, express or implied, is given. The author assumes **no liability** for any damages, losses, or legal consequences that may arise from using, modifying, or distributing this software. Use it at your own risk.*