diff --git a/.agents/docs/2026-11-20-add-binary_tree-plan.md b/.agents/docs/2026-11-20-add-binary_tree-plan.md new file mode 100644 index 00000000..28ace7cb --- /dev/null +++ b/.agents/docs/2026-11-20-add-binary_tree-plan.md @@ -0,0 +1,124 @@ +# Add yandere-chan.binary_tree 0.1.4 + +## Source and shape + +- Upstream: . +- Version: `0.1.4`, tagged on the commit that exports the global + `operator new` / `operator delete` using-declarations from the module + interfaces (namespace `yandere-chan` was introduced in 0.1.3). +- License: MIT. +- Shape: Form A (mcpp-native library). The tarball carries + `binary_tree-0.1.4/mcpp.toml`; that manifest is the build. It declares: + - `include_dirs = ["."]` — the header library (`binary_tree.h`, + `parent_aware_binary_tree.h`, `intrusive_binary_tree.h`, `union_data.h`, + and the POC sets) stays a normal header interface; + - sources `Yc.intrusive_binary_tree.cppm`, `Yc.binary_tree.cppm`, + `Yc.parent_aware_binary_tree.cppm` and `src/binary_tree.cppm`; + - `[lib] path = "src/binary_tree.cppm"` — the lib root re-exports the three + wrappers, so `import binary_tree;` reaches all of them and `mcpp pack` has + a module interface to publish. +- No features and no dependencies: the library is header/module only. + +The four public modules are `binary_tree`, `Yc.intrusive_binary_tree`, +`Yc.binary_tree` and `Yc.parent_aware_binary_tree`; module names are +independent of the package namespace. + +## The libc++ placement-new problem and the export fix + +The Linux LLVM run (clang + libc++) failed on 0.1.0 with: + +``` +libc++ __memory/allocator_traits.h:362: error: no matching function for call to '__construct_at' +construct_at.h:43: ... no matching 'operator new' function + for non-allocating placement new expression; include +``` + +`std::allocator_traits::construct` instantiates libc++'s `__construct_at`, +whose default template argument uses placement new. Adding `` to the +module's global module fragment is not enough: clang's combined +single-invocation module build (`-x c++-module -fmodule-output=... -c`, the +mode mcpp uses) does not make the GMF declaration **visible** to the importer, +even though it is reachable. The lookup happens when the consumer instantiates +the template, so `import binary_tree;` alone failed. See +llvm/llvm-project#218246 (and the earlier #59601), which lists the same two +workarounds: instantiate in the defining module, or re-declare the missing +declaration in the importing TU. + +0.1.4 takes a third route that keeps the consumer clean: each module interface +exports a using-declaration for the global placement `operator new` and its +matching `operator delete`: + +```cpp +export module Yc.binary_tree; + +import Yc.intrusive_binary_tree; + +export using ::operator new; +export using ::operator delete; +``` + +The using-declarations are exported names (not declarations of new entities), +so an importer can look placement new up without including ``, and a +consumer that *does* include `` still compiles. The declarations must +come after the imports: GCC requires post-module imports to be contiguous. +Clang, MSVC and GCC 16.1 all accept the form; the umbrella module re-exports +it through `export import`. + +0.1.0-0.1.3 are not listed: all carry the old `YandereChan2` namespace and +predate this export. + +## Download and mirror + +- GLOBAL: + `https://github.com/YandereChan2/binary_tree/releases/download/0.1.4/binary_tree-0.1.4.tar.gz` + (a `git archive` of tag `0.1.4`, uploaded as the release asset; the tarball + root is `binary_tree-0.1.4/`) +- SHA-256: + `e7bd88adaa156219d87db05cbe4bc0dd5447ee7c7736f138f0870ebdfa706853` +- No `mcpp-res` mirror is available, so the descriptor uses the repository's + plain-string upstream URL fallback. No CN mirror is invented; a maintainer + can add a byte-identical GitCode release later. +- `extensions.autoupdate` uses the bare tag and the tag-archive template + (`archive/refs/tags/${tag}.tar.gz`), so a future release needs no uploaded + asset for the updater to compute its sha. + +## Test member + +- `tests/examples/binary_tree-module/` has two test files: + - `binary_tree_module.cpp` imports the lib root and each wrapper and asserts + insert / in-order `for_each` / copy / `parent_of_cnroot` / intrusive-node + behavior; + - `binary_tree_umbrella.cpp` imports only `binary_tree` (umbrella-only) and + asserts the same construction path, which proves the re-exported + placement-new declarations reach an importer that never includes ``. + + Neither file includes `` or any library header. Every check affects the + process exit status. +- The member carries its own + `[indices] yandere-chan = { path = "../../.." }` so the dependency resolves + to the checked-in descriptor rather than the published remote index. + +## Verification + +- Pinned mcpp `2026.11.18.1`, the version in `validate.yml`: + `mcpp xpkg parse pkgs/y/yandere-chan.binary_tree.lua` reports `parse OK` + for linux, macosx and windows, and recognizes Form A. +- `mcpp test -p binary_tree-module --cache off` downloads the 0.1.4 asset, + compiles both tests without ``, and both pass. +- The same manifest builds with `mcpp build` (clang + MSVC STL), + `mcpp build --toolchain msvc@system`; all four `.cppm` compile with GCC + 16.1 (`-fmodules`). +- A minimal clang 23.1.3 combined-mode repro of the placement-new bug + (`module; #include ` + direct placement new) fails without the export + and passes with it; MSVC 14.51 and GCC 16.1 accept the exported form. + +## Notes + +- The export is a workaround for the clang module bug, not a permanent API + requirement. If a future clang makes GMF scopes visible to importers, the + using-declarations can be dropped. +- The POC set headers `rb_set.h` / `avl_set.h` import + `parent_aware_binary_tree.h` as a header unit on MSVC; that path is not part + of this package. +- The package is platform-independent: the same tarball and sha are used for + linux, macosx and windows. diff --git a/mcpp.toml b/mcpp.toml index a9b4a51f..400282c1 100644 --- a/mcpp.toml +++ b/mcpp.toml @@ -60,6 +60,7 @@ members = [ "tests/examples/accesskit", "tests/examples/asio-module", "tests/examples/asio-ssl", + "tests/examples/binary_tree-module", "tests/examples/boost-asio", "tests/examples/boost-any", "tests/examples/boost-circular-buffer", diff --git a/pkgs/y/yandere-chan.binary_tree.lua b/pkgs/y/yandere-chan.binary_tree.lua new file mode 100644 index 00000000..5568cd45 --- /dev/null +++ b/pkgs/y/yandere-chan.binary_tree.lua @@ -0,0 +1,69 @@ +-- yandere-chan.binary_tree — Intrusive and owning binary tree library with +-- C++23 module wrappers. +-- +-- Form A: the release tarball carries the package's own `mcpp.toml` at its +-- root (`binary_tree-/mcpp.toml`), and that manifest is the build: it +-- declares the header library (`include_dirs = ["."]`), the three module +-- wrappers `Yc.intrusive_binary_tree` / `Yc.binary_tree` / +-- `Yc.parent_aware_binary_tree`, and the lib root `src/binary_tree.cppm` that +-- re-exports them for `import binary_tree;`. The `mcpp` field is therefore the +-- wrapper-directory pointer, not an inline Form B descriptor. +-- +-- 0.1.4 is `git archive` of the tag, uploaded as a release asset. Besides the +-- `yandere-chan` namespace it exports the global `operator new` / `operator +-- delete` using-declarations from all three module interfaces, so a libc++ +-- consumer does not need `#include `: clang's combined `-fmodule-output` +-- build does not make the module's GMF `` visible to importers, and +-- libc++'s `allocator_traits::construct` looks placement new up at +-- instantiation (llvm/llvm-project#218246). +-- +-- 0.1.0-0.1.3 are intentionally not listed: all four carry the old +-- `YandereChan2` namespace, and 0.1.0-0.1.3 predate the exported +-- `operator new`/`operator delete` declarations. +-- +-- Upstream tags are bare versions (`0.1.4`), so the xpm key carries the tag +-- verbatim and autoupdate's tag pattern is `${version}`. +-- +-- No mcpp-res mirror is configured yet (no CN access): the plain-string GLOBAL +-- url is the documented fallback for CN consumers until a maintainer creates +-- the mirror. +package = { + spec = "1", + namespace = "yandere-chan", + name = "binary_tree", + description = "Intrusive and owning binary tree library, with C++23 module wrappers", + licenses = {"MIT"}, + repo = "https://github.com/YandereChan2/binary_tree", + type = "package", + maintainers = {"YandereChan2"}, + + extensions = { + autoupdate = { + tag = "${version}", + url = "https://github.com/YandereChan2/binary_tree/archive/refs/tags/${tag}.tar.gz", + }, + }, + + xpm = { + linux = { + ["0.1.4"] = { + url = "https://github.com/YandereChan2/binary_tree/releases/download/0.1.4/binary_tree-0.1.4.tar.gz", + sha256 = "e7bd88adaa156219d87db05cbe4bc0dd5447ee7c7736f138f0870ebdfa706853", + }, + }, + macosx = { + ["0.1.4"] = { + url = "https://github.com/YandereChan2/binary_tree/releases/download/0.1.4/binary_tree-0.1.4.tar.gz", + sha256 = "e7bd88adaa156219d87db05cbe4bc0dd5447ee7c7736f138f0870ebdfa706853", + }, + }, + windows = { + ["0.1.4"] = { + url = "https://github.com/YandereChan2/binary_tree/releases/download/0.1.4/binary_tree-0.1.4.tar.gz", + sha256 = "e7bd88adaa156219d87db05cbe4bc0dd5447ee7c7736f138f0870ebdfa706853", + }, + }, + }, + + mcpp = "*/mcpp.toml", +} diff --git a/tests/examples/binary_tree-module/mcpp.toml b/tests/examples/binary_tree-module/mcpp.toml new file mode 100644 index 00000000..346bd0d8 --- /dev/null +++ b/tests/examples/binary_tree-module/mcpp.toml @@ -0,0 +1,25 @@ +# binary_tree module-package test: consumes yandere-chan.binary_tree by import +# only and asserts behavior under `mcpp test`. +# +# This member is the only place the descriptor's Form A lookup is exercised: +# `[indices]` below overrides the workspace-root `compat` redirect, so +# yandere-chan resolves to this checkout (pkgs/y/yandere-chan.binary_tree.lua) +# rather than the published remote index. The key is the dependency NAMESPACE. +[indices] +yandere-chan = { path = "../../.." } + +[package] +name = "binary_tree-module-tests" +version = "0.1.0" + +# The package is the mcpp-native library: its own tarball carries mcpp.toml, +# which declares the public modules below. Import the umbrella root and each +# wrapper so a regression in either surface fails this member. The umbrella +# test also checks the exported placement-new declarations (no include +# anywhere in the consumer), which is what libc++ needs under clang's +# combined module build (llvm/llvm-project#218246). +# +# 0.1.4 is the first release with the `yandere-chan` namespace and the exported +# `operator new`/`operator delete`; earlier versions are not listed. +[dependencies.yandere-chan] +binary_tree = "0.1.4" diff --git a/tests/examples/binary_tree-module/tests/binary_tree_module.cpp b/tests/examples/binary_tree-module/tests/binary_tree_module.cpp new file mode 100644 index 00000000..295c35a1 --- /dev/null +++ b/tests/examples/binary_tree-module/tests/binary_tree_module.cpp @@ -0,0 +1,63 @@ +// yandere-chan.binary_tree module-package end-to-end assertion: consume the +// library by import only (no `#include` of its headers, no include path setup). +// +// * `import binary_tree;` — the lib root, re-exporting all three +// * `import Yc.binary_tree;` — owning, no parent pointer +// * `import Yc.parent_aware_binary_tree;` — owning, with parent pointers +// * `import Yc.intrusive_binary_tree;` — intrusive node hooks +// +// Every check increments `failures`; the process exits non-zero when a check +// does not hold, which is what makes this a test rather than a sample. + +import Yc.intrusive_binary_tree; +import Yc.binary_tree; +import Yc.parent_aware_binary_tree; +import binary_tree; + +int main() +{ + int failures = 0; + auto check = [&failures](bool ok) { if (!ok) { ++failures; } }; + + // Owning tree without parent pointers. + Yc::binary_tree t; + t.insert(t.root(), 1); + t.insert(t.root().get_left(), 2); + t.insert(t.root().get_right(), 3); + + check(!t.empty()); + check(*t.nroot() == 1); + check(*t.root().get_left() == 2); + check(*t.root().get_right() == 3); + + int sum = 0; + t.for_each([&sum](int& v) { sum += v; }); + check(sum == 6); + + // Copy construction walks and copies the structure. + Yc::binary_tree copy = t; + int copy_sum = 0; + copy.for_each([©_sum](int& v) { copy_sum += v; }); + check(copy_sum == 6); + + // Owning tree with parent pointers. + Yc::parent_aware_binary_tree p; + p.insert(p.root(), 5); + p.insert(p.root().get_left(), 6); + + check(*p.nroot() == 5); + check(*p.nroot().get_left() == 6); + check(!p.parent_of_cnroot().null()); + + // Intrusive tree: the user node carries the hooks. + struct node : Yc::intrusive_binary_tree_node_base<> { int value = 0; }; + Yc::basic_intrusive_binary_tree<> it; + node a; + a.value = 7; + it.insert(it.root(), a); + + check(!it.empty()); + check(static_cast(*it.nroot()).value == 7); + + return failures == 0 ? 0 : 1; +} diff --git a/tests/examples/binary_tree-module/tests/binary_tree_umbrella.cpp b/tests/examples/binary_tree-module/tests/binary_tree_umbrella.cpp new file mode 100644 index 00000000..c70097f7 --- /dev/null +++ b/tests/examples/binary_tree-module/tests/binary_tree_umbrella.cpp @@ -0,0 +1,19 @@ +// yandere-chan.binary_tree umbrella-only assertion: import the lib root and +// nothing else. This checks that `export import` re-exports both the owning +// tree template and the placement-new declarations exported by the wrappers, +// so no `#include ` is needed here either. + +import binary_tree; + +int main() +{ + Yc::binary_tree t; + t.insert(t.root(), 1); + t.insert(t.root().get_left(), 2); + + if (t.empty() || *t.nroot() != 1 || *t.root().get_left() != 2) { return 1; } + + int sum = 0; + t.for_each([&sum](int& v) { sum += v; }); + return sum == 3 ? 0 : 1; +}