calclibimp/README.md

# Library calclib Implementation

## Overview

This project, `calclibimp`, serves as the concrete implementation of a calculation library within 
the **KnitPkg for MetaTrader** Demo ecosystem. It provides a practical example of how to build a reusable MQL5 
library (`.ex5`) that leverages other KnitPkg packages, specifically `@douglasrechia/calc` for core technical analysis 
functions and `@douglasrechia/bar` for robust time series data access. The 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.

The primary function implemented here is `SMA_Close_TimeSeries`, which calculates a rolling Simple Moving 
Average (SMA) for a given symbol and timeframe. This library demonstrates how to encapsulate complex logic 
into a compiled MQL5 library, showing the power of KnitPkg in linking several packages.

## Features

*   **SMA Calculation as a Library Function**: Implements a function to calculate a Simple Moving Average 
for a specified period and length, returning the results as a series.
*   **Leverages KnitPkg Core Libraries**: Utilizes `douglasrechia::SMA` from `@douglasrechia/calc` for the core SMA 
algorithm and `douglasrechia::TimeSeriesArray<double>` from `@douglasrechia/bar` for efficient and series-ordered 
price data handling.
*   **MQL5 Library (`.ex5`) Output**: Compiles into an MQL5 library, which can be imported and used by means
of `@douglasrechia/calclib`.
*   **Modular Design**: Showcases how to structure a project to create a standalone calculation library, 
enhancing reusability and maintainability across different KnitPkg solutions.
*   **KnitPkg Dependency Management**: Demonstrates how a library project itself can declare and manage its 
own KnitPkg dependencies.

## Prerequisites

To compile 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).

## Downloading and install `calclibimp` in your MetaTrader

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

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

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

# Compile the Library
kp compile

# Copy the binary to MQL5/Libraries directory (needed to `@douglasrechia/calclib` import it correctly)
cp .\src\CalcLibImp.ex5 ..
```

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/calclibimp

# Copy the binary to MQL5/Libraries directory (needed to `@douglasrechia/calclib` import it correctly)
cp .\MQL5\Libraries\calclibimp\bin\CalcLibImp.ex5 .\MQL5\Libraries
```

## Next steps

Checkout `@douglasrechia/calclib` to see this library in action.

## 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.*