Cabin examples

User-facing runnable Cabin example projects, one per subdirectory. Each example has its own cabin.toml, sources, and README.md.

What lives here vs. elsewhere

• examples/ (this directory) - user-facing Cabin (C/C++) example projects. Each one is a real Cabin package that you can cd into and run cabin build against. Cargo does not look at this directory.
• crates/<name>/examples/ - Cargo example targets for the Rust crates. None exist today; this is where they would go if added.
• crates/cabin-port/ports/ - curated foundation ports. Cabin recipes that adapt real upstream C/C++ libraries that do not yet ship a native cabin.toml. Not example projects; see ../crates/cabin-port/ports/README.md.

Available examples

Directory	What it demonstrates
hello-c/	Smallest useful C project: one executable target with a .c source.
hello-cpp/	Smallest useful C++ project: one executable target with a .cc source.
library-and-app/	A library target consumed by an executable target in the same package, with include-dirs propagation.
library-with-tests/	A library plus two test targets, run with cabin test. The example to read for unit testing.
header-only-lib/	Authoring a header-only target (include-dirs, nothing compiled) consumed by an executable in the same package.
workspace-basic/	A virtual workspace root with two members (util library, cli executable depending on util via a path dependency).
workspace-app-and-lib/	A workspace whose internal greeter library depends on the fmt foundation port; the app member reaches fmt transitively through its path dependency.
feature-gated-targets/	A feature-gated optional library: required-features on [target.tls], the tls feature enabled on the dependency edge, and explicit deps = ["netlib:net", "netlib:tls"] links.
zlib-usage/	Consuming the curated zlib foundation port from crates/cabin-port/ports/zlib/.
cjson-usage/	Consuming the curated cJSON foundation port from crates/cabin-port/ports/cJSON/.
xxhash-usage/	Consuming the curated xxHash foundation port from crates/cabin-port/ports/xxhash/.
tinyxml2-usage/	Consuming the curated tinyxml2 C++ foundation port from crates/cabin-port/ports/tinyxml2/.
sqlite3-usage/	Consuming the curated SQLite foundation port (amalgamation) from crates/cabin-port/ports/sqlite3/, including a single-threaded feature.
libpng-usage/	Consuming the curated libpng foundation port from crates/cabin-port/ports/libpng/, which itself depends transitively on the bundled zlib port.
fmt-usage/	Consuming the curated {fmt} C++ foundation port from crates/cabin-port/ports/fmt/.
spdlog-usage/	Consuming the curated spdlog header-only C++ foundation port from crates/cabin-port/ports/spdlog/.
googletest-usage/	A test target linking the curated GoogleTest foundation port from crates/cabin-port/ports/googletest/, run with cabin test.
catch2-usage/	A test target linking the curated Catch2 foundation port (amalgamation, port-supplied main) from crates/cabin-port/ports/catch2/, run with cabin test.
nlohmann-json-usage/	Consuming the curated header-only nlohmann_json foundation port from crates/cabin-port/ports/nlohmann_json/.
cli11-usage/	Consuming the curated header-only CLI11 foundation port from crates/cabin-port/ports/CLI11/.
miniz-usage/	Consuming the curated miniz foundation port (zip-sourced amalgamation) from crates/cabin-port/ports/miniz/.
stb-usage/	Consuming the curated header-only stb foundation port (implementation-macro pattern) from crates/cabin-port/ports/stb/.
uthash-usage/	Consuming the curated header-only uthash foundation port from crates/cabin-port/ports/uthash/.
inih-usage/	Consuming the curated inih C foundation port from crates/cabin-port/ports/inih/.
picohttpparser-usage/	Consuming the curated picohttpparser C foundation port from crates/cabin-port/ports/picohttpparser/.
cli-with-spdlog/	A CLI app combining three foundation ports - CLI11 flags, {fmt} formatting, spdlog logging - including the SPDLOG_FMT_EXTERNAL opt-in to the external fmt port.
unit-test-gtest/	A library unit-tested with GoogleTest through cabin test: a fixture, value assertions, and exception assertions. The example to read for framework-based testing.
json-cli/	A JSON round trip on the header-only nlohmann_json port: parse a document, read typed values, emit a derived summary.
sqlite-todo/	An in-memory todo list on the sqlite3 port: DDL/DML through sqlite3_exec, then a prepare/step/finalize query loop.
png-info/	An in-memory PNG encode/decode roundtrip on the libpng port, pushing real image data across the transitive libpng -> zlib C port edge.
platform-cfg/	Per-platform [target.'cfg(...)'] defines: one source that compiles a different macro on Windows (MSVC) vs. Unix (GCC/Clang).

Running an example manually

cd examples/hello-cpp
cabin build
cabin run

(cabin run builds and launches the package's executable target. Each example's README spells out the exact command if it differs.)

Running every example's tests through Cargo

The repository ships integration tests that build and run each example using the in-tree cabin binary. From the repository root:

cargo test --test cabin_examples

The tests copy each example into a temporary directory before building, so the source tree never accumulates build output. Tests skip cleanly when Ninja or a C/C++ compiler is missing; the foundation-port example tests additionally skip when CABIN_NET_OFFLINE is set or when the host cannot reach the archive host - github.com:443 for most ports, www.sqlite.org:443 for sqlite3, and downloads.sourceforge.net:443 for libpng.