DouglasRechia/calclib
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
calclib/README.md
Douglas Rechia 2c6a084d6f Version 1.0.0
2026-02-03 10:08:09 -03:00

4.5 KiB
Raw Permalink Blame History

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.
  3. CalcLibImp.ex5: The compiled library from the @douglasrechia/calclibimp 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:

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:

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