diff --git a/.agents/skills/README.md b/.agents/skills/README.md index b29904b..582b5b4 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -1,7 +1,7 @@ -# mcpplibs template — Agent Skills +# CMP — Agent Skills -Skills that help an agent understand this mcpp/mcpplibs module-library template, look things up -upstream, and follow the mcpp-style-ref rules when writing or reviewing Modern/Module C++. +Skills that help an agent understand the CMP mcpp/C++23 module project, look things up upstream, +and follow the mcpp-style-ref rules when writing or reviewing Modern/Module C++. ## Available Skills @@ -30,7 +30,7 @@ done Or install them as personal skills: ```bash -ln -s /path/to/mcpp-template/.agents/skills/mcpp ~/.cursor/skills/mcpp +ln -s /path/to/cmp/.agents/skills/mcpp ~/.cursor/skills/mcpp ``` Claude Code and other agents that read `.agents/skills/` pick them up from this directory diff --git a/.agents/skills/mcpp-style-ref/SKILL.md b/.agents/skills/mcpp-style-ref/SKILL.md index 956c4e3..921858d 100644 --- a/.agents/skills/mcpp-style-ref/SKILL.md +++ b/.agents/skills/mcpp-style-ref/SKILL.md @@ -143,14 +143,14 @@ mcpp --version > xlings详细信息可参考 [xlings](https://github.com/openxlings/xlings) 文档。 -## 示例项目创建 +## 当前项目结构 参考本仓库 `src/` 目录结构： - `.xlings.json`：声明项目工具环境 - `mcpp.toml`：声明 `[package]` 与测试依赖；简单库目标可由 mcpp 从 `src/*.cppm` 自动推断 -- `src/mylib.cppm`：库主模块接口，默认 `export module mcpplibs.mylib;` -- `tests/mylib_test.cpp`：`mcpp test` 自动发现的 gtest 测试；不要定义 `main()` +- `src/cmp.cppm`：库主模块接口，声明 `export module mcpplibs.cmp;` +- `tests/cmp_test.cpp`：`mcpp test` 自动发现的 gtest 导入测试；不要定义 `main()` - `examples/basic/`：独立 mcpp consumer 包，通过 path 依赖引用根库 构建： diff --git a/.agents/skills/more-details/SKILL.md b/.agents/skills/more-details/SKILL.md index 6408209..6c62a04 100644 --- a/.agents/skills/more-details/SKILL.md +++ b/.agents/skills/more-details/SKILL.md @@ -27,16 +27,14 @@ docs, and actual command output. ## This Repository -- `README.md` (`README.zh.md`, `README.zh.hant.md`) — entry point, quick start, agent prompt, links. -- `docs/architecture.md` (`.zh.md`, `.zh.hant.md`) — structure, mcpp conventions, dependencies, templates, CI. +- `README.md` (`README.zh.md`, `README.zh.hant.md`) — entry point, current status, boundaries, roadmap, links. +- `docs/architecture.md` (`.zh.md`, `.zh.hant.md`) — current structure, mcpp conventions, runtime boundaries, CI. - `.xlings.json` — the project tool environment (which mcpp version builds this). - `mcpp.toml` — package metadata, dependencies, dev-dependencies. -- `src/mylib.cppm` — the library module interface. -- `tests/mylib_test.cpp` — a gtest suite matching the `mcpp test` conventions. -- `examples/basic/` — a standalone consumer package. -- `templates/` — project templates shipped with the library (`basic`, `lib`). -- `tools/template_smoke.sh` — renders and builds every template against this checkout. -- `.github/workflows/ci-{linux,macos,windows}.yml` — per-platform CI. +- `src/cmp.cppm` — the import-only CMP root module interface. +- `tests/cmp_test.cpp` — the gtest import smoke test. +- `examples/basic/` — a standalone path-dependency consumer. +- `.github/workflows/ci-{linux,macos,windows}.yml` — per-platform build, test, and example CI. ## Upstream @@ -57,7 +55,7 @@ Use these to confirm: - Package index: https://github.com/mcpplibs/mcpp-index · https://mcpplibs.github.io/mcpp-index/ - mcpplibs organization: https://github.com/mcpplibs -- Reference library — small and close to this template: https://github.com/mcpplibs/cmdline +- Reference library — small, with a package/module layout close to CMP's current baseline: https://github.com/mcpplibs/cmdline - Reference library — templates, i18n, multi-module: https://github.com/mcpplibs/llmapi Check the index before adding a dependency; read `cmdline`/`llmapi` when you want to see how a @@ -76,7 +74,7 @@ public API, and tests without a custom `main()`. - xlings: https://github.com/openxlings/xlings -This template pins its tools in `.xlings.json`. After entering the repository: +This project pins its tools in `.xlings.json`. After entering the repository: ```bash xlings install # installs mcpp into the PROJECT environment (xlings install mcpp -g for global) @@ -85,11 +83,10 @@ mcpp --version ## Common Tasks -- **Understand the template** → `README.md` and `docs/architecture.md`. +- **Understand CMP's current baseline** → `README.md` and `docs/architecture.md`. - **Confirm an `mcpp.toml` field** → `mcpp.toml`, the [`mcpp`](../mcpp/SKILL.md) skill, then upstream `docs/05-mcpp-toml.md`. - **Add a dependency** → the [`mcpp-index`](../mcpp-index/SKILL.md) skill, then `mcpplibs/cmdline` for a real example. - **Add a module API** → `mcpp-style-ref`, then edit `src/*.cppm`. -- **Add a test** → follow `tests/mylib_test.cpp`, verify with `mcpp test`. +- **Add a test** → follow `tests/cmp_test.cpp`, verify with `mcpp test`. - **Add an example** → follow `examples/basic/` — its own `mcpp.toml` with a path dependency. -- **Add or change a template** → `templates//`, verify with `bash tools/template_smoke.sh`. - **Publish the library** → the [`mcpp-index`](../mcpp-index/SKILL.md) skill. diff --git a/.github/workflows/ci-linux.yml b/.github/workflows/ci-linux.yml index b093b6c..3a811a3 100644 --- a/.github/workflows/ci-linux.yml +++ b/.github/workflows/ci-linux.yml @@ -1,8 +1,7 @@ name: ci-linux -# Linux CI — the same path a user walks after `Use this template`: -# xlings install (project env, pinned by .xlings.json) → build → test → -# example → templates/ smoke. +# Linux CI — the same path a contributor walks: +# xlings install (project env, pinned by .xlings.json) → build → test → example. # # Split per OS on purpose (ci-macos.yml / ci-windows.yml are the same flow): # one badge and one log per platform, and a macOS/Windows toolchain problem @@ -62,6 +61,3 @@ jobs: run: | cd examples/basic mcpp run - - - name: Smoke-test templates/ - run: bash tools/template_smoke.sh diff --git a/.github/workflows/ci-macos.yml b/.github/workflows/ci-macos.yml index 7878456..a33d338 100644 --- a/.github/workflows/ci-macos.yml +++ b/.github/workflows/ci-macos.yml @@ -53,6 +53,3 @@ jobs: run: | cd examples/basic mcpp run - - - name: Smoke-test templates/ - run: bash tools/template_smoke.sh diff --git a/.github/workflows/ci-windows.yml b/.github/workflows/ci-windows.yml index e2ec287..e4cb52f 100644 --- a/.github/workflows/ci-windows.yml +++ b/.github/workflows/ci-windows.yml @@ -2,7 +2,7 @@ name: ci-windows # Windows CI — same flow as ci-linux.yml. xlings bootstraps from PowerShell; # everything after it runs in bash (git-bash ships on the runner), so the -# build/test/example/template steps stay byte-identical to the other two +# build/test/example steps stay byte-identical to the other two # platforms instead of forking into a second dialect. on: @@ -63,7 +63,3 @@ jobs: run: | cd examples/basic mcpp run - - - name: Smoke-test templates/ - shell: bash - run: bash tools/template_smoke.sh diff --git a/.gitignore b/.gitignore index 1b47574..0f41629 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,12 @@ compile_commands.json # xlings project environment .xlings/ +# Local tools and editor state +.cache/ +/.clice/ +/.rpiv/ +/.vscode/ + # Compiled Object files *.slo *.lo diff --git a/README.md b/README.md index 7d43c8d..8a7467d 100644 --- a/README.md +++ b/README.md @@ -1,298 +1,145 @@ -# mcpplibs.mylib +# CMP -> A minimal mcpp C++23 module library scaffold — `import mcpplibs.mylib;` +> **Coroutine Machine Process** — a C++23 coroutine runtime project. [![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23) -[![Module](https://img.shields.io/badge/module-ok-green.svg)](https://en.cppreference.com/w/cpp/language/modules) +[![Module](https://img.shields.io/badge/module-mcpplibs.cmp-green.svg)](https://en.cppreference.com/w/cpp/language/modules) [![License](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE) -| **English** - [简体中文](README.zh.md) - [繁體中文](README.zh.hant.md) | -|:---:| -| [mcpp build tool](https://github.com/mcpp-community/mcpp) · [package index](https://github.com/mcpplibs/mcpp-index) · [architecture](docs/architecture.md) · [Issues](https://github.com/mcpplibs/template/issues) | -| [![ci-linux](https://github.com/mcpplibs/template/actions/workflows/ci-linux.yml/badge.svg?branch=main)](https://github.com/mcpplibs/template/actions/workflows/ci-linux.yml) [![ci-macos](https://github.com/mcpplibs/template/actions/workflows/ci-macos.yml/badge.svg?branch=main)](https://github.com/mcpplibs/template/actions/workflows/ci-macos.yml) [![ci-windows](https://github.com/mcpplibs/template/actions/workflows/ci-windows.yml/badge.svg?branch=main)](https://github.com/mcpplibs/template/actions/workflows/ci-windows.yml) | +**English** · [简体中文](README.zh.md) · [繁體中文](README.zh.hant.md) -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. +[mcpp](https://github.com/mcpp-community/mcpp) · [Architecture](docs/architecture.md) · +[Issues](https://github.com/mcpplibs/cmp/issues) -## Quick Start +[![ci-linux](https://github.com/mcpplibs/cmp/actions/workflows/ci-linux.yml/badge.svg?branch=main)](https://github.com/mcpplibs/cmp/actions/workflows/ci-linux.yml) +[![ci-macos](https://github.com/mcpplibs/cmp/actions/workflows/ci-macos.yml/badge.svg?branch=main)](https://github.com/mcpplibs/cmp/actions/workflows/ci-macos.yml) +[![ci-windows](https://github.com/mcpplibs/cmp/actions/workflows/ci-windows.yml/badge.svg?branch=main)](https://github.com/mcpplibs/cmp/actions/workflows/ci-windows.yml) -1. Open the template repository: https://github.com/mcpplibs/template -2. Click [**Use this template**](https://github.com/new?template_name=template&template_owner=mcpplibs) to create your own library repository. -3. Clone it locally: +> [!IMPORTANT] +> CMP is currently in its **bootstrap stage**. The package exports the root module +> `mcpplibs.cmp`, but it does not provide coroutine runtime APIs yet. -```bash -git clone https://github.com//.git -cd -``` +CMP is being built as a modern coroutine runtime and library on standard stackless C++ +coroutines. The intended direction is an explicit `co_await` model that can grow, in small +verified steps, toward scheduling, timers, asynchronous I/O, cancellation, and safe handling of +blocking work. -4. Run the scaffold as-is first, to confirm the environment works: +## Why CMP? -
-Click for the xlings install command +The name stands for **Coroutine Machine Process**. CMP uses **C** as the intended name for a +lightweight coroutine execution unit. This is analogous to Go runtime's **G** as a naming and +mental-model inspiration only; it is not a claim that a future CMP task is already equivalent to +a goroutine. -**Linux / macOS** -```bash -curl -fsSL https://d2learn.org/xlings-install.sh | bash -``` +The project is guided by a few principles: -**Windows — PowerShell** -```powershell -irm https://d2learn.org/xlings-install.ps1.txt | iex -``` +- use C++23 standard stackless coroutines and C++ Modules; +- keep suspension explicit through `co_await` and purpose-built awaiters; +- develop runtime pieces incrementally, with tests and small reviewable changes; +- support more than server workloads; +- keep mcpp as the single source of build and package truth. -> More about xlings → [xlings.d2learn.org](https://xlings.d2learn.org) +## Runtime Boundaries -
- -```bash -xlings install -mcpp build -mcpp test -``` - -> [!NOTE] -> `xlings install` installs mcpp into the **project environment**, at the version pinned by -> [`.xlings.json`](.xlings.json) — so every contributor and CI build uses the same mcpp. -> To install mcpp **globally** instead, run `xlings install mcpp -g`. - -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 - -## Repository Layout - -```text -. -├── .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 -``` +C++ standard coroutines are a language mechanism, not a complete runtime. CMP therefore does not +promise that: -## Library Example +- a task is automatically equivalent to a Go goroutine; +- an arbitrary blocking call becomes non-blocking; +- coroutine switching is safe directly inside a signal handler; +- M:N scheduling, work stealing, timers, cancellation, or async I/O already exist. -The library exports one simple API: +Those capabilities must be designed and verified individually. The expected direction is +explicit async I/O awaiters, a dedicated blocking pool, and cooperative safe points. -```cpp -import std; -import mcpplibs.mylib; - -int main() { - std::println("{}", mcpplibs::mylib::hello_mcpplibs()); -} -``` +## Quick Start -Output: +Install [xlings](https://github.com/openxlings/xlings), then install the mcpp version pinned by +[`.xlings.json`](.xlings.json): -```text -hello mcpplibs +```bash +xlings install +mcpp --version +mcpp build +mcpp test ``` -Relevant files: - -- `src/mylib.cppm`: module interface -- `tests/mylib_test.cpp`: unit tests -- `examples/basic/`: consumer example - -Run the consumer example: +Run the standalone consumer: ```bash cd examples/basic mcpp run ``` -To add a dependency, declare it in `mcpp.toml`: - -```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. +The example exits successfully without output. Its purpose is to prove that an independent mcpp +package can resolve the path dependency and import `mcpplibs.cmp`. -## Project Templates +## Current Module -A library can ship **project templates** in `templates/`. Users scaffold from them with -`mcpp new`, and the template version tracks the library version automatically: +```cpp +import mcpplibs.cmp; -```bash -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 +int main() { + return 0; +} ``` -This repository ships two: +The module deliberately has no public declarations during bootstrap. Future public APIs will use +the namespace `mcpplibs::cmp`. -| Template | Contents | -|---|---| -| `basic` (default) | Minimal console app that imports the library | -| `lib` | A downstream C++23 module library built on this one, with gtest tests | - -Layout of a template — templates are pure data, rendered and copied, with no hooks and no -script execution: +## Repository Layout ```text -templates// -├── 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: - -| Placeholder | Expands to | -|---|---| -| `{{project.name}}` | the name the user passed to `mcpp new` | -| `{{self.name}}` | this library's package name (`mylib`) | -| `{{self.version}}` | this library's resolved version | - -Exactly one template may declare `default = true` in its `template.toml`; that is the one -`--template mylib` picks when no `: