Skip to content
Merged
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
124 changes: 124 additions & 0 deletions .agents/docs/2026-11-20-add-binary_tree-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# Add yandere-chan.binary_tree 0.1.4

## Source and shape

- Upstream: <https://github.com/YandereChan2/binary_tree>.
- 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 <new>
```

`std::allocator_traits::construct` instantiates libc++'s `__construct_at`,
whose default template argument uses placement new. Adding `<new>` 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 `<new>`, and a
consumer that *does* include `<new>` 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 `<new>`.

Neither file includes `<new>` 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 `<new>`, 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 <new>` + 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.
1 change: 1 addition & 0 deletions mcpp.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
69 changes: 69 additions & 0 deletions pkgs/y/yandere-chan.binary_tree.lua
Original file line number Diff line number Diff line change
@@ -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-<version>/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 <new>`: clang's combined `-fmodule-output`
-- build does not make the module's GMF `<new>` 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",
}
25 changes: 25 additions & 0 deletions tests/examples/binary_tree-module/mcpp.toml
Original file line number Diff line number Diff line change
@@ -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 <new> 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"
63 changes: 63 additions & 0 deletions tests/examples/binary_tree-module/tests/binary_tree_module.cpp
Original file line number Diff line number Diff line change
@@ -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<int> 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<int> copy = t;
int copy_sum = 0;
copy.for_each([&copy_sum](int& v) { copy_sum += v; });
check(copy_sum == 6);

// Owning tree with parent pointers.
Yc::parent_aware_binary_tree<int> 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<node&>(*it.nroot()).value == 7);

return failures == 0 ? 0 : 1;
}
19 changes: 19 additions & 0 deletions tests/examples/binary_tree-module/tests/binary_tree_umbrella.cpp
Original file line number Diff line number Diff line change
@@ -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 <new>` is needed here either.

import binary_tree;

int main()
{
Yc::binary_tree<int> 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;
}
Loading