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
2 changes: 1 addition & 1 deletion docs/docs/developer/extending/encodings.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ wins:
1. **The consumer's override**, in `comline.toml`.
2. **The declaring package's `map`** for that language.

If neither answers for an encoding the package uses, `comline generate` fails
If neither answers for an encoding the package uses, `comline generation` fails
with one sentence per encoding:

```text
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/developer/extending/generators.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ stdout.

The two official generators, Rust and TypeScript, speak the same
protocol. The CLI links them in for speed, but calls them through the same
request and response types, so every `comline generate` exercises it.
request and response types, so every `comline generation` exercises it.

The protocol's every field is in the
[generator protocol reference](../../reference/generator-protocol.md). This page
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ comline check
## Generate code

```shell
comline generate
comline generation
```

Targets come from `code_generation.languages` in `config.idp` (the scaffold
Expand All @@ -101,5 +101,5 @@ Today `rust` and `typescript` are the generators.

- [Overview](guides/index.md) — the whole pipeline
- [IDL guide](guides/idl/index.md) — the schema language
- [Generating code](guides/codegen/generating-code.md) — the full `generate` surface
- [Generating code](guides/codegen/generating-code.md) — the full `generation` surface
- [CLI reference](reference/tools/cli/index.md) — every command and flag
28 changes: 14 additions & 14 deletions docs/docs/guides/codegen/generating-code.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Generating code

`comline generate` turns your compiled schemas into source code for a target
`comline generation` turns your compiled schemas into source code for a target
language. This page is the practical guide: what it produces, how to say where it
goes, and how to generate more than one version at once.

Expand All @@ -15,7 +15,7 @@ Code generation is configured across two files with two different owners:
| File | Owner | In version control | Purpose |
|---|---|---|---|
| `config.idp` | the **package author** | committed, frozen into every published version | declares *what languages* the package can be generated as |
| `comline.toml` | the **consumer** (whoever runs `generate`) | committed, never frozen | says *where* generated code goes, in what layout, for which versions |
| `comline.toml` | the **consumer** (whoever runs `comline generation`) | committed, never frozen | says *where* generated code goes, in what layout, for which versions |

`config.idp` never contains an output path — where your bindings land is your
call, not the package author's, so it lives in `comline.toml`.
Expand All @@ -39,7 +39,7 @@ toolchain** its generated code must build on. The `= {}` is required and takes
no options. See [Language versions](#language-versions) for what the version
promises and how it's checked.

Declaring a language is what makes it generated: `comline generate` emits every
Declaring a language is what makes it generated: `comline generation` emits every
language listed here. The entry carries no output path — where the code lands is
the consumer's business, below — and a consumer who wants fewer says so with
`only`.
Expand Down Expand Up @@ -211,19 +211,19 @@ idiomatic output for a past schema shape.
## Running it

```
comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--dry-run] [--list] [--watch]
comline generation [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--dry-run] [--list] [--watch]
```

`generate` validates the project and writes the code. Unlike `comline build` it
`generation` validates the project and writes the code. Unlike `comline build` it
does **not** freeze a version or write to `.comline/` — it is safe to run
repeatedly and from CI.
repeatedly and from CI. `gen` is short for `generation`.

```bash
comline generate # every configured target, per comline.toml
comline generate --target rust # just rust
comline generate --target rust --out ./bind # override this target's output root
comline generate --dry-run # report without writing anything
comline generate --watch # regenerate on schema / config change
comline generation # every configured target, per comline.toml
comline generation --target rust # just rust
comline generation --target rust --out ./bind # override this target's output root
comline generation --dry-run # report without writing anything
comline generation --watch # regenerate on schema / config change
```

Each target's files are reported as a tree:
Expand All @@ -245,8 +245,8 @@ Each target's files are reported as a tree:
generated at once. `--dry-run` and `--list` are independent: the first decides
whether anything is written, the second how it is reported.

`comline clean` removes the generated output (the whole `out` directory when it
is a dedicated one, e.g. `generated/`). It leaves `.comline/` alone —
`comline generation clean` removes the generated output (the whole `out` directory when it
is a dedicated one, e.g. `generated/`); `--target <lang>` removes only that language's. It leaves `.comline/` alone —
`comline reset` is the command that discards the version history.

## What Rust output looks like
Expand Down Expand Up @@ -325,7 +325,7 @@ for it.

## Gotchas

- `generate` never changes the package version. Only `build` does.
- `generation` never changes the package version. Only `build` does.
- The default layout writes under `generated/`. Older CLI versions wrote flat
into the project root; set `out = "."` and `layout = "{{namespace}}.{{ext}}"`
for that.
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/codegen/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ detail that the generated code is pleasant to use directly rather than only as a

## Using it

`comline generate` is the command; [Generating code](generating-code.md) is the
`comline generation` is the command; [Generating code](generating-code.md) is the
full guide, and [`comline.toml`](../../reference/package/congregation/comline-toml.md) is where a
consumer sets the output location, layout and mode.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/codegen/library-generation.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ that source into a **package**: a manifest (`Cargo.toml`, `package.json`) and
the module layout. A planned third mode, `dylib`, would compile it to a library
any language's [runtime](../runtime/index.md) can load.

`comline generate`'s `mode` chooses how far generation goes. It is set per target
`comline generation`'s `mode` chooses how far generation goes. It is set per target
in [`comline.toml`](../../reference/package/congregation/comline-toml.md) (`[generate] mode` or
`[[generate.target]] mode`).

Expand Down
6 changes: 3 additions & 3 deletions docs/docs/guides/idl/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,14 +255,14 @@ that out; the schema only says *that* something is unverified and *why*:
}
```

Nobody writes this by hand: `comline add` shows what a new dependency gives
up and asks before writing it, and `comline accept billing` (or
Nobody writes this by hand: `comline deps add` shows what a new dependency gives
up and asks before writing it, and `comline deps accept billing` (or
`billing::Billing`) does the same for one already declared. In the editor,
the dependency's entry in `config.idp` shows the error, with a quick fix
that writes the line. Until it's accepted, the build fails, printing the
entry. The list is a snapshot: if a
later version of the dependency gives up more, the build stops again until
`comline accept` is run again.
`comline deps accept` is run again.

How a call travels between caller and implementation is the
[runtime](../runtime/index.md)'s job, over a pluggable
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/idl/validator.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
a property or whose literal type is wrong, a missing argument for a property
without a default, or an undeclared `params.*` reference all fail the build. Generated **Rust** code then
[runs them](#in-generated-code). Generated TypeScript doesn't yet: it
generates the types without the checks, and `comline generate` warns. See
generates the types without the checks, and `comline generation` warns. See
[TypeScript's language reference](../../reference/languages/typescript.md#code-generation).

A **validator** is a named, parameterised check you attach to a
Expand Down
6 changes: 3 additions & 3 deletions docs/docs/guides/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ flowchart LR
I --> V["validate"]
V -->|"comline build"| F["freeze"]
F --> CAS[(".comline/<br/>version history")]
V -->|"comline generate"| G["generate"]
V -->|"comline generation"| G["generate"]
TOML["comline.toml<br/>where code goes"] --> G
G --> OUT["generated/"]
```

`comline check` stops after validating. `comline build` freezes a version;
`comline generate` writes code without freezing anything.
`comline generation` writes code without freezing anything.

## 1. Write a schema

Expand Down Expand Up @@ -53,7 +53,7 @@ last one. See [Versioning rules](../reference/versioning.md).

## 3. [Generate code](codegen/generating-code.md)

`comline generate` turns the schemas into source for each target language.
`comline generation` turns the schemas into source for each target language.
The package declares *which* languages it supports, in `config.idp`; whoever
generates decides *where* the code lands, in `comline.toml`
([the two files](codegen/generating-code.md#the-two-files)). One history can be
Expand Down
8 changes: 4 additions & 4 deletions docs/docs/guides/ir/cas.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ flowchart LR
| `objects/<xx>/<rest>` | One object. The 64 hex characters of its hash are split: the first two name the directory, the other 62 name the file. The file holds the object's bytes, LZ4-compressed. |
| `refs/heads/main` | The hash of the newest commit, as 64 hex characters. Updated at the end of every build and release. It is the only ref. |
| `FORMAT_VERSION` | The [IR format stamp](#the-ir-format-stamp) as a decimal number. |
| `deps-cache/` | Git dependencies fetched by `comline add` and by builds. A cache, not history. |
| `deps-cache/` | Git dependencies fetched by `comline deps add` and by builds. A cache, not history. |

### What to commit

Expand All @@ -55,7 +55,7 @@ writes ignores only that directory:
.comline/deps-cache/
```

`comline clean` never touches `.comline/`. `comline reset` deletes the whole
`comline generation clean` never touches `.comline/`. `comline reset` deletes the whole
directory, history included, behind a typed confirmation or `--force`. See
[Packages & dependencies](../packages/index.md) for the package layout.

Expand Down Expand Up @@ -326,9 +326,9 @@ See `comline release` in the [CLI reference](../../reference/tools/cli/index.md)
| `comline diff <old> <new>` | Two commits' root trees, compared with the same rules as a build: schema changes, changes within a dependency's reach, config changes and the bump they call for. |
| `comline inspect` | The newest build's `facts`, shown beside each protocol's wire summary. It writes nothing. See [`comline inspect`](../../reference/tools/cli/inspect.md). |
| `comline doc --version <v>` | A built version's schema blobs, its `config` for the package name, and its `docs` headers. `--changelog-from <v>` adds the changes since an earlier version. See [`comline doc`](../../reference/tools/cli/doc.md) and [Documenting your schemas](../documenting.md). |
| `comline generate` | With a pinned version or `"all"`, the frozen schemas of those versions. The default, `"latest"`, reads the working tree and not the store. |
| `comline generation` | With a pinned version or `"all"`, the frozen schemas of those versions. The default, `"latest"`, reads the working tree and not the store. |

`diff`, `doc --version` and `generate` find a commit by `HEAD`, a version
`diff`, `doc --version` and `generation` find a commit by `HEAD`, a version
string such as `0.3.0-dev.2`, or a commit hash (the full 64 characters, or a
prefix of 4 or more that matches one commit). They walk the chain from
`refs/heads/main` through each commit's first parent.
Expand Down
10 changes: 5 additions & 5 deletions docs/docs/guides/packages/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ That key is now an error that hands back the `wire` line to write instead.
## Consumer Side (`comline.toml`)

Where generated code lands, in what layout, for which versions — none of which
belongs to the package author — is set by whoever runs `comline generate`, in a
belongs to the package author — is set by whoever runs `comline generation`, in a
separate, non-frozen `comline.toml`. See
[Generating code](../codegen/generating-code.md) and the
[`comline.toml` reference](../../reference/package/congregation/comline-toml.md).
Expand Down Expand Up @@ -154,12 +154,12 @@ reports git's own error.
`config.idp`, and imports from it aren't checked until it is. More in
[Dependency packages in the editor](../../design/editor-dependency-packages.md).

`comline add` writes an entry for you, after resolving the dependency (a git pin
`comline deps add` writes an entry for you, after resolving the dependency (a git pin
is fetched), with its `hash` pinned to what it just compiled:

```bash
comline add shared_types ../shared-types
comline add net --git https://github.com/acme/net --commit 4f2c9e1 --version 1.2.0
comline deps add shared_types ../shared-types
comline deps add net --git https://github.com/acme/net --commit 4f2c9e1 --version 1.2.0
```

The rest of `config.idp` is left as written. `--no-hash` skips the pin, say for
Expand All @@ -177,7 +177,7 @@ recorded versions. The `comline new` scaffold's `.gitignore` ignores only
`.comline/deps-cache/`, where [git dependencies](#dependencies) are fetched.

!!! warning
`comline reset` deletes `.comline/` (behind a confirmation). `comline clean`
`comline reset` deletes `.comline/` (behind a confirmation). `comline generation clean`
does not — see [Versioning rules](../../reference/versioning.md#history-model).

## Publishing
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ same family as [Protocol Buffers](https://protobuf.dev/),
flowchart LR
S["schema<br/>.ids files"] --> C["comline build<br/>check and freeze"]
C --> V[("version history<br/>.comline/")]
C --> G["comline generate"]
C --> G["comline generation"]
G --> R["Rust code"]
G --> T["TypeScript code"]
R <-->|"calls over a<br/>transport"| T
Expand All @@ -43,7 +43,7 @@ changed since the last release, so a breaking change can't ship as a patch.

### [Generated code](./guides/codegen/index.md)

`comline generate` writes idiomatic code for each target language: types, a
`comline generation` writes idiomatic code for each target language: types, a
trait or interface per protocol, clients, servers and connections. Rust and
TypeScript are supported today, each in two forms: source files to drop into a
project, or a buildable package.
Expand Down
6 changes: 3 additions & 3 deletions docs/docs/languages/rust/connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,13 @@ left out when:
only once one JSON-RPC protocol in the package is client-provided; then they
all do.
- **The protocols on connections disagree** on the framing or the handshake.
No one connection carries them all, and `comline generate` warns, naming
No one connection carries them all, and `comline generation` warns, naming
both protocols. Each protocol still gets its own dispatcher and sender.
- **Only protocols from an external `std` are on a connection.** Only what
the crate emits counts.

When a package declares protocols but none is on a connection,
`comline generate` says so, and why.
`comline generation` says so, and why.

### Using them

Expand Down Expand Up @@ -85,7 +85,7 @@ let sent = ChatSender::new(&mut conn).send("hi")?;
([Framing & wire format](framing-and-wire-format.md)), and the framing and
handshake are the protocols'. When the protocols on connections disagree
on either, no one connection carries them all, so these functions aren't
generated and `comline generate` warns why.
generated and `comline generation` warns why.
- **A schema named `connection`** can't be used in `code` mode, since the
file would overwrite it.

Expand Down
6 changes: 3 additions & 3 deletions docs/docs/languages/typescript/connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,13 +38,13 @@ left out when:
only once one JSON-RPC protocol in the package is client-provided; then they
all do.
- **The protocols on connections disagree** on the framing or the handshake.
No one connection carries them all, and `comline generate` warns, naming
No one connection carries them all, and `comline generation` warns, naming
both protocols. Each protocol still gets its own dispatcher and sender.
- **Only protocols from an external `std` are on a connection.** Only what
the package emits counts.

When a package declares protocols but none is on a connection,
`comline generate` says so, and why.
`comline generation` says so, and why.

### Using them

Expand Down Expand Up @@ -82,7 +82,7 @@ const sent = await new chat.ChatSender(conn).send({ text: "hi" });
([Framing & wire format](framing-and-wire-format.md)); the framing and
handshake are the protocols'. When the protocols on connections disagree on
either, no one connection carries them all, so these functions aren't
generated and `comline generate` warns why.
generated and `comline generation` warns why.

## What codegen emits

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/languages/typescript/framing-and-wire-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Two codecs ship. Every `Codec` has a `name` (used in the handshake) plus

There's no MessagePack codec for TypeScript yet, so a TypeScript target
can't generate a package whose `wire.format` is `msgpack@1`: `comline build`
and `comline generate` refuse it.
and `comline generation` refuse it.

`u64` and `s64` (and `u128` / `s128`) are `bigint` in both codecs.

Expand Down
5 changes: 4 additions & 1 deletion docs/docs/reference/languages/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ language page can't claim something that isn't true.
| --- | --- |
| ✅ **supported** | Works. |
| 🟡 **partial** | Works, with the limit the note states. |
| ⚪ **ignored** | Succeeds, but the output is what it would be without the feature: the types are right, the feature has no effect. `comline generate` warns, and so does the editor. |
| ⚪ **ignored** | Succeeds, but the output is what it would be without the feature: the types are right, the feature has no effect. `comline generation` warns, and so does the editor. |
| ❌ **unsupported** | Is refused, with an error naming every use. The editor warns at each use. |

A runtime's claims use the same words, about the wire:
Expand Down Expand Up @@ -119,6 +119,9 @@ commit. A runtime's suite runs every example against it:
| JSON wire format <br><sub>`format-json`</sub> | ✅ supported | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57)) |
| MessagePack wire format <br><sub>`format-msgpack`</sub> | ✅ supported | ❌ unsupported: JSON and packed@1 ship |
| packed wire format <br><sub>`format-packed`</sub> | ✅ supported | ✅ supported |
| packed sizes <br><sub>`sizes-packed`</sub> | ✅ supported | ❔ not reported |
| MessagePack sizes <br><sub>`sizes-msgpack`</sub> | ✅ supported | ❔ not reported |
| JSON sizes <br><sub>`sizes-json`</sub> | ✅ supported | ❔ not reported |

<!-- runtime-matrix:end -->

Expand Down
Loading
Loading