# Build Locally

Use local builds while iterating on runtime package sets, channel choices, or
conda-ship runtime behavior.

Packaged local builds find the runtime template installed next to `cs`
automatically. When your manifest contains `[tool.conda-ship].runtime`, a
normal build is:

```bash
cs build
```

Source checkouts do not build a runtime template implicitly. Install
conda-ship from a package that includes `cs-template`, or pass
`--template` with an explicit prebuilt template.

```{note}
Most local users should install conda-ship from a package and let `cs` find the
installed `cs-template`. Use `--template` only for custom packaging,
cross-builds, or template debugging.
```

If you are changing a downstream distribution such as conda-express, keep the
package-set decision in that downstream project, then reproduce the build with
the `cs` CLI or the GitHub Action.

## Check The Runtime Input

When you want to check the selected source environment before building, run:

```bash
cs inspect
```

```{figure} ../../demos/inspect.gif
:alt: Terminal recording of cs inspect deriving and printing the runtime package set.

Inspect a source environment before shipping it.
```

If you changed the configured source environment, refresh the source lockfile
with the tool that owns the manifest:

::::{tab-set}

:::{tab-item} conda-workspaces

```bash
conda workspace lock
cs inspect
```

Use this for `conda.toml` and `pyproject.toml` with `[tool.conda]`.
:::

:::{tab-item} Pixi

```bash
pixi lock
cs inspect
```

Use this for `pixi.toml` and `pyproject.toml` with `[tool.pixi]`.
:::

::::

CI can use JSON output for machine-readable preflight checks:

```bash
cs inspect --json
```

Use `build --dry-run` when you want to validate artifact names, template
selection, install settings, and bundle suitability without writing files:

```bash
cs build --dry-run
```

```{figure} ../../demos/dry-run.gif
:alt: Terminal recording of cs build --dry-run previewing online and embedded runtime artifacts.

Preview runtime metadata and artifact names without writing release files.
```

## Build A Runtime

`[tool.conda-ship].runtime`, `[tool.conda-ship].delegate`,
`[tool.conda-ship].source-environment`, and a downstream runtime version are
required unless you pass the runtime, delegate, and version through CLI flags.
conda-ship does not provide default values for them. The version can come from
`[tool.conda-ship].runtime-version`, static `[project].version`, or explicit
project metadata resolution.

```bash
cs build
```

Use `--out-dir` to stage somewhere other than `dist/`:

```bash
cs build \
  --out-dir /tmp/cs-artifacts
```

Pass `--template` when you need an explicit release template asset, custom
packaging path, or cross-build template. conda-ship does not search `PATH` for
templates.

## Run A Smoke Test

Use `cs run` to build and immediately execute the staged runtime:

```bash
cs run \
  -- --path /tmp/demo-smoke bootstrap
```

Everything after `--` is passed to the generated runtime.

## Build For Another Target

Pass a target triple, an artifact label, and a matching prebuilt template:

```bash
cs build \
  --runtime demo \
  --target x86_64-unknown-linux-gnu \
  --target-label x86_64-unknown-linux-gnu \
  --template ./cs-template-x86_64-unknown-linux-gnu
```

The target label is appended to staged artifact names and metadata files.

## Keep Names Distribution-Specific

Use a runtime name owned by the distribution you are building. For example,
conda-express uses `cx` as its runtime name. The online layout stages `cx`; the
embedded layout stages `cxz`. A different distribution uses a different
`[tool.conda-ship].runtime` value or the `--runtime` override.

## Run Release Checks

Before publishing a conda-ship release, run the same local checks used for
the release pass:

```bash
pixi run test
pixi run lint
pixi run -e test pytest
pixi run -e test ruff-check
pixi run -e test ruff-format-check
pixi run docs
cargo audit --deny warnings
cargo deny check
zizmor --persona auditor .
```

`cargo deny check` enforces the repository's Rust advisory, license, dependency
ban, and source policies. Duplicate dependency versions are warnings for now
because the rattler dependency graph still contains expected overlap.