Skip to content

Projects vs packages

In KnitPkg, project and package are closely related concepts, but they are not the same thing.

  • A project is any code repository managed by KnitPkg. It follows a well-defined directory structure, can be built with KnitPkg commands, and (if you want) can be published to the registry.
  • A package is a project that has been published to the registry specifically to be consumed as a dependency by other projects.

In other words:

  • Not every project is a package.
  • Every package is a project.

KnitPkg project

A project is the standard “container”: it can be an indicator, expert, script, library, service, or even a test repository. In MQL projects, your source code typically lives in src/, and KnitPkg automatically generates dependency artifacts (include tree or flat files) under knitpkg/.

A typical layout looks like this:

Project typical directory layout
project_dir/
│   knitpkg.yaml        # Manifest
│   LICENSE             # Optional: license (text format)
│   README.md           # Recommended: README (markup format)
│   .gitignore          # Git ignore
│
├───.knitpkg            # Reserved for KnitPkg use
│   │   config.yaml     # Project-specific configuration
│   │
│   ├───cache           # Code of dependencies downloaded from git repositories
│   └───compile-logs    # Logs generated by MetaEditor compiler
│
├───bin
│       ProjectCode.ex5 # Project compiled binaries (.ex4 for MQL4)
│
├───knitpkg
│   │   lock.json       # Lock file
│   │
│   ├───include         # Include mode (autogenerated): resolved headers from dependencies
│   │   └───organization
│   │       └───project_name
│   │               ProjectHeader1.mqh
│   │               ProjectHeader2.mqh
│   │               ...
│   │
│   └───flat            # Flat mode (autogenerated): resolved flattened headers from dependencies
│           ProjDep_flat.mqh
│
└───src                 # Project source code
        ProjectCode.mq5 # Source code of indicator, expert, etc (.mq4 for MQL4)
        ProjectCode.mqh # Entrypoint or additional regular headers

Do not edit knitpkg/ by hand

The knitpkg/ directory is fully generated by KnitPkg (lock file, include tree, flat files, etc.).
As a developer, you should treat it as read-only: do not manually change its contents, because they can be regenerated/overwritten by commands like kp install.

KnitPkg package

A package is a project whose main purpose is to be imported by other projects via dependencies:. That means it must organize its code in a predictable way so other people (or your other projects) can #include its headers.

A typical layout looks like:

Package typical directory layout
project_dir/
│   knitpkg.yaml        # Manifest
│   LICENSE             # Optional: license (text format)
│   README.md           # Recommended: README (markdown format)
│   .gitignore          # Git ignore
│
├───.knitpkg            # Reserved for KnitPkg use
│   │   config.yaml     # Project-specific configuration
│   │
│   ├───cache           # Code of dependencies downloaded from git repositories
│   └───compile-logs    # Logs generated by MetaEditor compiler
│
├───bin
│       UnitTests.ex5   # Unit test binaries (.ex4 for MQL4)
│
├───knitpkg
│   │   lock.json       # Lock file
│   │
│   ├───autocomplete    # Autocomplete (autogenerated): header for composite packages
│   │       autocomplete.mqh
│   │
│   └───include         # Package code here
│       └───organization
│           └───project_name
│                   ProjectHeader1.mqh
│                   ProjectHeader2.mqh
│                   ...
│
└───tests
        UnitTests.mq5   # Unit test source (.mq4 for MQL4)

Where package code must live

When the project type is package, the package’s public headers must be placed under:

  • knitpkg/include/<organization>/<project_name>/

This is the only place under knitpkg/** where you should add your own code for a package.
Everything else under knitpkg/ is generated by KnitPkg (for example, lock.json and knitpkg/autocomplete/).

Use your organization name as the root namespace

As a recommendation, write your package code under a namespace that matches your organization name (for example, namespace douglasrechia { ... }).

The directory layout knitpkg/include/<organization>/<project_name>/ prevents header path conflicts during installation, so files from different packages are not overwritten.

Namespaces complement that by preventing symbol conflicts when dependencies are installed and made available together to the consuming project.

MQL4 vs MQL5

Unfortunately, MQL4 does not support namespaces. Namespaces are available only in MQL5.

Quick mental model

  • Project: “My repo that I build/run” (indicator, EA, script, library, etc.)
  • Package: “A project designed to be depended on” (reusable headers published to the registry)