# feat(api,cli): generate CMakeLists.txt for standalone C/C++ nodes and support cmake find_package

[Ts-sound]

Summary

Add CMake find_package support for all C/C++ API crates (dora-node-api-c, dora-operator-api-c, dora-node-api-cxx, dora-operator-api-cxx), enable dora new --kind node --lang c/cxx and --kind dataflow to generate ready-to-build CMakeLists.txt, replace shell-based staging with a Rust xtask tool, and publish unified library archives with cmake config files.

Problem

Running dora new --kind node --lang c or --lang cxx produced only source files without a build system. A // TODO: Makefile? comment remained in both template modules, requiring users to manually write their own build setup.

Related

• feat(cli): generate CMakeLists.txt for standalone C/C++ nodes #1514
• feat(api,cli): generate CMakeLists.txt for standalone C/C++ nodes and support cmake find_package #1756

Solution

Generic CMake Template

Single dora-api-config.cmake.in with @PACKAGE@, @TARGET@, @LIB_UNIX@, @LIB_WIN@, @CXX_BRIDGE_FILES@ placeholders shared by all 4 crates.

build.rs Staging

Each crate's build.rs writes cmake config + headers to predictable paths:

• C crates: target/<profile>/<crate>/lib/cmake/<crate>/*.cmake + include/*.h
• C++ crates: target/cxxbridge/<crate>/lib/cmake/<crate>/*.cmake + include/*.h + src/*.cc

xtask stage

Replaced shell scripts with cargo run -p xtask -- stage <crate> <target_dir> <prefix> — cross-platform, handles all 4 crates.

dora new Templates

Template	Content
--kind node --lang c	node.c + CMakeLists.txt (find_package(dora-node-api-c))
--kind node --lang cxx	node.cc + CMakeLists.txt (find_package(dora-node-api-cxx) + CXX_BRIDGE_FILES)
--kind dataflow --lang c	3 nodes + root CMakeLists.txt (find_package + add_subdirectory)
--kind dataflow --lang cxx	3 nodes + root CMakeLists.txt (find_package + add_subdirectory + CXX_BRIDGE_FILES)

Tests

• test-c-cpp-libraries.yml : CI test
• scripts/c_cpp_lib/stage_test.sh — verifies staging for debug, release, --target
• scripts/c_cpp_lib/build_node_test.sh — dora new --kind node + cmake build
• scripts/c_cpp_lib/build_dataflow_test.sh — dora new --kind dataflow + cmake build

Documentation

Rewrote apis/C-CPP-LIBRARIES.md with Obtaining the API Libraries (download / xtask), Using dora new, and CMake Integration sections.

Key Changes

• apis/c/node/cmake/dora-api-config.cmake.in — generic cmake template
• apis/{c/operator,c++/node,c++/operator}/build.rs — cmake export
• apis/c/{node,operator}/build.rs — stage to target/<profile>/<crate>/
• xtask/ — cargo run -p xtask -- stage <crate> <target_dir> <prefix>
• binaries/cli/src/template/c/{node,node/CMakeLists,cmake,mod}.rs — C node + dataflow templates
• binaries/cli/src/template/cxx/{node,node/CMakeLists,cmake,node-template,mod}.rs — C++ node + dataflow templates
• .github/workflows/{publish,test}-c-cpp-libraries.yml — replace shell scripts with xtask
• scripts/c_cpp_lib/{stage_test,build_node_test,build_dataflow_test}.sh — build verification
• apis/C-CPP-LIBRARIES.md — complete rewrite

Expected Flow

# Option 1: Download pre-built archives from GitHub releases
tar xzf dora-c-libraries-x86_64-unknown-linux-gnu.tar.gz

# Option 2: Build with xtask
cargo build --release -p dora-node-api-c
cargo run -p xtask -- stage dora-node-api-c target/release dora-c-libraries-x86_64-unknown-linux-gnu

# Create and build a C node
dora new my-robot --kind node --lang c
cd my-robot && mkdir build && cd build
cmake .. -DCMAKE_PREFIX_PATH=../../dora-c-libraries-x86_64-unknown-linux-gnu
cmake --build .

# Create and build a C++ dataflow
dora new my-dataflow --kind dataflow --lang cxx
cd my-dataflow && mkdir build && cd build
cmake .. -DCMAKE_PREFIX_PATH=../../dora-cpp-libraries-x86_64-unknown-linux-gnu
cmake --build .

Tasks

• Generic cmake template for all 4 crates
• build.rs staging to predictable target directory
• xtask stage command replacing shell scripts
• C node CMakeLists.txt template
• C++ node CMakeLists.txt template with CXX_BRIDGE_FILES
• C dataflow CMakeLists.txt (find_package + add_subdirectory)
• C++ dataflow CMakeLists.txt (find_package + add_subdirectory)
• CI publish workflow update
• CI test workflow update
• Build test scripts (node + dataflow)
• Documentation rewrite (C-CPP-LIBRARIES.md)
• C++ node template fix (correct cxxbridge API)

Notes

• CXX_BRIDGE_FILES is only populated for C++ crates. C crates set it to empty.
• C++ .cc files are NOT included in the static library — they come from find_package and must be compiled alongside user code.
• Dataflow root CMakeLists.txt uses add_subdirectory() for each node, delegating to per-node CMakeLists.txt.

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[Ts-sound]

@phil-opp Could you please review the changes (about apis/c/node)?
If approved, I'll apply consistent changes to c/operator and all cxx/* accordingly.

[phil-opp]

Claude found the following issue:

🔴 Windows: the static lib never makes it into lib/ on a clean build

In apis/c/node/build.rs:

#[cfg(windows)]
fn link_library(lib_dir: &Path) {
    let lib_symlink = lib_dir.join("dora_node_api_c.lib");
    let _ = fs::remove_file(&lib_symlink);
    let target_dir = lib_dir.parent().expect("failed to get parent");
    let lib_target = target_dir.join("dora_node_api_c.lib");
    if lib_target.exists() {
        fs::copy(&lib_target, &lib_symlink).expect("failed to copy library");
    }
}

build.rs runs before rustc compiles the crate, so on a fresh build target/release/dora_node_api_c.lib does not exist yet → lib_target.exists() is false → the copy is silently skipped. After compilation the .lib is on disk but never gets staged into target/release/lib/. find_package then resolves IMPORTED_LOCATION to a missing file and CMake fails at link time.

The Unix path happens to work because dangling symlinks are legal and cargo writes the .a later, resolving the link. Windows fs::copy doesn't have that property.

The CI smoke job should surface this on windows-latest — and the single cargo build --release --package dora-node-api-c step won't trigger a second build-script run (this PR also drops dora-node-api-c from binaries/cli/Cargo.toml, so cargo install --path binaries/cli doesn't re-invoke it).

Suggested fix: move lib staging out of build.rs into a post-build step (an xtask or a CI step that runs after cargo build). build.rs would then only emit the cmake/ and include/ files, and lib staging becomes a release-time concern — which is closer to what cargo's build-script contract expects anyway. As a bonus this also removes the Unix symlink, so local-dev and release-archive layouts stay identical.

[Ts-sound]

OK, I will add this task as a follow-up to publish-c-cpp-libraries.yml .

[phil-opp]

We also have an existing cmake-templates.txt file. How does this compare to it? Doesn't this lead to duplication?

[Ts-sound]

This file is used to simultaneously compile talker_1 and talker_2, listener_1 )for dataflow-template.yml). Is it necessary to continue using cmake-templates.txt?

[Ts-sound]

This file can be simplified.

project(cxx-dataflow LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_FLAGS "-fPIC")

find_package(dora-node-api-c REQUIRED)

## listener_1
add_executable(listener_1 listener_1/node.cc)
target_link_libraries(listener_1 PRIVATE dora-node-api-c::dora-node-api-c dora-node-api-c::extra)

## talker_1,talker_2
...

[Ts-sound]

@phil-opp
In Rust, the build.rs output path is provided via OUT_DIR, which is a temporary, dynamically generated directory (target/<profile>/build/<crate>-*/out). Currently, it is difficult for xtask scripts or other post-build scripts to reliably locate this path.

[Ts-sound]

@phil-opp Could you please review the changes?

[heyong4725]

Closing as superseded-in-part by #1851, with thanks to @Ts-sound for laying out the full design.

Why close

Three weeks after this PR opened, #1851 (rescue of #1514) merged the CLI-template piece of #1756 using a different approach: ExternalProject_Add (build dora from source via DORA_ROOT_DIR) instead of find_package(dora-node-api-c REQUIRED) (consume installed libraries). Both are legitimate UX models, but only one ships in dora new. A panel-faithful rescue of this PR's 1561 lines would have to either replace #1851 or design coexistence, plus rebase against three weeks of unrelated evolution, plus address @phil-opp's two unresolved review concerns.

What this PR's contribution split into

✅ Already on main (via #1851 / pre-existing infra):

• CMakeLists.txt templates for dora new --kind node/dataflow --lang c/cxx (feat(cli): generate CMakeLists.txt for standalone C/C++ nodes (rescue of #1514) #1851 — ExternalProject_Add approach)
• publish-c-cpp-libraries.yml workflow (pre-existing, shell-based packaging)
• apis/C-CPP-LIBRARIES.md documentation (pre-existing, 208 lines)

❌ Not on main, real value, surgical follow-up coming:

• find_package(dora-node-api-c REQUIRED) support — build.rs in the 4 C/C++ API crates generates CMake config + version files at standard layout (<prefix>/lib/cmake/<crate>/)
• xtask stage tool — cross-platform Rust replacement for shell staging scripts (also fixes @phil-opp's Windows build.rs lib-staging bug by moving staging out of build.rs into a post-build step)
• test-c-cpp-libraries.yml CI workflow

The residual scope (find_package infra + xtask + test CI, with Phil's Windows fix applied) will land as a focused follow-up PR — roughly 400-600 lines instead of 1561, with no conflict against #1851's templates. I'll credit you with Co-authored-by since the design and most of the code is yours.

Tracking

• Parent issue feat(api,cli): generate CMakeLists.txt for standalone C/C++ nodes and support cmake find_package #1756 stays open; I'll update its task list to reflect the split.
• Phil's two review comments on this PR are still valid and will be addressed in the follow-up: (1) move Windows lib staging out of build.rs into xtask post-build, (2) cmake-templates.txt / dora-api-config.cmake.in are different layers (CLI scaffold vs. package config), no actual duplication.

Thanks for the thorough design write-up — it made the triage straightforward.