PGO & CPU Variants

Advanced topic. This page describes profile-guided optimization (PGO) and CPU variants for Native builds. These are specialized options for people tuning a finished program; they are not needed to learn CK. Both are opt-in, and an ordinary ckc build does not use a workload profile.

Profile-guided executable build#

For a zero-argument main, ckc pgo build creates a temporary instrumented executable, runs it once, merges the completed profile shard, then builds the final O3 executable.

ckc pgo build app.ck --out app-pgo --profile-out app.ckprof
ckc pgo inspect app.ckprof

Use a representative workload. CK validates the compiler, source, KIR, target, mode, and profile identities before applying observations. A profile can guide profitability and layout; it cannot prove that a memory access or arithmetic rewrite is safe.

Library workflow#

Libraries collect completed profile shards into a directory. After workload execution is quiescent, the host calls the generated ck_profile_flush_* control symbol. Merge the shards, then build with --pgo-use.

ckc build kernel.ck --kind dynamic --pgo-generate profiles/ --out libkernel
ckc pgo merge profiles/ --out kernel.ckprof
ckc build kernel.ck --kind dynamic --pgo-use kernel.ckprof --out libkernel-pgo

The host must run the training library and call its generated flush symbol between the first and second commands.

CPU variants#

--cpu multiversion builds a portable baseline and verified, bounded enhanced variants for supported Native artifact kinds. A baseline-safe dispatcher selects a compatible variant at runtime while preserving the public ABI.

ckc build kernel.ck --kind static --cpu multiversion --out libkernel.a

Multiversioning requires O3 and is not available for a standalone object output. Profile use is available at O2 or O3; profile-guided specialization and multiversioning require O3. Offline Auto-Tuning is not currently available. See the CLI contract for the full compatibility matrix.