Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quick start

After installing cjv, check the selected toolchain, set a default version, configure a project version, and manage updates.

Checking your installation

After completing the setup wizard, open a new terminal so your updated PATH is loaded, and check the active toolchain:

cjv show
cjc --version

cjv show displays your default host platform, all installed toolchains, and which toolchain is currently active. If your shell reports that cjc cannot be found, double-check that <CJV_HOME>/bin (by default ~/.cjv/bin) is on your PATH—see PATH configuration and verification for details.

Choosing a default toolchain

If you installed cjv with --default-toolchain none (or skipped SDK installation during setup), you can query the releases available on a channel and set a global default toolchain. Let’s take the lts channel as an example:

cjv toolchain list-remote --channel lts
cjv default lts
cjc --version

If the toolchain you pass to cjv default is not installed yet, cjv downloads and installs it automatically before saving it as the default. If lts does not publish an SDK for your platform yet, run cjv toolchain list-remote for sts or nightly and select that channel instead—or run cjv init again to let the interactive wizard pick an available channel for you.

The global default toolchain is used whenever you are in a directory that does not have a project toolchain file or a local directory override. To see which toolchain is active in your current directory and why it was chosen, run:

cjv show active

See Toolchains and versions for a full explanation of channels and version naming.

Choosing a version for a project

Using cangjie-sdk.toml

In a team repository, you usually want every contributor and CI runner to build with the exact same Cangjie release and extension libraries. You can declare these requirements in a cangjie-sdk.toml file at the root of your project:

[toolchain]
channel = "lts-1.0.5"
components = ["stdx"]

Replace lts-1.0.5 with a version that your project needs and your distribution source provides (or run cjv pin lts to generate the file with the resolved version automatically).

Whenever you run cjpm build or cjc inside that project directory, cjv automatically selects the toolchain declared in cangjie-sdk.toml. By default, auto_install is enabled, so cjv will download and install any missing SDK, component, or cross-compilation target on the fly. Running a proxy command will never unexpectedly upgrade an SDK that is already installed.

Setting a local directory override

If you want to test a project with a different toolchain on your own machine without modifying cangjie-sdk.toml, you can set a directory override:

cjv override set sts
cjv show active
cjv override unset

Directory overrides are stored in your personal ~/.cjv/settings.toml file rather than inside the project directory, while cangjie-sdk.toml is meant to be committed to version control. See Project toolchains for how overrides and project files interact.

Running a command with another version

Sometimes you just want to run a single command with a specific toolchain without changing your default or directory settings. Use cjv exec:

cjv exec +sts cjc --version

exec runs SDK tools or compiled programs with SDK and runtime library paths, installing missing requirements according to auto_install. cjv run sts cjc --version remains the explicit-toolchain compatibility form.

If you have compiled your own Cangjie binary and need to run it with the dynamic libraries from the SDK or stdx, use cjv exec:

cjv exec ./my_binary

See Running commands and setting the environment for more on run, exec, and envsetup.

Inspecting installed toolchains

Here are the most common commands for inspecting your local setup:

cjv show active
cjv which cjc
cjv toolchain list
  • cjv show active prints the currently selected toolchain and the rule that selected it (such as a cangjie-sdk.toml file, a directory override, or the global default).
  • cjv which cjc prints the full filesystem path to the cjc executable inside the active SDK.
  • cjv toolchain list lists hosts and cross SDKs with installation names, actual releases, and tracking/pinned/custom kinds. show installed remains a hidden compatibility command.

Keeping toolchains and cjv up to date

Updating tracked channels

When new versions of the Cangjie SDK are released, you can check for available updates or install them across all of your tracked channels (lts, sts, nightly):

cjv check
cjv update

cjv check queries the remote manifest and reports available updates for your installed SDKs and for cjv itself without installing anything. cjv update downloads and installs updates for all tracked channels, while leaving pinned versions (like lts-1.0.5) and custom toolchains untouched.

Whether a full cjv update also checks for or installs updates to cjv itself is controlled by the auto_self_update setting (check by default). You can also update cjv manually at any time by running:

cjv self update

Uninstalling a toolchain

To remove an installed toolchain that you no longer need and reclaim disk space:

cjv uninstall sts

Uninstalling a host toolchain also removes its attached components, cross-compilation targets, and offline documentation. For a complete list of commands and flags, see the Command reference.