A minimal mcpp C++23 module library scaffold — import mcpplibs.mylib;

English - 简体中文 - 繁體中文
mcpp build tool · package index · architecture · Issues

A template repository for building modern C++ modular libraries with the mcpp build tool: one library module, one gtest suite, one consumer example, project templates other people can scaffold from, and CI on Linux / macOS / Windows.

1. Open the template repository: https://github.com/mcpplibs/template
2. Click Use this template to create your own library repository.
3. Clone it locally:

git clone https://github.com/<your-org>/<your-lib>.git
cd <your-lib>

4. Run the scaffold as-is first, to confirm the environment works:

Linux / macOS

curl -fsSL https://d2learn.org/xlings-install.sh | bash

Windows — PowerShell

irm https://d2learn.org/xlings-install.ps1.txt | iex

More about xlings → xlings.d2learn.org

xlings install
mcpp build
mcpp test

5. Then rename mylib to your own library name. The places that matter:

• mcpp.toml — package name, description, repository URL
• src/mylib.cppm — module name and API
• tests/mylib_test.cpp — test cases
• examples/basic/ — dependency and import
• templates/ — the project templates your library ships (see below)
• README*.md and docs/architecture.md — the prose

.
├── .xlings.json              # project tool environment (pins the mcpp version)
├── mcpp.toml                 # package metadata, dependencies, dev-dependencies
├── src/mylib.cppm            # the library module interface
├── tests/mylib_test.cpp      # gtest unit tests, run by `mcpp test`
├── examples/basic/           # standalone consumer package (path dependency)
├── templates/                # project templates shipped WITH the library
│   ├── basic/                #   mcpp new myapp --template mylib
│   └── lib/                  #   mcpp new mylib2 --template mylib:lib
├── tools/template_smoke.sh   # compiles every template against this checkout
├── docs/architecture.md      # structure, mcpp conventions, dependency management
└── .github/workflows/        # ci-linux.yml · ci-macos.yml · ci-windows.yml

The library exports one simple API:

import std;
import mcpplibs.mylib;

int main() {
    std::println("{}", mcpplibs::mylib::hello_mcpplibs());
}

Output:

hello mcpplibs

Relevant files:

• src/mylib.cppm: module interface
• tests/mylib_test.cpp: unit tests
• examples/basic/: consumer example

Run the consumer example:

cd examples/basic
mcpp run

To add a dependency, declare it in mcpp.toml:

[dependencies.mcpplibs]
cmdline = "0.0.2"

then import mcpplibs.cmdline; where you need it. Do not export import a third-party dependency from your root module by default — only do so when your public API genuinely exposes that dependency's types.

A library can ship project templates in templates/. Users scaffold from them with mcpp new, and the template version tracks the library version automatically:

mcpp new --list-templates mylib      # list what this library provides
mcpp new myapp --template mylib      # the default template (basic)
mcpp new mylib2 --template mylib:lib # pick one explicitly

This repository ships two:

Layout of a template — templates are pure data, rendered and copied, with no hooks and no script execution:

templates/<name>/
├── template.toml      # metadata: description, default = true, post_message
├── mcpp.toml.in       # `.in` files are rendered, then the suffix is stripped
└── src/main.cpp.in    # everything else is copied verbatim

The placeholder vocabulary is owned by mcpp and deliberately small:

Exactly one template may declare default = true in its template.toml; that is the one --template mylib picks when no :<template> is given. Verify templates before a release exists in the index with:

bash tools/template_smoke.sh

It renders each template the way mcpp new does, repoints the dependency at this checkout, and builds it. CI runs it on all three platforms.

During development, or inside the same repository, use a local path:

[dependencies]
mylib = { path = "../mylib" }

Before the library reaches a package index, a Git repository works too:

[dependencies]
mylib = { git = "https://github.com/mcpplibs/mylib.git", tag = "v0.1.0" }

Once published to the mcpp package index, name and version are enough:

[dependencies]
mylib = "0.1.0"

Either way, the import stays the same:

import mcpplibs.mylib;

mcpp-index is the default package index — every package there is one pkgs/<initial>/<name>.lua descriptor. mcpp generates yours from mcpp.toml:

mcpp publish --dry-run   # package a tarball, hash it, print the descriptor — upload nothing
mcpp emit xpkg -o mylib.lua   # just the descriptor, no packaging

--dry-run also prints the remaining steps with your project's real URLs filled in: tag and push, attach target/dist/<name>-<version>.tar.gz to the GitHub Release, then open a PR adding pkgs/<initial>/<name>.lua to mcpp-index. Useful links along the way:

• Repository: https://github.com/mcpplibs/mcpp-index — browse the packages online at https://mcpplibs.github.io/mcpp-index/
• Contributor docs: docs/README.md · package types · repository & schema · CN mirror
• End-to-end procedure (human or agent): the add-mcpp-index-package skill
• In this repository: .agents/skills/mcpp-index/SKILL.md

A library like this one is a Form A package: your repository already carries mcpp.toml, so the descriptor only declares metadata and a download address. After the PR is merged, mcpp add mylib resolves for everybody.

CI is split per platform, so a macOS or Windows problem can never hide behind a green Linux run. Each workflow walks the same path a new user walks:

Locally that is:

xlings install -y
mcpp build
mcpp test
cd examples/basic && mcpp run
bash tools/template_smoke.sh

This repository ships agent skills under .agents/skills/:

A prompt to get an agent oriented:

Repository: https://github.com/mcpplibs/template

Read .agents/skills/more-details/SKILL.md, .agents/skills/mcpp/SKILL.md,
.agents/skills/mcpp-style-ref/SKILL.md and docs/architecture.md first.

For now, only understand this template's mcpp project structure, module organization,
testing approach and dependency management — do not modify files yet.

When you need more, follow the links in more-details (mcpp docs, mcpp-index,
mcpplibs/cmdline, mcpplibs/llmapi).
Stay mcpp-only; follow the `mcpp test` conventions; do not re-export third-party
dependencies by default. Keep README as the entry point and details in docs/architecture.md.

Real mcpp module libraries worth reading before you design your own:

• mcpplibs/llmapi — a C++23 LLM client (OpenAI-compatible). Read it for: shipping several templates/, multilingual READMEs, a library split across many .cppm files, and depending on another mcpplibs package.
• mcpplibs/cmdline — a small command-line parsing library. Read it for: the minimal shape of a single-module library with tests and examples — the closest thing to what this template grows into.

• mcpp build tool: https://github.com/mcpp-community/mcpp
• mcpp docs: https://github.com/mcpp-community/mcpp/tree/main/docs
• Getting started: https://github.com/mcpp-community/mcpp/blob/main/docs/00-getting-started.md
• mcpp.toml guide: https://github.com/mcpp-community/mcpp/blob/main/docs/05-mcpp-toml.md
• mcpp package index: https://github.com/mcpplibs/mcpp-index · https://mcpplibs.github.io/mcpp-index/
• mcpplibs organization: https://github.com/mcpplibs
• This template: https://github.com/mcpplibs/template
• C++23 module style reference: https://github.com/mcpp-community/mcpp-style-ref
• xlings tool environment: https://github.com/openxlings/xlings