How Generated Runtimes Work#

When you run cs build, conda-ship does not invent a new program from scratch. It starts with a small generic runtime template, copies it to the resolved runtime name, and writes your build data into that copy. The runtime name can come from [tool.conda-ship].runtime or from --runtime.

Users rarely need to think about the template. They run the finished runtime, such as demo, demoz, cx, or cxz.

What cs build Writes#

During a runtime build, conda-ship writes these details into the copied binary:

  • runtime name, display name, and delegate executable

  • install scheme and install name

  • install method, when configured

  • runtime lock

  • optional compressed package bundle

  • documentation URL

  • metadata filename

  • bundle and offline environment variable names

That is what turns the same generic bootstrap code into a specific runtime with its own runtime name, delegate, package set, help links, and install location.

Where The Template Comes From#

For packaged builds, the template is downloaded from conda-ship’s GitHub Release assets. The asset name includes the platform it runs on, for example:

cs-template-x86_64-unknown-linux-gnu
cs-template-aarch64-apple-darwin
cs-template-x86_64-pc-windows-msvc.exe

You usually only see those names when wiring a packaging job. The GitHub Action downloads the matching template automatically. A packaged cs CLI looks for an installed cs-template next to the cs executable; it does not search arbitrary PATH entries for a template. --template PATH is an override for custom packaging or cross-builds.

The template is not a runtime. Running it directly fails with a message that points back to cs build; only the stamped copy has a runtime name, lockfile, package metadata, and install policy.

When running from a source checkout, cs build still expects either an installed template next to cs, a CONDA_SHIP_TEMPLATE environment variable, or an explicit --template PATH.

What Users See#

The finished runtime has a small command surface:

  • bootstrap: install conda into the runtime’s install path

  • status: report runtime and install details

  • shell: start a conda-spawn subshell

  • uninstall: remove the install path

All other commands are passed through to the configured delegate executable after bootstrap.

The base prefix is protected with a CEP 22 frozen marker. Users create named environments for regular package work.

What Each Project Chooses#

Some runtime behavior is visible to users:

  • conda-spawn based activation through RUNTIME shell

  • disabled activate, deactivate, and init commands with guidance when the delegate is conda

  • automatic bootstrap before pass-through delegate commands

  • uninstall that removes the install path and prints a runtime-removal hint

The package set, runtime name, delegate, documentation URL, and release channel belong to the project using conda-ship.