Command line

Five subcommands: build runs a recipe, plan resolves and orders one without building, export copies what a work directory holds out for an archive, prune removes what the pool no longer serves, and check reports whether the pool’s packages can be installed. All five take a recipe directory and the same target options.

src2deb build  RECIPE_DIR [options]
src2deb plan   RECIPE_DIR [options]
src2deb export RECIPE_DIR --to DIR [options]
src2deb prune  RECIPE_DIR [options]
src2deb check  RECIPE_DIR [options]

RECIPE_DIR is a directory containing a recipe.toml. Exactly one is required, and it may appear before or after the options.

Each subcommand takes the work directory’s exclusive lock for as long as it runs, so only one of them works on a --work directory at a time.

Target options

Each overrides the corresponding recipe field, so one recipe serves every target it builds against.

The last two are not accepted where they would do nothing: an export carries packages a run already stamped, and a prune and a check read a pool, so none of them has a version to tag, and neither a prune nor a check has arch-indep output to hand anywhere. Naming one there is a usage error rather than a silently ignored flag.

Every value is validated as it is parsed, so a malformed one is a usage error against the flag rather than a failure partway into the run — including a --architecture naming the same architecture twice. Each suite and architecture pair gets its own pool, output tree, manifest, and build roots, so runs for several targets share one --work directory. See Cross-architecture builds and Package versions.

Build options

--only and --from are mutually exclusive, and --jobs takes an integer of 1 or more.

Both --only and --from narrow a run to part of its recipe, so whatever the selected components build-depend on comes from the archive or from the pool. A selection that leaves out a component producing one of those build-dependencies is refused before anything is provisioned, naming the component to add. See What a narrowed run needs from the pool.

Plan options

plan still clones every component’s source, because the build order is read from every debian/control. It takes the same exclusive lock on its work directory that build does, so planning while a build runs wants a --work directory of its own.

--runtime-deps reads each component’s packaging for the runtime relationships it declares and answers them against the target suite, the recipe’s repositories, the pool as it stands, and the packages the recipe itself will build. See Before the build.

The order is one answer whatever the recipe targets, since neither the sources nor the order depends on an architecture. What does is announced as the plan runs: each architecture the recipe names, whether it is foreign, and whether it would produce the recipe’s Architecture: all packages.

A component that declares its version gets a line for it, which is where to see what version-from = "git-describe" derived before a build stamps it into a package:

  1. foo @ source 1f3a9c2e5b7d, packaging 8d4b0e1c7a92
     version: 1.2.3

Export options

An export carries every component the work directory records as built, not only what the last run produced, and replaces whatever the export before it left in the same directory. See Publishing to an archive.

Prune options

Pruning covers the pool for a suite, which is shared by every recipe built into the work directory for it. See Pruning the pool.

Check options

A check resolves each pool package’s Depends and Pre-Depends against the target suite, the recipe’s repositories, and the pool, and reports what nothing satisfies. It exits non-zero when anything is unsatisfiable, so it gates a publish; a build ends with the same check over the pools it published into, as a note that does not fail the run. See Checking installability.

Verbosity

Given both, the last on the command line wins. See Provisioning progress.

Information

Either wins over the rest of the command line, so src2deb build recipes/x --help prints usage.

Streams

Progress, notes, and the closing summary go to standard error. The build order plan produces goes to standard output, so it stays pipeable while a run narrates alongside it:

src2deb plan recipes/cosmic-epoch | tail -5

In-cage build output is passed through to standard error, indented by two spaces. Under --jobs N each line also carries its component’s name. See In-cage build output.

Exit status

130 outranks a component failure: a cancelled run did not finish, so nothing follows about the components it never reached. The failure is still in the summary and the manifest. See Cancelling a run.