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
56 changes: 56 additions & 0 deletions content/docs/development/cli-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <PATH> Where to create it (default: current directory)
-y, --yes Accept defaults without prompting
```
Expand Down Expand Up @@ -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.
Expand Down
39 changes: 39 additions & 0 deletions content/docs/development/depending-on-horus.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
7 changes: 7 additions & 0 deletions content/docs/development/testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
13 changes: 13 additions & 0 deletions content/docs/getting-started/quick-start.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,19 @@ Temperature: 20.4°C

Press **Ctrl+C** to stop.

<Callout type="info" title="Two ways to build — and why plain `cargo build` is not one of them">
`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).
</Callout>

<Callout type="info" title="Scheduler lines before the first reading are normal">

Several lines of scheduler and real-time output appear above the temperatures. The one
Expand Down
Loading