From acd3cccbe1a8d524e6184f21dbea9ddb3612fc92 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 4 Oct 2026 09:35:39 +0800 Subject: [PATCH] docs: document lib mode's flatten and that layout doesn't apply to it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follows ComlineProject/cli#36 (flatten) — the comline.toml reference and Library generation guide were both silent on lib mode ignoring layout entirely, which is exactly what prompted a real "why is it nesting under rust/" bug report. --- docs/docs/guide/codegen/library-generation.md | 8 ++++-- docs/docs/reference/comline-toml.md | 26 ++++++++++++++++++- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/docs/guide/codegen/library-generation.md b/docs/docs/guide/codegen/library-generation.md index 221aa2c..2dda020 100755 --- a/docs/docs/guide/codegen/library-generation.md +++ b/docs/docs/guide/codegen/library-generation.md @@ -42,8 +42,12 @@ something you `cargo add` / `pip install` / `luarocks install`, or publish. Implemented for **rust**: `/rust/` gets a `Cargo.toml` (package name from the congregation, `serde` dependency), `src/lib.rs`, and `src/.rs` per -schema. Other languages, multi-version `lib` output, and a schema whose namespace -is nested (`a/b`) are not done yet. +schema — `/` keeps this target's crate from colliding with another +`lib` target sharing the same `out`; a target with `out` to itself can set +[`flatten = true`](../../reference/comline-toml.md#flatten) to skip that and +land the crate straight into `out`. `layout` plays no part in any of this — +it only applies to `code` mode. Other languages, multi-version `lib` output, +and a schema whose namespace is nested (`a/b`) are not done yet. **Use it when** the schema is shared: diff --git a/docs/docs/reference/comline-toml.md b/docs/docs/reference/comline-toml.md index b8403c8..beab64d 100644 --- a/docs/docs/reference/comline-toml.md +++ b/docs/docs/reference/comline-toml.md @@ -16,7 +16,7 @@ Defaults for every target. |---|---|---|---| | `out` | string (path) | `"generated"` | Output root, relative to `comline.toml`. | | `layout` | string (template) | `"{{language}}/{{namespace}}.{{ext}}"` | Path of each generated file under `out`. Handlebars, strict. | -| `mode` | `"code"` \| `"lib"` \| `"dylib"` | `"code"` | Emit form. Only `code` is implemented. | +| `mode` | `"code"` \| `"lib"` \| `"dylib"` | `"code"` | Emit form. `code` is implemented for every generator; `lib` for `rust`; `dylib` is planned — see [Library generation](../guide/codegen/library-generation.md). | | `package_versions` | `"latest"` \| `"all"` \| list | `"latest"` | Which package versions to emit — see [below](#package_versions). | | `default_framing` | string | — | Wire framing for protocols that don't pick one with [`@framing`](../guide/idl/protocol.md#protocol-annotations) — see [below](#default_framing). | @@ -30,6 +30,7 @@ be repeated here to override it for this target only. | `language` | string | **Required.** Must be one the manifest declares under `code_generation.languages`. | | `lang_version` | string | Optional; selects a version-specific generator. Defaults to what `config.idp` declared. | | `out`, `layout`, `mode`, `package_versions`, `default_framing` | — | Per-target override of the `[generate]` value. | +| `flatten` | bool | `lib`/`dylib` only, target-only (no `[generate]` default): write the crate straight into `out` instead of `out//`. See [below](#flatten). | ```toml [generate] @@ -42,6 +43,29 @@ lang_version = "1.70.0" out = "src/generated" ``` +### `flatten` + +`layout` only governs `code` mode's one-file-per-schema paths — a `lib`-mode +target ignores it entirely (`comline generate` warns if one is set) and +always writes the crate's fixed internal shape (`Cargo.toml`, `src/lib.rs`, a +file per schema under `src/`) rooted at `out//`, so two `lib` +targets can safely share one `out` without their files colliding. + +A target with its own dedicated `out` doesn't need that disambiguation — +`flatten = true` skips it, writing the crate straight into `out`: + +```toml +[[generate.target]] +language = "rust" +mode = "lib" +out = "../my-rust-crate/" +flatten = true # crate lands at out/, not out/rust/ +``` + +Only set this when the target's `out` is exclusively its own — flattening a +shared `out` across more than one `lib` target reintroduces the collision +the default layout avoids. + ## Layout variables | Variable | Value |