Skip to content

05-mcpp-toml.md

Latest commit

 

History

History
292 lines (222 loc) · 5.97 KB

05-mcpp-toml.md

File metadata and controls

292 lines (222 loc) · 5.97 KB

mcpp.toml 工程文件指南

mcpp.toml 是 mcpp 构建工具的项目配置文件,类似 Cargo 的 Cargo.toml 或 Node 的 package.json。放在项目根目录下,mcpp build 会自动发现并读取它。

1. 最小化示例

mcpp 的设计原则是 约定优于配置 —— 大多数字段都有合理默认值,最简单的 mcpp.toml 只需几行:

1.1 可执行程序（最简）

[package]
name    = "hello"
version = "0.1.0"

mcpp 自动推断:

  • 源文件: src/**/*.{cppm,cpp,cc,c}
  • 入口: src/main.cpp → 生成 hello 二进制
  • 标准: C++23
  • 模块: 扫描 export module ... 声明自动建立依赖图

1.2 库项目（最简）

[package]
name    = "mylib"
version = "0.1.0"

[targets.mylib]
kind = "lib"

lib-root 约定:主模块接口默认在 src/mylib.cppm(包名的最后一段)。

2. 完整字段参考

2.1 [package] — 包元数据

[package]
name        = "myapp"              # 包名(必填)
version     = "0.1.0"              # 语义化版本(必填)
description = "My awesome app"     # 简介(可选)
license     = "MIT"                # 许可证(可选)
authors     = ["Alice", "Bob"]     # 作者列表(可选)
repo        = "https://github.com/user/myapp"  # 仓库地址(可选)

2.2 [targets.<name>] — 构建目标

# 可执行程序(默认,有 src/main.cpp 时自动推断)
[targets.myapp]
kind = "bin"
main = "src/main.cpp"       # 可选,默认 src/main.cpp

# 静态库
[targets.mylib]
kind = "lib"

# 共享库
[targets.mylib]
kind = "shared"

2.3 [build] — 构建配置

[build]
sources      = ["src/**/*.cppm", "src/**/*.cpp"]  # 源文件 glob(默认: src/**/*.{cppm,cpp,cc,c})
include_dirs = ["include", "third_party/include"]  # 头文件搜索路径
c_standard   = "c11"              # C 源文件的标准(默认 c11)
cflags       = ["-DFOO=1"]        # 额外 C 编译参数
cxxflags     = ["-DBAR=2"]        # 额外 C++ 编译参数
static_stdlib = true               # 静态链接 libstdc++(默认 true)

glob 排除(! 前缀,mcpp 0.0.4+):

[build]
sources = [
    "src/**/*.cpp",
    "!src/**/*_test.cpp",       # 排除测试文件
    "!src/**/*_fuzzer.cpp",     # 排除 fuzzer
]

2.4 [lib] — 库根模块约定

[lib]
path = "src/capi/lua.cppm"    # 覆盖默认的 lib-root 位置

默认约定:src/<包名最后一段>.cppm(如包名 mcpplibs.cmdline → src/cmdline.cppm）。

2.5 [dependencies] — 运行时依赖

# 默认命名空间(mcpp)下的包
[dependencies]
gtest   = "1.15.2"              # 精确版本
mbedtls = "3.6.1"
ftxui   = "6.1.9"

# 命名空间子表写法
[dependencies.mcpplibs]
cmdline   = "0.0.2"
tinyhttps = "0.2.2"
llmapi    = "0.2.5"

# 路径依赖(本地开发)
[dependencies]
mylib = { path = "../mylib" }

# Git 依赖
[dependencies]
mylib = { git = "https://github.com/user/mylib.git", tag = "v1.0.0" }

SemVer 约束:

[dependencies]
foo = "^1.2.3"      # >= 1.2.3, < 2.0.0 (caret,默认)
bar = "~1.2.3"      # >= 1.2.3, < 1.3.0 (tilde)
baz = "=1.2.3"      # 精确匹配
qux = ">=1.0, <2.0" # 范围组合

2.6 [dev-dependencies] — 测试依赖

[dev-dependencies]
gtest = "1.15.2"

mcpp build 忽略这些;mcpp test 解析并使用。mcpp test 会自动发现 tests/**/*.cpp 并编译为测试二进制。

2.7 [toolchain] — 工具链配置

[toolchain]
default = "gcc@16.1.0"

# 跨编译目标覆盖
[target.x86_64-linux-musl]
toolchain = "gcc@15.1.0-musl"
linkage   = "static"

3. 实战示例

3.1 简单 Hello World

[package]
name    = "hello"
version = "0.1.0"
// src/main.cpp
import std;
int main() { std::println("Hello, mcpp!"); }
mcpp build && mcpp run

3.2 模块化库 + 测试

[package]
name    = "mymath"
version = "1.0.0"

[targets.mymath]
kind = "lib"

[dev-dependencies]
gtest = "1.15.2"
// src/mymath.cppm
export module mymath;
export int add(int a, int b) { return a + b; }
// tests/test_add.cpp
#include <gtest/gtest.h>
import mymath;
TEST(Math, Add) { EXPECT_EQ(add(1, 2), 3); }
mcpp build   # 编译库
mcpp test    # 编译 + 跑测试

3.3 依赖其他包的应用

[package]
name    = "myapp"
version = "0.1.0"

[dependencies]
ftxui = "6.1.9"

[dependencies.mcpplibs]
cmdline = "0.0.2"
llmapi  = "0.2.5"

mcpp 自动:

  1. 从 mcpp-index 下载源码 tarball
  2. 按 [build].include_dirs 传播头文件路径
  3. 传递依赖自动入图(llmapi → tinyhttps → mbedtls 全自动)

3.4 纯 C 库

[package]
name    = "myc"
version = "0.1.0"

[build]
c_standard   = "c99"
include_dirs = ["include"]
sources      = ["src/**/*.c"]

[targets.myc]
kind = "lib"

3.5 混合 C / C++23 模块项目

[package]
name    = "hybrid"
version = "0.1.0"

[build]
include_dirs = ["include"]
c_standard   = "c11"

[dependencies]
lua = "5.4.7"     # 纯 C 库,mcpp 自动用 C 编译器编译 .c 文件

[targets.hybrid]
kind = "bin"

3.6 跨编译静态发布

[package]
name    = "mytool"
version = "1.0.0"

[toolchain]
default = "gcc@16.1.0"

[target.x86_64-linux-musl]
toolchain = "gcc@15.1.0-musl"
linkage   = "static"
mcpp build --target x86_64-linux-musl
# → 产出完全静态链接的二进制,可直接 scp 到任意 Linux x86_64 机器运行

4. 约定与默认值速查

项目 默认值 说明
源文件 src/**/*.{cppm,cpp,cc,c} 自动递归扫描
入口 src/main.cpp 有这个文件就推断为 bin 目标
库根 src/<pkg-tail>.cppm 可用 [lib].path 覆盖
标准 c++23 C++23 模块是一等公民
C 标准 c11 .c 文件自动走 C 编译器
静态 stdlib true 便携二进制
头文件 include/(如果存在） 自动加到 -I
测试 tests/**/*.cpp mcpp test 自动发现
依赖命名空间 mcpp（默认) 平铺写法走默认 ns