Runtime Conditions commands for extension bindings and workload profiling.
From this repository's root, build the executable with the schema-aware helper:
go run ./scripts/build.go --output ./rc
./rc --version
./rc profile generate --dir /path/to/go/workload --out profile.yamlThe helper downloads the pinned core profile schema, verifies its SHA-256, and embeds it alongside the linked Go profiler. Go profiling needs no runtime schema download or separate profiler installation. Analyzing a workload requires a working Go toolchain and its binding dependencies. CI builds with Go 1.26.5 and tests workload analysis with Go 1.25.0.
A plain go build or go install omits the schema linker value. Such a binary
can display help and version information, but profile generation fails with
rc: installed profiler has no verified core profile schema.
Rebuild it using the command above and run the resulting ./rc executable.
For a build using an already downloaded schema, supply the approved artifact:
go run ./scripts/build.go --output ./rc \
--core-schema /path/to/runtimeconditions.profile.schema.yamlThe local schema must match the helper's pinned checksum. Release builds also
pass --version <release-tag> and --commit <source-commit> to embed provenance.
rc profile uses the built-in Go profiler by default. The same commands are
available under rc profile go, with identical flags and behavior:
| Command | Purpose |
|---|---|
rc profile generate |
Generate a validated profile from Go binding declarations. |
rc profile validate-extensions |
Validate all imported generated binding packages. |
rc profile validate-extension |
Validate one imported binding package selected with --package. |
rc profile version |
Show the linked Go profiler version. |
A profile does not have to come from a profiler. To check one written by hand, or by an agent:
./rc profile validate profile.yamlIt is checked against the core profile schema embedded in rc and against the definitions of the
extensions it declares (downloaded from their ids, or read from --catalog directories).
For command help:
./rc profile --help
./rc profile go --help
./rc profile go generate --helpGenerate a profile using the default or explicit Go route:
./rc profile generate --dir /path/to/go/workload --out profile.yaml
./rc profile go generate \
--dir /path/to/go/workload \
--name my-workload \
--workload-uri https://example.com/my-workload \
--workload-version 1.0.0 \
--out profile.yaml--dir defaults to the current directory. Generation writes YAML to stdout
when --out is omitted. The default profile name is the workload directory's
basename; the default workload URI is its enclosing Go module path, falling
back to the directory path. The workload version defaults to dev.
Validate imported bindings or inspect the profiler version:
./rc profile go validate-extensions --dir /path/to/go/workload
./rc profile go validate-extension \
--dir /path/to/go/workload \
--package runtimeconditions.io/x/rc/common
./rc profile go versionProfiling analyzes declarations without executing the workload. Resolve the
workload's Go binding dependencies before running these commands. A failed
generation leaves an existing --out file unchanged.
Other languages run a separate add-on that rc finds on PATH. It can come from the
language's own tooling or from a system package, and rc does not care which. The
TypeScript profiler is on npm for developers who want it in their npm scripts:
npm install --global @runtimeconditions/typescript-profiler. The Java profiler is a jar that its
launcher, rc-profiler-java, runs; download it from the
releases of
runtimeconditions/java-rc-profiler and put the launcher on PATH. The Python profiler is on PyPI as
runtimeconditions-profiler; install it with pip into the workload's own virtual environment, because it finds
binding packages through that environment's metadata, and put the environment's bin directory on PATH. System packages for Homebrew,
apt, and yum, so that rc and its add-ons install the same way on a build server, are planned.
| Command | Purpose |
|---|---|
rc profile typescript <command> [flags] |
Run the installed TypeScript profiler. |
rc profile java <command> [flags] |
Run the installed Java profiler. |
rc profile python <command> [flags] |
Run the installed Python profiler. |
rc plugins list [--output yaml] |
Show the Go profiler and each add-on's status, version, and path. |
Everything after typescript, java, or python goes to the add-on unchanged, so it keeps its own flags
(for example --project instead of --dir, and --classpath for Java). rc looks for
rc-profiler-typescript, then runtimeconditions-typescript-profiler, or rc-profiler-java, or
runtimeconditions-python-profiler, on PATH; RC_TYPESCRIPT_PROFILER, RC_JAVA_PROFILER, or
RC_PYTHON_PROFILER can name an absolute path instead. It runs the add-on only
if --version --json lists the core profile schema rc targets (0.4.0). The add-on's output and exit
status pass through.
The Java launcher chooses the JDK, not rc: RC_JAVA_HOME, then JAVA_HOME, then the runtime bundled
in its system package, then java on PATH. It needs JDK 17 or newer and says so when none is found.
The Python profiler runs on the interpreter of the environment it is installed in (Python 3.11 or newer), and
sees the binding packages installed there. Install the profiler next to the bindings the workload imports, not
with pipx, which would give it an environment of its own.
./rc bindings --help
./rc bindings generate --helpThe command group provides resolve, normalize, generate, verify,
package, plan-release, check, and update. Cobra owns help, completion,
and flag parsing; execution uses the shared binding library from extensions.
Binding commands also require the shared YAML schemas. Installed layouts place
them under share/rc/extension-bindings/model/, alongside bin/rc. CI stages
these files from the exact extensions commit in
distribution/components.lock.yaml; they remain ordinary YAML files.
The local build helper builds the executable. For local binding development,
supply --tooling-dir pointing to matching schema resources, such as the
tooling/extension-bindings directory in a checkout of that pinned revision:
./rc bindings generate \
--packages /path/to/binding-project/packages.yaml \
--toolchain-lock /path/to/binding-project/toolchain.lock.yaml \
--tooling-dir /path/to/extensions/tooling/extension-bindings \
--core-schema /path/to/runtimeconditions.profile.schema.yaml \
--output /tmp/generated-bindingspackages.yaml selects extension roots, language targets, and native package
versions. toolchain.lock.yaml declares the applicable toolchain constraints.
Use repeatable --target package-key:language flags to limit the selected targets.
generate requires a new or empty output directory. verify --input accepts the
generated tree; use the same catalog and resource flags for these commands.
update verifies candidates before changing committed binding
directories; check compares regenerated content without updating those files.
The core schema must match the version declared in the package catalog. Without
--core-schema, normalization uses upstream core-schema resolution. Offline
generation also requires locally available extension definitions; native package
verification and profiling require resolved package dependencies and Go.
The normalizer and Go emitter run as linked libraries. Explicit executable
overrides for those tools conflict with this mode. For binding provenance,
--go-profiler /absolute/path/to/go-rc-profiler selects a standalone profiler
file; otherwise the linked profiler's actual module version and checksum are
recorded. The rc profile commands always use the linked Go profiler.
CI tests Linux and macOS on amd64 and arm64. It relocates the staged executable and YAML resources, exercises all eight binding operations, installs a freshly generated Go module through a local proxy, and profiles its declarations through both Go command routes. Negative checks cover altered committed source, nonempty output directories, and invalid declarations preserving existing profile output. Only Go is available on the smoke test's subprocess PATH; Python is used by the CI harness, and is not a runtime dependency of Go binding or profiling commands.
The small extension fixture is checked in as YAML under testdata/ci/bindings/.
Generated packages, archives, profiles, and module caches remain temporary CI
outputs. Homebrew/APT packaging and optional profiler add-ons remain planned.