Skip to content

Guide Overview

Comline takes a schema you write by hand and carries it through a fixed pipeline. Each stage has its own section in this guide; this page is the map.

flowchart LR
    subgraph author["You write"]
        IDP["config.idp<br/>the package"]
        IDS["src/*.ids<br/>the schemas"]
    end
    IDP --> P["parse"]
    IDS --> P
    P --> I["resolve imports<br/>and dependencies"]
    I --> V["validate"]
    V -->|"comline build"| F["freeze"]
    F --> CAS[(".comline/<br/>version history")]
    V -->|"comline generate"| 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.

1. Write a schema

A package is a directory with a manifest (config.idp) and one or more .ids schema files under src/:

comline new my-api      # scaffold config.idp + comline.toml + src/main.ids

A schema declares structs, enums, errors, constants, type aliases, protocols and validators, with docstrings on any of them. Annotations and settings tune how they're checked and generated.

2. Check and build

comline check parses, resolves imports and validates. comline build does that and then freezes the result into an intermediate representation, stored in the content-addressable store under .comline/ as a new commit in an append-only chain.

Each build is a pre-release version leading to the next release; comline release creates that version, bumped by the largest change since the last one. See Versioning rules.

3. Generate code

comline generate 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). One history can be generated for several past versions at once.

4. Run it

Generated code links against a runtime library, which runs the handshake, frames each call and encodes its values: the call system. The language guides show it in Rust and TypeScript.

Then