comline.toml

Consumer-owned configuration for comline generate: where generated code goes, in what layout, in what form, and for which package versions. Its [doc] table configures comline doc. It is committed, never frozen, and never part of a published package. With no comline.toml (or an all-commented one) the defaults below apply and targets come from config.idp's code_generation.languages.

For the task-oriented walkthrough see Generating code.

[generate]

Defaults for every target.

[[generate.target]]

One block per declared language you want to configure. Any key from [generate] may be repeated here to override it for that language only.

A block configures a language; it does not choose which languages are generated. That comes from config.idp alone — a declared language with no block takes the [generate] defaults, several blocks for one language give several outputs, and a block naming a language the congregation doesn't declare is an error. To generate fewer than the package declares, use only.

[generate]
out    = "generated"
layout = "{{language}}/{{namespace}}.{{ext}}"

[[generate.target]]
language     = "rust"
lang_version = "1.88.0"
out          = "src/generated"

generator

[[generate.target]]
generator = "tools/comline-gen-go.wasm"
language  = "go"
timeout   = 120

Runs a generator that is its own program, speaking the generator protocol. language picks among the languages it offers, and may be left out if it offers one; it must still be one config.idp declares. A .wasm runs sandboxed; anything else runs as a native process, unsandboxed. The limits and path rules are in Generators.

encodings

[generate]
encodings = { "com.acme.lines@1" = "acme_lines::LinesFraming" }

[[generate.target]]
language  = "rust"
encodings = { "com.acme.lines@1" = { type = "acme_lines::LinesFraming", package = "acme-lines", version = "0.1" } }

Maps an encoding's name to the type that implements it, in the target's language. A value is the type alone, or a table with type and optionally package and version. For each encoding the package uses, the first of these that answers wins: this table (the target's over [generate]'s), then the map the declaring package suggests in its config.idp. An encoding that is used and has no mapping is a generation error. See Map it to a type.

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/<language>/, 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:

[[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.

external_std

Comline's standard library is implicitly available to every package, so std/http and std/validators are part of every generation request. This decides whether their code is copied into your generated output or referenced from std's own pre-generated package:

It defaults to on in lib mode — a buildable package should depend on std rather than vendor it — and off in code mode, which has no manifest to declare a dependency in. In code mode with it on, the generated file names what to install in a comment at the top.

--external-std and --no-external-std override it for one run.

Neither package is published yet, so a lib target that references one needs it linked locally (npm link, a path override) until that changes — which is already true of @comline/runtime for any package with a protocol.

validate_on_decode

Generated code always carries a schema's @validators checks as validate() / validate_first(), for you to call. This decides whether decoding calls them too:

Validators are enforced by default: a schema's checks hold wherever its values are decoded. Choosing between collect and first is yours rather than the schema's: a form that wants every problem at once and a hot path that wants to stop early want different things from the same type. A provider also refuses a call whose arguments fail their checks, the same way it refuses arguments that don't decode.

Not running them is a give-up, like @unverified, and it carries its reason:

[generate]
validate_on_decode = { off = "the gateway validates every request first" }

A bare "off" is refused, with that fix. comline generate notes each target that gives it up, with the reason, and comline inspect lists it after the protocols (--json: validate_on_decode_given_up).

Today only the rust generator runs validators; typescript ignores this. --validate-on-decode collect|first and COMLINE_GENERATE_VALIDATE_ON_DECODE override it for one run; turning it off is written in comline.toml, where its reason is kept.

async

A protocol on a connection is generated for a blocking driver by default. async = true generates it for an async one instead:

• rust: async handlers, <Proto>AsyncDispatcher and <Proto>AsyncSender, and an async package serve / accept / connect, for the runtime's AsyncConnection on any executor — see Rust connections. A lib package turns on the runtime's async feature.
• typescript: nothing changes; its handlers and senders return Promises either way.

Every protocol is on a connection unless it's lockstep (the datagram framing, or JSON-RPC with no client-provided protocol); those are the same either way, and comline generate warns when async = true changes nothing. Like external_std, it's a consumer's choice: the same package can be generated async for one application and blocking for another.

only

Generate a subset of the languages config.idp declares, for a checkout that doesn't need all of them:

[generate]
only = ["rust"]

A name the congregation doesn't declare is an error, so a typo fails loudly instead of quietly generating nothing. --target narrows a single run the same way.

This is also the escape hatch when a declared language has no generator in your comline build: declaring a language means you mean it, so a missing generator is an error rather than a silent skip, and only is how you say you want fewer.

[doc]

Settings for comline doc. Each key but renderer, timeout and links has a flag that overrides it.

[doc]
out = "site/docs/api"
formats = ["html", "markdown"]
versions = { since = "0.3.0", last = 10 }
links = { std = "https://example.com/std" }

Layout variables

package_versions

Anything but "latest" reads the content-addressable store, so the project must have been built at least once. Selecting more than one version requires {{package_version}} in layout — otherwise every version writes to the same paths. Old schemas are emitted with the current generator.

[generate]
package_versions = "all"
layout           = "{{language}}/{{package_version}}/{{namespace}}.{{ext}}"

default_framing (moved)

The framing is part of the schema, since both ends have to agree on it, so it moved to the package: config.idp's wire = { framing = "..." } (Wire defaults). A default_framing, in [generate] or in a target, is an error that names the line to write there instead:

`default_framing` moved from comline.toml to config.idp
  help: drop it here, and declare the package's framing in config.idp:
      wire = { framing = "jsonrpc" }

Precedence

Lowest to highest, applied field by field:

built-in defaults → [generate] → [[generate.target]] → COMLINE_GENERATE_* env → CLI flags

• COMLINE_GENERATE_OUT / COMLINE_GENERATE_LAYOUT / COMLINE_GENERATE_MODE — apply to every target (a CI global). Empty values are ignored.
• --out / --layout / --mode — apply to one target and need --target when more than one is configured.

Editor support

comline.toml has a JSON Schema, served at https://comlineproject.github.io/docs/schemas/comline-toml/0.x.json. With it an editor completes keys, checks values, and shows each key's description on hover. comline new writes the pointer as the first line of the file:

#:schema https://comlineproject.github.io/docs/schemas/comline-toml/0.x.json

In VS Code, the Comline extension gives comline.toml its own language, and the Comline language server checks it against the package next to it, with or without the line. On top of the schema's checks it reports:

• a language that config.idp doesn't declare;
• a version no built-in generator handles;
• an encodings key that no package in view declares;
• an encoding the package uses but leaves unmapped;
• a generator path that isn't a file.

It completes language from config.idp and encodings keys from their declarations, and its quick fixes correct a misspelt key or value, or declare a missing language in config.idp. It never runs a generator.

In other editors, any TOML language server that reads the #:schema directive picks the schema up, such as Taplo.