83 lines
No EOL
4.5 KiB
Markdown
83 lines
No EOL
4.5 KiB
Markdown
# 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.* |