feat: lib-root convention (Levels 1+2)#15
Merged
Sunrisepeak merged 1 commit intomainfrom May 9, 2026
Merged
Conversation
…].path`)
Introduces a Cargo-style "lib root" — a single primary module-interface
file that aggregates the package's public API. Two recognised forms:
* Convention (no config): `src/<package-tail>.cppm` where
`<package-tail>` is the last `.`-segment of `[package].name`.
Examples:
mcpplibs.tinyhttps → src/tinyhttps.cppm
mcpplibs.cmdline → src/cmdline.cppm
gtest → src/gtest.cppm
* Override: `[lib] path = "src/foo.cppm"` (cargo-style).
Either way, the file must `export module <full-package-name>;` (no
`:partition` suffix) — partitions go in sibling files and are
re-exported from the lib root, mirroring Rust's `lib.rs` aggregating
`pub mod`s.
Lib-root checks fire only for projects that ship a `kind = "lib"` (or
`shared`) target. Pure binaries (mcpp itself, scaffolded `mcpp new`)
are unaffected.
Validation policy:
- explicit `[lib].path` pointing at a missing file → ERROR
- convention miss (no `src/<tail>.cppm`) → WARNING (soft on-ramp;
existing libs aren't broken — they get a polite reminder)
- lib-root file exists but `export module …:partition;` → ERROR
(lib root must be the primary module, never a partition)
- lib-root file exports a different module name than [package].name
→ ERROR
Existing libs that already follow the convention (mcpplibs.cmdline,
mcpplibs.templates, mcpplibs.tinyhttps) keep working unchanged. The
soft warning gives anyone who doesn't a clear path to compliance
without a hard break.
Coverage: 4 manifest unit tests + 5 validate tests + a manual smoke
on tinyhttps (zero warnings) and a deliberate file-rename
reproduction of the warning path.
2 tasks
Sunrisepeak
added a commit
that referenced
this pull request
May 9, 2026
The v0.0.2 GitHub Release is being re-issued with the same version number to fold in three improvements that landed against main *after* the original tag was pushed: * fix(modgraph): partition import scanner no longer concatenates the unit's own `:partition` into imported names (PR #14) * feat: lib-root convention `src/<package-tail>.cppm` + optional `[lib].path` (PR #15) CHANGELOG's [0.0.2] entry is amended in place to capture them, since no v0.0.3 has been published yet and we're keeping the version number stable while the project is still pre-1.0. After this PR merges, the v0.0.2 git tag and GitHub Release will be re-pointed at the new HEAD.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a Cargo-style lib root — a single primary module-interface
file aggregating a package's public API.
Two recognised forms:
src/<package-tail>.cppmwhere<package-tail>is the last dotted segment of[package].name:mcpplibs.tinyhttps→src/tinyhttps.cppmmcpplibs.cmdline→src/cmdline.cppmgtest→src/gtest.cppm[lib] path = "src/foo.cppm"(cargo-style).Either way the file must
export module <full-package-name>;—partitions go in sibling files and are re-exported from the lib
root, mirroring Rust's
lib.rsaggregatingpub mods.Lib-root validation (only for
kind = "lib"/sharedprojects)[lib].pathpointing at a missing filesrc/<tail>.cppm)export module foo:bar;)[package].namePure-binary projects (mcpp itself,
mcpp new-scaffolded apps) areunaffected.
What this enables (downstream)
[modules].exportsbecomes optional for lib targets — derivablefrom the lib root in a follow-up PR
mcpp publishcan auto-fill xpkgmodulesfrom the lib rootmcpp explainuse lib root as their entryTest plan
mcpp build(worktree)mcpp test— 9/9 unit binaries pass (incl. 4 manifest + 5validate new cases)
mcpplibs/tinyhttps: zero warningssrc/mylib.cppm→src/wrong.cppm): warning fires, build still succeeds