Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/04-mcpp-toml.md
Original file line number Diff line number Diff line change
Expand Up @@ -1920,7 +1920,7 @@ mcpp cache info <pkg>@<ver> # one entry, including the key inputs it was
mcpp cache verify # every entry's file list against the disk
mcpp cache gc --max-size 5GiB # LRU-collect package and host tool entries to a budget
mcpp cache gc --older-than 30d # ...or by how long since they were last used
mcpp cache clean [--deps|--std|--tools|--all|--legacy]
mcpp cache clean [--deps|--std|--tools|--work|--all|--legacy]
```

The on-disk entry layout is versioned. An mcpp release that changes it retires
Expand Down
13 changes: 13 additions & 0 deletions docs/09-commands-by-scenario.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ them. Confusing them costs a full rebuild.
|---|---|---|---|
| `target/<triple>/<fingerprint>/`, `target/.build-mcpp/{out,host}/` | one project | a configuration fingerprint changes and opens a new directory; a build program's outputs and the build programs are kept per configuration | `mcpp clean`, `mcpp clean --stale` |
| the build cache (`mcpp cache dir`) | the whole machine | any project compiles a dependency or a `std` module, or builds a host tool, or compiles the `mcpp` module its build program imports | collected after a build when unused for `[cache] unused_days`; `mcpp cache gc`, `mcpp cache prune`, `mcpp cache clean` |
| the work directories of plans (`<home>/cache/{build-database,pack-formats,publish-plan}/`) | the whole machine, one per project | `mcpp emit build-database`, `mcpp pack --list-formats` or `mcpp publish` plans a project | collected with the build cache's entries; `mcpp cache clean --work` |

`mcpp clean` removes `target/` entirely, and the next build recompiles
everything. `mcpp clean --stale` removes only the fingerprint directories that
Expand Down Expand Up @@ -111,6 +112,18 @@ warning states both (2026.11.8.1+). `mcpp cache prune` and `mcpp cache gc
--older-than` collect `std` module entries by age as well; `gc --max-size`
budgets packages and host tools, not `std` modules (2026.11.8.1+).

`mcpp emit build-database`, `mcpp pack --list-formats` and `mcpp publish`'s
check of a library's pins plan a project without writing into it, each in a work directory of the home, one
per project: `<home>/cache/build-database/`, `cache/pack-formats/` and
`cache/publish-plan/`. A plan records its use in the directory's `.mcpp-plan`,
whose one line is the project root. `mcpp cache list` shows each directory as
an entry of kind `work`, named by the command and that project; the
collection after a build, `mcpp cache prune`, `mcpp cache gc --older-than` and
`gc --max-size` collect it by last use, as they collect a package entry; and
`mcpp cache clean --work` (or `--all`) empties all three areas. A directory
written before the record is dated by its own time. Removing one costs the
next plan of that project nothing but writing it again (mcpp#969).

## The versions a package publishes

`mcpp search` matches a substring and appends what each hit publishes, merged
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/04-mcpp-toml.md
Original file line number Diff line number Diff line change
Expand Up @@ -1708,7 +1708,7 @@ mcpp cache info <pkg>@<ver> # one entry, including the key inputs it was
mcpp cache verify # every entry's file list against the disk
mcpp cache gc --max-size 5GiB # LRU-collect package and host tool entries to a budget
mcpp cache gc --older-than 30d # ...or by how long since they were last used
mcpp cache clean [--deps|--std|--tools|--all|--legacy]
mcpp cache clean [--deps|--std|--tools|--work|--all|--legacy]
```

磁盘上的条目布局是版本化的。一个改变了它的 mcpp 发布版,会一次性
Expand Down
9 changes: 9 additions & 0 deletions docs/zh/09-commands-by-scenario.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
|---|---|---|---|
| `target/<三元组>/<指纹>/`、`target/.build-mcpp/{out,host}/` | 单个工程 | 一个配置指纹变化,开出一个新目录;构建程序的输出与构建程序按配置保存 | `mcpp clean`、`mcpp clean --stale` |
| 构建缓存(`mcpp cache dir`) | 整台机器 | 任何工程编译一个依赖、一个 `std` 模块,或构建一个 host 工具,或编译其构建程序 import 的 `mcpp` 模块 | 构建后回收 `[cache] unused_days` 内未使用的条目;`mcpp cache gc`、`mcpp cache prune`、`mcpp cache clean` |
| 规划的工作目录(`<home>/cache/{build-database,pack-formats,publish-plan}/`) | 整台机器,每个工程一个 | `mcpp emit build-database`、`mcpp pack --list-formats` 或 `mcpp publish` 规划一个工程 | 与构建缓存的条目一同回收;`mcpp cache clean --work` |

`mcpp clean` 整个删掉 `target/`,下次构建重编一切。`mcpp clean --stale`
只删已无构建记录使用的指纹目录,在用的配置保留。每个配置目录在 `uses.list` 中
Expand Down Expand Up @@ -90,6 +91,14 @@ host 工具条目。一份 `std` BMI 被机器上每个工程共享,实现以"
与 `mcpp cache gc --older-than` 也按年龄收集 `std` 模块条目;`gc --max-size` 只对包与宿主工具做
预算(2026.11.8.1+)。

`mcpp emit build-database`、`mcpp pack --list-formats` 与 `mcpp publish` 对库的版本钉的检查规划工程而不写入工程,
各自在 home 的一个工作目录中进行,每个工程一个:`<home>/cache/build-database/`、`cache/pack-formats/`
与 `cache/publish-plan/`。规划把一次使用记在目录的 `.mcpp-plan` 上,该文件只有一行,即工程根。
`mcpp cache list` 把每个目录列为 `work` 类条目,以命令与该工程命名;构建后的回收、`mcpp cache prune`、
`mcpp cache gc --older-than` 与 `gc --max-size` 按最后使用时间回收它,与回收包条目相同;
`mcpp cache clean --work`(或 `--all`)清空这三处。早于该记录写出的目录以目录自身的时间计。
移除一个目录,该工程的下一次规划只需重新写出它(mcpp#969)。

## 一个包已发布的版本

`mcpp search` 按子串匹配,并在每个命中行后附上该包发布的版本 —— 跨描述符
Expand Down
107 changes: 103 additions & 4 deletions src/bmi_cache/maintenance.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@
// $MCPP_HOME/build-cache/v1/std/<identity>/std-module.json
// $MCPP_HOME/build-cache/v1/tool/<index>/<pkg>@<ver>/<key>/entry.json
// (a host tool, mcpp.build.tool_store; last use = the record's time)
// $MCPP_HOME/cache/{build-database,pack-formats,publish-plan}/<key>/.mcpp-plan
// (the work directory of a plan that describes; last use = the record's time)
//
// Two things this file did wrong before the layout change and that the new
// entry.json fixes:
Expand All @@ -23,6 +25,7 @@ export module mcpp.bmi_cache.maintenance;

import std;
import mcpp.home;
import mcpp.home.files; // mark_used
import nlohmann.json;
import mcpp.libs.toml;
import mcpp.ui;
Expand Down Expand Up @@ -94,6 +97,58 @@ export std::optional<std::uintmax_t> parse_size(std::string_view v) {
return std::nullopt;
}

// THE WORK DIRECTORIES OF PLANS THAT DESCRIBE (mcpp#969). `mcpp emit
// build-database`, `mcpp pack --list-formats` and the pin check of `mcpp
// publish` plan a project without writing into it (PrepareIntent::Describe),
// each in a directory of the home, `cache/<area>/<key>`, one per project.
// Nothing removed one: a home measured on 2026-11-19 held 626 of them, 3.4 GB,
// most of them for projects that no longer existed. A plan states its use on
// the directory's record, and `cache list`, `gc`, `prune` and the collection
// after a build treat each directory as an entry. Removing one costs nothing
// but the next plan's writing it again (SPEC-005 R2.1).
export enum class PlanArea { BuildDatabase, PackFormats, PublishPlan };

namespace {

struct PlanAreaInfo {
PlanArea area;
std::string_view dir; // under `<home>/cache/`
std::string_view command; // what plans there, as `cache list` names it
};

constexpr std::array<PlanAreaInfo, 3> kPlanAreas{{
{PlanArea::BuildDatabase, "build-database", "emit build-database"},
{PlanArea::PackFormats, "pack-formats", "pack --list-formats"},
{PlanArea::PublishPlan, "publish-plan", "publish"},
}};

// The record whose time is the directory's last use (mcpp::home::mark_used);
// its one line is the project root the directory plans.
constexpr std::string_view kPlanRecord = ".mcpp-plan";

std::filesystem::path plan_area_root(const PlanAreaInfo& area) {
return mcpp::home::root() / "cache" / area.dir;
}

} // namespace

// The work directory of a plan of `area` named `key`, created, with its use
// stated: the record is written when the directory is new and its time set to
// now otherwise. `project` is what `cache list` names the directory by.
export std::filesystem::path plan_work_dir(PlanArea area, std::string_view key,
const std::filesystem::path& project) {
const auto& info = *std::ranges::find(kPlanAreas, area, &PlanAreaInfo::area);
const auto dir = plan_area_root(info) / std::string(key);
std::error_code ec;
std::filesystem::create_directories(dir, ec);
const auto record = dir / kPlanRecord;
if (std::filesystem::exists(record, ec))
mcpp::home::mark_used(record);
else
std::ofstream(record, std::ios::binary) << mcpplibs::os::fs::generic_utf8(project) << '\n';
return dir;
}

namespace {

std::filesystem::path pkg_root() { return mcpp::home::cache_root() / "pkg"; }
Expand Down Expand Up @@ -353,10 +408,46 @@ std::vector<Entry> walk_variant_entries() {
return out;
}

// The work directories of plans that describe (plan_work_dir): one per
// project and area, each last used when a plan last ran in it. Collected as
// the cache's entries are, and emptied by `cache clean --work`.
std::vector<Entry> walk_plan_entries() {
std::vector<Entry> out;
for (const auto& area : kPlanAreas) {
std::error_code ec;
const auto root = plan_area_root(area);
for (auto& d : std::filesystem::directory_iterator(root, ec)) {
if (!d.is_directory()) continue;
Entry e;
e.dir = d.path();
e.kind = "work";
e.key = mcpplibs::os::fs::generic_utf8(d.path().filename());
const auto record = e.dir / kPlanRecord;
std::string project;
std::error_code fe;
if (std::filesystem::is_regular_file(record, fe)) {
e.accessed = dir_mtime_seconds(record);
if (std::ifstream is(record, std::ios::binary); is) std::getline(is, project);
} else {
// Written by an mcpp before the record: the directory's time is
// the last plan that wrote or removed a file directly in it.
e.accessed = dir_mtime_seconds(e.dir);
}
e.label = project.empty()
? std::format("{} (work directory)", area.command)
: std::format("{} (work directory of {})", area.command, project);
measure(e);
out.push_back(std::move(e));
}
}
return out;
}

std::vector<Entry> walk_collectable() {
auto out = walk_pkg_entries();
for (auto& e : walk_tool_entries()) out.push_back(std::move(e));
for (auto& e : walk_variant_entries()) out.push_back(std::move(e));
for (auto& e : walk_plan_entries()) out.push_back(std::move(e));
return out;
}

Expand Down Expand Up @@ -674,10 +765,10 @@ export int cache_gc(const std::string& maxSizeArg, const std::string& olderThanA
return 0;
}

// `mcpp cache clean [--deps] [--std] [--all] [--legacy]`.
export int cache_clean(bool deps, bool stds, bool tools, bool all, bool legacy) {
if (all) { deps = true; stds = true; tools = true; }
if (!deps && !stds && !tools && !legacy) deps = true; // bare `clean` = dep entries
// `mcpp cache clean [--deps] [--std] [--tools] [--work] [--all] [--legacy]`.
export int cache_clean(bool deps, bool stds, bool tools, bool work, bool all, bool legacy) {
if (all) { deps = true; stds = true; tools = true; work = true; }
if (!deps && !stds && !tools && !work && !legacy) deps = true; // bare `clean` = dep entries

std::error_code ec;
if (deps) {
Expand All @@ -695,6 +786,14 @@ export int cache_clean(bool deps, bool stds, bool tools, bool all, bool legacy)
std::filesystem::remove_all(tool_root(), ec);
std::println("Cleaned host tool entries ({})", human_bytes(n));
}
if (work) {
std::uintmax_t n = 0;
for (const auto& area : kPlanAreas) {
n += dir_size(plan_area_root(area));
std::filesystem::remove_all(plan_area_root(area), ec);
}
std::println("Cleaned work directories of plans ({})", human_bytes(n));
}
if (legacy) {
auto legacyRoot = mcpp::home::legacy_bmi_root();
if (std::filesystem::exists(legacyRoot, ec)) {
Expand Down
2 changes: 2 additions & 0 deletions src/cli.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -1257,6 +1257,8 @@ int run(int argc, char** argv) {
.option(cl::Option("deps").help("Drop package entries (default)"))
.option(cl::Option("std").help("Drop std module entries"))
.option(cl::Option("tools").help("Drop host tool entries"))
.option(cl::Option("work").help(
"Drop the work directories of emit build-database, pack --list-formats and publish"))
.option(cl::Option("all").help("Drop every kind of entry"))
.option(cl::Option("legacy")
.help("Remove the unused pre-v1 cache at $MCPP_HOME/bmi"))
Expand Down
13 changes: 8 additions & 5 deletions src/cli/cmd_build.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import mcpplibs.cmdline;
import mcpp.build.prepare;
import mcpp.build.execute;
import mcpp.build.ninja; // write_module_maps
import mcpp.bmi_cache.maintenance; // parse_duration, for `clean --stale --older-than`
import mcpp.bmi_cache.maintenance; // parse_duration, for `clean --stale --older-than`; plan_work_dir
import mcpp.build.directives; // the device-slot table
import mcpp.build.configure;
import mcpp.build.coff_exports;
Expand Down Expand Up @@ -669,12 +669,15 @@ namespace {

// One work directory per project root and member, under the mcpp home: the
// planning pass writes its lock, its build programs' artifacts and its output
// directory there, never inside the project.
// directory there, never inside the project. The cache collects it once no
// plan has used it for a while (mcpp#969).
std::filesystem::path build_database_work_dir(const std::filesystem::path& root,
std::string_view member) {
return mcpp::home::root() / "cache" / "build-database"
/ mcpp::toolchain::hash_string(root.lexically_normal().generic_string()
+ "\x1f" + std::string(member));
return mcpp::bmi_cache::plan_work_dir(
mcpp::bmi_cache::PlanArea::BuildDatabase,
mcpp::toolchain::hash_string(root.lexically_normal().generic_string()
+ "\x1f" + std::string(member)),
root);
}

std::optional<std::string> read_whole_file(const std::filesystem::path& p) {
Expand Down
1 change: 1 addition & 0 deletions src/cli/cmd_cache.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ export int cmd_cache_clean(const mcpplibs::cmdline::ParsedArgs& parsed) {
return mcpp::bmi_cache::cache_clean(parsed.is_flag_set("deps"),
parsed.is_flag_set("std"),
parsed.is_flag_set("tools"),
parsed.is_flag_set("work"),
parsed.is_flag_set("all"),
parsed.is_flag_set("legacy"));
}
Expand Down
12 changes: 7 additions & 5 deletions src/cli/cmd_publish.cppm
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ import mcpp.manifest;
import mcpp.publish.pipeline;
import mcpp.ui;
import mcpp.wire;
import mcpp.home; // --list-formats plans outside the project
import mcpp.bmi_cache.maintenance; // plan_work_dir: --list-formats and the pin check plan outside the project
import mcpp.pack.stage_tree; // the built-in formats
import mcpp.toolchain.fingerprint; // hash_string
import mcpp.toolchain.platform; // host_arch: the static row of `--linkage static`
Expand Down Expand Up @@ -107,8 +107,9 @@ static int refuse_shared_exact_pins() {
if (!library) return 0;
mcpp::build::BuildOverrides ov;
ov.intent = mcpp::build::PrepareIntent::Describe;
ov.work_dir = mcpp::home::root() / "cache" / "publish-plan"
/ mcpp::toolchain::hash_string(root->lexically_normal().generic_string());
ov.work_dir = mcpp::bmi_cache::plan_work_dir(
mcpp::bmi_cache::PlanArea::PublishPlan,
mcpp::toolchain::hash_string(root->lexically_normal().generic_string()), *root);
std::expected<mcpp::build::BuildContext, std::string> ctx = std::unexpected(std::string{});
{
mcpp::ui::terminal::StdoutToStderr narration;
Expand Down Expand Up @@ -370,8 +371,9 @@ int cmd_pack_list_formats(const mcpplibs::cmdline::ParsedArgs& parsed) {
if (auto o = parsed.option("target"); o && !o->get().values.empty())
ov.target_triple = o->get().values.back();
ov.intent = mcpp::build::PrepareIntent::Describe;
ov.work_dir = mcpp::home::root() / "cache" / "pack-formats"
/ mcpp::toolchain::hash_string(root->lexically_normal().generic_string());
ov.work_dir = mcpp::bmi_cache::plan_work_dir(
mcpp::bmi_cache::PlanArea::PackFormats,
mcpp::toolchain::hash_string(root->lexically_normal().generic_string()), *root);
std::expected<mcpp::build::BuildContext, std::string> ctx = std::unexpected(std::string{});
{
mcpp::ui::terminal::StdoutToStderr narration;
Expand Down
Loading
Loading