cjr User Guide

cjr finds the runtime that matches a Cangjie program and launches it.

cjr ./app

Cangjie programs usually depend on dynamic libraries shipped with their SDK. The runtime ABI varies across SDK versions. cjr reads the full SDK version from the binary and selects an official asset using cangjie-version-manifest. The runtime version must match exactly.

Prepared cjr runtimes are reused directly. When preparing a runtime, cjr first checks cjv archives and official managed installations, then its own archives. If none are available, it downloads the official SDK, verifies its checksum and extracts the runtime. Installing or configuring cjv is optional.

Scope

cjr supports command-line programs and dependencies correctly built with the same official SDK. The application distributor remains responsible for application libraries, stdx and system dependencies. Program metadata determines the runtime version automatically, using official releases exclusively.

Continue with installation, or use inspect and the platform guide to diagnose a launch failure.

Install and run

Download a prebuilt binary

Download the prebuilt archive for your system and architecture from GitHub Releases.

Each archive has a .sha256 checksum file in the release. Verify it with sha256sum -c <filename>.sha256 on Linux or shasum -a 256 -c <filename>.sha256 on macOS. On Windows, use Get-FileHash <archive-path> -Algorithm SHA256 and compare the result with the checksum file.

Extract the archive and add the directory containing cjr (cjr.exe on Windows) to PATH. On Linux / macOS, you can install it in your user command directory:

mkdir -p ~/.local/bin
install -m 755 cjr ~/.local/bin/cjr

Ensure ~/.local/bin is on PATH. On Windows, place cjr.exe in a permanent directory and add that directory to your user Path through Environment Variables. Open a new terminal and run:

cjr --version
# cjr 0.0.1

Windows binaries include the C/C++ runtime. The macOS binaries require macOS 13 or newer. The Linux binary is statically linked with musl; the Cangjie application and its runtime still have their own system requirements.

Install from source

Install Rust 1.89 or newer, a C compiler and CMake. Use the MSVC Rust toolchain on Windows.

cargo install --git https://github.com/Zxilly/cjr --tag v0.0.1 --locked

Ensure Cargo’s bin directory is on your PATH, then run:

cjr --version

To install from a local checkout:

git clone https://github.com/Zxilly/cjr.git
cd cjr
cargo install --path . --locked

Run a program

Linux / macOS:

cjr ./app --port 8080

Windows PowerShell:

cjr .\app.exe --port 8080

The first launch may download a full SDK archive. Only the runtime is extracted; later launches reuse it. cjr runs the original executable in place, preserves its contents and uses the current working directory, standard streams and application arguments.

Offline use

Run the program once while online, then use:

cjr --offline ./app

Offline mode uses local content exclusively. Existing runtime records, or local metadata with matching SDK content, must identify an official asset. Missing content produces an error.

Put --offline and -v before the executable path. Everything after that path belongs to the application.

Command reference

Run a program

cjr [--offline] [-v] <binary> [args...]

cjr ./app --help requests the application’s help. Use cjr --help for cjr itself. If an executable is named inspect, list or cache, specify a path such as ./inspect, or use cjr -- inspect.

cjr preserves the child’s exit status. Preparation and launch errors print a diagnostic and return a nonzero status.

Inspect a program

cjr inspect ./app
cjr inspect ./app --json

Show the binary format, architecture, SDK version, dynamic dependencies and local runtime candidates. Inspection is a read-only operation on local files.

List local content

cjr list
cjr list --json

List visible cjr and cjv assets with their source and usage state. The query covers local content.

Clean the cache

cjr cache clean --dry-run
cjr cache clean
cjr cache clean --all --dry-run
cjr cache clean --all

The default removes archives, metadata and abandoned staging content while retaining prepared runtimes. --all also removes runtimes known to be unused. --dry-run previews the operation. Cleanup only affects cjr-owned content.

JSON output

inspect --json and list --json include a schema_version field. Automation should check the exit status and schema version, accept additional fields and handle warnings and unknown states explicitly. Treat a match as successful only when the reported state confirms it.

Cache and cjv

Cache location

cjr uses .cjr in the user home directory by default. Set CJR_HOME to choose another directory:

CJR_HOME=/path/to/cjr-cache cjr ./app

$env:CJR_HOME = 'D:\Caches\cjr'
cjr .\app.exe

Use independent, non-overlapping paths for the cjr and cjv directories. Use a local filesystem directory writable by the current user.

Automatic cjv reuse

An existing prepared cjr runtime is used directly. When preparing a new one, cjr tries:

1. cjv archives matching the official checksum.
2. cjv managed SDK installations with matching official source records.
3. Archives stored by cjr.
4. The official download URL.

cjr uses compatible locks when reading a cjv installation and copies runtime files into its own storage. cjv-owned content stays intact.

An absolute CJV_HOME takes precedence. Otherwise, cjr reads the home setting from the cjv user configuration, then the system configuration, and finally falls back to .cjv in the user home. CJV_CONFIG_FILE and CJV_FALLBACK_SETTINGS can select those configuration files.

cjr uses official SDK caches and managed installations with compatible layouts and complete source records. It skips other content and proceeds to the next source automatically.

Content retained by cleanup

cjr registers runtime use before launching the application. cache clean --all skips runtimes that may still be used by the program or its descendants.

On macOS, confirming that every descendant has exited may require the same host to restart; usage records remain until confirmation. Forced termination of cjr and unreadable records can also delay cleanup.

Cleanup retains coordination locks and operates on files and links themselves within cjr storage. Use cjr cache clean to select reclaimable runtimes based on usage records.

Platforms and troubleshooting

Platforms

Availability also requires an official SDK asset for the exact version and architecture with a SHA-256 checksum. Linux supports x64. macOS supports native command-line programs and selects the matching architecture slice. Application distributors handle .app bundles and Rosetta translation.

Check SDK version metadata

Run cjr inspect <binary> first. ELF requires section headers. Mach-O supports both ordinary version pointers and chained fixups. Version detection requires an intact version table with a supported layout. Parsing failures produce a diagnostic. Ask the application distributor for a build that preserves version metadata.

Check official release records

The complete SDK version, platform and official checksum must match. Check that the manifest includes the target version and its checksum; cjr uses an exact version match. Offline use also requires local metadata or an existing runtime record.

Runtime present, launch still fails

Check application-local libraries and embedded search paths. Windows application-directory DLLs, old ELF RPATH entries, preload variables and explicit library paths can take precedence over the chosen runtime. cjr rejects detected conflicts. The application distributor should correct the conflicting files or paths.

Application distributors provide application libraries and stdx; the system package manager supplies glibc and other system dependencies. Use the system loader’s diagnostic to identify missing dependencies.

Restricted macOS programs

cjr rejects loading-environment injection for recognized hardened or restricted programs. Signatures, entitlements and SIP stay intact. Applications distributed this way should bundle and sign their own runtimes.

Non-ASCII arguments

cjr passes native operating-system arguments. Some Cangjie Windows SDKs may fail to decode Chinese arguments in main(args). If direct execution fails in the same way, the SDK or application needs to address it.

Static dependency checks read dependencies declared in the binary. The system loader or application reports errors from runtime plugins, delay loading and custom loaders.