calclib/README.md

# Library calclib Stubs

## Overview

This project, `calclib`, is a crucial component within the **KnitPkg for MetaTrader** Demo ecosystem, 
designed to facilitate the consumption of `@douglasrechia/calclibimp` by other KnitPkg projects. It acts 
as a "stub" package, providing the necessary header files (`.mqh`) with `#import` directives that allow other 
MQL5 Expert Advisors, Indicators, or Scripts to seamlessly call functions implemented in a separate, compiled 
library. 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.

By separating the library's interface (stubs) from its implementation, `calclib` promotes a clean, 
modular architecture. This approach enhances code reusability and simplifies dependency management for complex MQL5 projects. It demonstrates how KnitPkg can be used to link different components effectively, enabling robust and scalable development.

## Features

*   **KnitPkg Dependency Management**: Demonstrates how a package can be structured to export functionality 
from a library, making it discoverable and manageable via the KnitPkg CLI.
*   **Facilitates Library Consumption**: Simplifies the process for other KnitPkg projects to utilize functions 
from compiled MQL5 and/or DLL libraries, abstracting away the complexities of direct library linking.
*   **Library Stub Generation**: Provides header files with `#import` directives, allowing MQL5 projects to 
call functions from `@douglasrechia/calclibimp` compiled `.ex5` library.
*   **Decoupling of Interface and Implementation**: Separates the function declarations from their actual 
implementation, promoting a cleaner architectural design.
*   **Unit Testing**: Includes unit tests to verify that the library stubs correctly link to the underlying 
implementation and that the exported functions behave as expected.

## Prerequisites

To use this project, you will need:

1.  **MetaTrader 5**: With MetaEditor 5 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.  **`CalcLibImp.ex5`**: The compiled library from the 
[`@douglasrechia/calclibimp`](https://forge.mql5.io/DouglasRechia/@douglasrechia/calclibimp.git) project must be 
present in your MetaTrader's `MQL5/Libraries` directory. This package provides the stubs for that specific 
library.

## Adding `calclib` as a dependency in your project

To incorporate the latest stable release of `calclib` into your KnitPkg project, use the `add` command to include it as a dependency in your `knitpkg.yaml` file:

```bash
kp add @douglasrechia/calclib
```

Note that the caret (^) prefixing the version number in the `knitpkg.yaml` manifest indicates that your project will receive minor and patch updates for `calclib` during installation commands.

After adding the dependency, execute `kp install` to download `calclib` for prompt use. For reproducible builds, you may opt to use `kp install --locked` to adhere to the locked version. Refer to the KnitPkg documentation for additional information.

## Unit Tests

This package includes unit tests to verify that the `SMA_Close_TimeSeries` stub correctly links to the `CalcLibImp.ex5` library and returns accurate results. 

To run the unit tests:

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

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

cd calclib

# Compile the test script
kp compile

# Close MetaTrader and launch it again (needed to refresh navigator Scripts). Open any chart you want.
# The compiled binary `UnitTests.ex5` will appear in MetaTrader navigator under the Scripts/calclib entry.
# Double‑click it to run the tests. See test results 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.*