From be0c410e0c009eb0cbafc2794ab29b074aad063e Mon Sep 17 00:00:00 2001 From: Patrick Eanism Date: Sun, 20 Sep 2026 12:57:33 -0700 Subject: [PATCH] docs: the two build modes, and how to switch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Companion to softmata/horus#220. A managed project has no manifest cargo can find at the root, and until now nothing on the getting-started pages said so: a Rust developer's first `cargo build` failed with `could not find Cargo.toml` and no explanation. - quick-start: a callout at the first build naming the managed layout, the shell-integration route, and `horus eject` / `horus new --cargo` for a manifest cargo owns. - depending-on-horus: a "Managed, or cargo-native" section with the decision table (manifest, plain cargo, horus commands, [rust], horus add), the three ways to go cargo-native, and what the shell proxy does; the target-section row in the "what horus new generates" table now names tests/examples/ benches/src/bin and the [lib] case. - cli-reference: a `horus eject` section (what it writes, what changes after, when it refuses) and the `--cargo` flag on `horus new`. - testing: a tests/ directory runs without a root Cargo.toml now — top-level tests/*.rs are declared as targets, nested modules stay helpers. --- content/docs/development/cli-reference.mdx | 56 +++++++++++++++++++ .../docs/development/depending-on-horus.mdx | 39 +++++++++++++ content/docs/development/testing.mdx | 7 +++ content/docs/getting-started/quick-start.mdx | 13 +++++ 4 files changed, 115 insertions(+) diff --git a/content/docs/development/cli-reference.mdx b/content/docs/development/cli-reference.mdx index fe835650..b04ebbdd 100644 --- a/content/docs/development/cli-reference.mdx +++ b/content/docs/development/cli-reference.mdx @@ -156,6 +156,8 @@ Options: flags do not apply -w, --workspace Create as a workspace with multiple crates -l, --lib Create as a library crate (instead of binary) + --cargo Create a cargo-owned project: a root Cargo.toml, + not the generated .horus/Cargo.toml -o, --output Where to create it (default: current directory) -y, --yes Accept defaults without prompting ``` @@ -196,6 +198,60 @@ horus new robot_controller --output ~/projects/robots --- +## `horus eject` - Hand the Build to Cargo + +**What it does**: Writes a root `Cargo.toml` from the generated +`.horus/Cargo.toml` and stops owning the build. Plain `cargo build`, `cargo run` +and `cargo test` work from then on, and `horus build`/`run`/`test` build from +your manifest. + +**Why it's useful**: A managed project (`horus new`) has no manifest cargo can +find at the project root, so `cargo build` fails with `could not find +Cargo.toml`. Eject is for editors, scripts, CI, and muscle memory that expect a +normal Rust crate. + +### Basic Usage + +```bash +horus eject +``` + +### Options + +```bash +horus eject [OPTIONS] + +Options: + --force Replace an existing root Cargo.toml +``` + +### What Gets Written + +- Every target the generated manifest declared — `src/main.rs`, `src/bin/*`, + `tests/*`, `examples/*`, `benches/*`, and `[lib]` for a library — with its + path rewritten relative to the project root. +- The HORUS dependencies, as absolute paths to the source tree HORUS resolved + when it wrote the file. Moving or upgrading that tree breaks them until you + repoint them or eject again. +- The two `[patch]` tables the generated manifest carried, so resolution keeps + working. + +What changes after an eject: + +- `[rust]` in `horus.toml` is **ignored** — profiles, lints and features belong + in `Cargo.toml` now. `horus doctor -v` reports the mode as `cargo-native`. +- `.horus/Cargo.toml` is deleted; the root manifest is the only source of truth, + and HORUS never regenerates it. +- `horus build`/`run`/`test` still work: they detect the root manifest and run + cargo against it. + +An existing root `Cargo.toml` is refused unless `--force`. Workspace projects +already build from a generated root workspace manifest, and non-Rust projects +have no Cargo manifest to eject. To start cargo-native instead, use +`horus new my_robot --cargo`. + +--- + ## `horus run` - Build and Run **What it does**: Compiles your code and runs it. Handles all the build tools for you. diff --git a/content/docs/development/depending-on-horus.mdx b/content/docs/development/depending-on-horus.mdx index 9ce391d0..7f1884f3 100644 --- a/content/docs/development/depending-on-horus.mdx +++ b/content/docs/development/depending-on-horus.mdx @@ -149,6 +149,7 @@ What `generate` emits, in the order it emits it: | A `[[bin]]` per entry point | `cargo_gen.rs:67-97` | The sources live outside `.horus/`, so each target needs an explicit `path` | | `horus`, `horus_core`, `horus_macros` as path dependencies | `cargo_gen.rs:1062-1093` | Without them the section is emitted empty and the build fails with a wall of "cannot find type Topic/Scheduler" instead of an actionable message (`cargo_gen.rs:108-113`) | | `serde = { version = "1", features = ["derive"] }` | `cargo_gen.rs:970-988`, literal at `:984` | The `message!` macro expands to `serde::Serialize`, so serde has to be a **direct** dependency of your crate; transitive is not enough | +| `[[bin]]`, `[lib]`, `[[test]]`, `[[example]]`, `[[bench]]` for the project's targets | `cargo_gen.rs`, `write_layout_targets` | Cargo discovers targets relative to the manifest's directory, which is `.horus/` — so `tests/`, `examples/`, `benches/` and `src/bin/` have to be declared or they compile to nothing. Top-level `*.rs` files are targets, `dir/name/main.rs` is a target named `name`, and nested modules (`tests/common/mod.rs`) are helpers, matching cargo | | `[patch."…horus-robotics.git"]` and `[patch."…horus-tf.git"]` | `cargo_gen.rs:1100-1109` and `:1260-1325`, called last at `:146` | The next section | Two details worth knowing. The path-dependency loop at `cargo_gen.rs:1066` tries @@ -160,6 +161,44 @@ because a backslash in a TOML string is an escape and `C:\Users\…` made the generated manifest unparseable before cargo could read it (`cargo_gen.rs:941-959`). +## Managed, or cargo-native + +A HORUS project is in one of two modes, and which one it is decides whether a +plain `cargo` command works. + +| | **Managed** (what `horus new` writes) | **Cargo-native** | +|---|---|---| +| Manifest | `horus.toml`; `.horus/Cargo.toml` is generated and gitignored | root `Cargo.toml` | +| Plain `cargo build` / `run` / `test` | fails — no manifest at the project root | works normally | +| `horus build` / `run` / `test` | generate the manifest, run cargo in `.horus/` | run cargo against your manifest | +| `[rust]` in `horus.toml` | applies (profile, lints, features, rustflags) | **ignored** | +| `horus add` | writes to `horus.toml` | writes to `Cargo.toml` | + +`horus doctor -v` prints which mode the project is in. + +There are three ways to get a cargo-native project: + +- `horus new my_robot --cargo` — start that way. +- `horus eject` — convert a managed project: it writes the root `Cargo.toml` + from the generated one, rewrites every relative path (targets and local path + dependencies), deletes `.horus/Cargo.toml` so there is only one source of + truth, and refuses to replace an existing root manifest without `--force`. +- Write the manifest yourself, as the rest of this page describes — the right + route for adding HORUS to a crate you already have. + +Once a root `Cargo.toml` exists, `horus build`/`run`/`test` build from it and +never regenerate `.horus/Cargo.toml`; artefacts still land in `.horus/target` +because every cargo spawn gets `CARGO_TARGET_DIR` set. The two `[patch]` tables +below are still required — they belong in the root manifest now, not in +`horus.toml`. + +In managed mode, shell integration is the other way to keep using cargo: the +installer runs `horus env --init`, which shadows `cargo` with a function that +routes it through `horus cargo` inside HORUS projects and to the real binary +everywhere else. Without that function installed, a bare `cargo build` in a +managed project fails with `could not find Cargo.toml`, and the command to use +is `horus build`. + ## The two `[patch]` tables, and why nothing resolves without them `horus` depends on `horus-robotics` and `horus-tf` as git dependencies. Both of diff --git a/content/docs/development/testing.mdx b/content/docs/development/testing.mdx index 779e9570..6537973a 100644 --- a/content/docs/development/testing.mdx +++ b/content/docs/development/testing.mdx @@ -764,6 +764,13 @@ mod tests { } ``` +A `tests/` directory at the project root works too: `horus test` declares every +top-level `tests/*.rs` (and `examples/`, `benches/`, `src/bin/`) as a cargo +target in the generated manifest, so a normal integration-test layout runs +without a root `Cargo.toml`. Nested modules like `tests/common/mod.rs` stay +helpers, as they do in cargo. In a cargo-native project (`horus eject`, or +`horus new --cargo`) plain `cargo test` sees the same files. + ## Time-Limited Test Runs Use `scheduler.run_for()` to run tests for a fixed duration: diff --git a/content/docs/getting-started/quick-start.mdx b/content/docs/getting-started/quick-start.mdx index 593cf85d..4fe416fb 100644 --- a/content/docs/getting-started/quick-start.mdx +++ b/content/docs/getting-started/quick-start.mdx @@ -197,6 +197,19 @@ Temperature: 20.4°C Press **Ctrl+C** to stop. + +`horus new` creates a **managed** project: `horus.toml` is the manifest and +`.horus/Cargo.toml` is generated, which is why a bare `cargo build` here fails +with `could not find Cargo.toml`. Build with `horus run`, `horus build` or +`horus test`. If the installer set up shell integration (`horus env --init`), +plain `cargo` commands inside projects route through HORUS and work too. + +Want a manifest cargo owns? `horus eject` writes a root `Cargo.toml` from the +generated one, and `horus new my_robot --cargo` starts that way. From then on +`cargo build`/`run`/`test` work directly, and `[rust]` in `horus.toml` no longer +applies. See [Depending on HORUS](/development/depending-on-horus). + + Several lines of scheduler and real-time output appear above the temperatures. The one