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
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ comline generate # write generated code for each configured target
| Command | What it does |
|---|---|
| `comline new <name> [--git]` | Scaffold `<name>/` with `config.idp`, `comline.toml`, `src/main.ids` and a `.gitignore`. `--git` also runs `git init`. |
| `comline check` | Parse, resolve and validate every schema. No `.comline/` writes, no version bump — safe for editors, hooks and CI. |
| `comline add <name> <dir>` / `comline add <name> --git <uri> --commit <sha> --version <v>` | Add a dependency to `config.idp`: resolved first (a git pin is fetched), then written with its content `hash` pinned. `--no-hash` skips the pin. |
| `comline check` | Parse, resolve and validate every schema. No `.comline/` writes (beyond fetching git dependencies), no version bump — safe for editors, hooks and CI. |
| `comline build [--release] [--watch]` | Compile, validate, and freeze a new immutable version into `.comline/`. Prints the changelog and the version bump. |
| `comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--watch]` | Validate (no freeze), then write generated code. Output location/layout come from `comline.toml` `[generate]`; targets from there or `config.idp`. |
| `comline diff <old> <new>` | Show the schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash, or `HEAD` (the default for `<new>`). |
Expand Down
40 changes: 38 additions & 2 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ This is the long-form reference. For a two-minute tour see the
- [Versioning model](#versioning-model)
- [Commands](#commands)
- [`new`](#comline-new)
- [`add`](#comline-add)
- [`check`](#comline-check)
- [`build`](#comline-build)
- [`generate`](#comline-generate)
Expand Down Expand Up @@ -139,15 +140,50 @@ comline new my-api
comline new my-api --git
```

### `comline add`

```
comline add <name> <dir> [--no-hash]
comline add <name> --git <uri> --commit <sha> --version <version> [--no-hash]
```

Declare another Comline package as a dependency, imported under `<name>`:
`use <name>::models::Thing`. It is resolved first, the way `check` resolves it,
so an entry that wouldn't resolve is never written:

- `<dir>` — a package on disk, relative to this package's directory (written to
`config.idp` as given);
- `--git <uri> --commit <sha> --version <version>` — a commit of a git
repository, fetched into `.comline/deps-cache/` with the `git` binary.
`--version` is the version that commit stands for.

The entry goes into `config.idp`'s `dependencies` block, created at the end of
the file if there isn't one, in the file's own indentation; every other line is
left as written. Its `hash` is pinned to the content just compiled, so if the
dependency changes later, `check` and `build` fail until the pin is updated.

- `--no-hash` — don't pin the hash (say, a path dependency still being worked
on).

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

Exit `0` once added, `1` if the dependency doesn't resolve or can't be added
(the name is already declared, isn't an identifier, or is already one of this
package's own namespaces), `2` if the directory is not a Comline project.

### `comline check`

```
comline check
```

Parse, resolve and validate every schema and the package config, reporting the
first error found. It writes **nothing** to `.comline/` and does **not** bump the
version — safe to run from editors, pre-commit hooks and CI lint steps.
first error found. It writes **nothing** to `.comline/` (beyond fetching git
dependencies into `.comline/deps-cache/`) and does **not** bump the version —
safe to run from editors, pre-commit hooks and CI lint steps.

```bash
comline check
Expand Down
43 changes: 43 additions & 0 deletions src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,49 @@ pass `--force`.")]
git: bool,
},

/// Add a dependency to `config.idp`, resolved and pinned
#[command(long_about = "\
Declare another Comline package as a dependency. It is resolved first, the way \
`check` resolves it (a git pin is fetched into `.comline/deps-cache/`, then \
compiled), so an entry that wouldn't resolve is never written. Its entry then \
goes into `config.idp`'s `dependencies` block, with `hash` pinned to the content \
just compiled: if the dependency changes later, the build fails until the pin is \
updated. The rest of `config.idp` is left as written.

Its schemas are imported under NAME: `use NAME::models::Thing`.

Examples:
comline add shared_types ../shared-types
comline add net --git https://github.com/acme/net --commit 4f2c9e1 --version 1.2.0")]
Add {
/// Name to import it under (`use <NAME>::...`)
name: String,

/// A package on disk, relative to this package's directory
#[arg(
value_name = "DIR",
required_unless_present = "git",
conflicts_with = "git"
)]
dir: Option<PathBuf>,

/// Fetch it from this git repository instead
#[arg(long, value_name = "URI", requires_all = ["commit", "version"])]
git: Option<String>,

/// Commit to pin (with `--git`)
#[arg(long, value_name = "SHA", requires = "git")]
commit: Option<String>,

/// Version that commit stands for (with `--git`)
#[arg(long, value_name = "VERSION", requires = "git")]
version: Option<String>,

/// Don't pin its content hash (say, a path dependency still being worked on)
#[arg(long)]
no_hash: bool,
},

/// Print a shell completion script to stdout
#[command(long_about = "\
Write a completion script for the given shell to stdout.
Expand Down
Loading
Loading