calclibimp/README.md

# Library calclibimp

**Reusable MQL5 library (.ex5) demo using KnitPkg packages**  
*MIT License*

---

## What is this?

`calclibimp` is a **demonstration project** that showcases how to build a reusable MetaTrader 5 **MQL5 Library** (a compiled `.ex5`) using KnitPkg.

It compiles a library that implements `SMA_Close_TimeSeries`, a helper that calculates a rolling Simple Moving Average (SMA) for a given symbol and timeframe. The goal is to demonstrate how to encapsulate logic into a compiled library that can be imported by other projects (for example, `@douglasrechia/calclib`).

This project is intended **only as an educational example** of how to structure a library project, manage dependencies, and compile MQL5 code with KnitPkg. It is **not** meant to be a production-grade trading system.

## Prerequisites

To build and use 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).
3.  **KnitPkg homepage**: See [https://knitpkg.dev](https://knitpkg.dev) for an overview and [https://docs.knitpkg.dev](https://docs.knitpkg.dev) for documentation.

---

## Features

- **Library type** (`type: library`) — a compiled `.ex5` library project (not a package)
- **SMA library function** — implements `SMA_Close_TimeSeries`
- **Dependency installation** — uses the KnitPkg registry to resolve and download dependencies
- **Dependencies**
  - `@douglasrechia/calc` — technical analysis functions (SMA, etc.)
  - `@douglasrechia/bar` — time series data access utilities
- **MQL5 target** — designed for MetaTrader 5
- **Compile support** — `kp compile` builds the library into an `.ex5` binary

---

## One-command download/build via the registry

You can use `kp get` to query the registry for metadata and automatically download/build the latest stable version.

Example (run from your MetaTrader *Data Folder* root if you have MetaTrader installed in more than one location):

```bash
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>"

kp get mql5 @douglasrechia/calclibimp
```

---

## Exploring the project locally (optional)

If you want to learn how to structure your own library with KnitPkg packages, clone this repository into your MetaTrader `Libraries` folder.

### 1) Clone into MetaTrader `Libraries` folder (example)

```bash
# Go to your MetaTrader 'Libraries' directory.
# Tip: in MetaEditor, right-click the `Libraries` folder and choose "Open Folder".
cd "C:\Users\username\AppData\Roaming\MetaQuotes\Terminal\<TERMINAL_ID>\MQL5\Libraries"

git clone https://forge.mql5.io/DouglasRechia/calclibimp.git
cd calclibimp
```

### 2) Install dependencies

```bash
kp install
```

### 3) Compile

```bash
kp compile
```
---

## License

This project is released under the **MIT License**. See `LICENSE` for details.

---

## Disclaimer

This code is provided **as-is**, for **educational purposes only**.  
No warranty (express or implied) is provided. Use at your own risk.