Documentation
¶
Overview ¶
Package kclrender is the single seam through which forge evaluates KCL. It renders via the embedded kpm package manager + kcl-go runtime — no external `kcl` binary required on PATH — and registers forge's KCL plugin namespace (kcl_plugin.forge.*) so KCL can pull host-runtime values (e.g. resolve_port) during evaluation.
kpm reads the package's kcl.mod and resolves dependencies — git, local path, and OCI/registry — exactly like the `kcl` CLI, so projects declare the forge module (and any extra packages) in kcl.mod in whatever style they like; forge neither parses nor special-cases deps. The two packages forge supplies itself — `forge` (internal/kclvendor) and any other forge project the kcl.mod imports under [forge_projects] (internal/kclprojects) — are external packages kpm never sees.
Index ¶
- func Release(ctx context.Context) string
- func ReleaseDArgs(ctx context.Context) []string
- func Run(workDir, source string, dArgs []string) ([]byte, error)
- func RunInWorkDir(workDir, source string, dArgs []string) ([]byte, error)
- func SnapshotDArgs(s release.Snapshot, cluster string) ([]string, error)
- func WithRelease(ctx context.Context, version string) context.Context
- func WithSnapshot(ctx context.Context, s release.Snapshot) (context.Context, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Release ¶ added in v0.1.45
Release is the release version WithRelease bound to ctx, or "" when the render is unbound. The same value the KCL sees as option("release_version"), for the Go-side consumers that never pass through a render — a frontend build's env, notably.
func ReleaseDArgs ¶ added in v0.1.45
ReleaseDArgs is the `-D release_version=<quoted>` binding for ctx's release, or nil. Quoted so an all-digit version stays a str (see image_tag).
func Run ¶
Run renders the KCL at source — a package directory or a single .k file — and returns the raw JSON result.
Both paths mean what any Go path means: relative to the process cwd. A caller holding a relative project dir builds source as filepath.Join(projectDir, ...), and that is correct here (see absPaths).
workDir is the process cwd KCL resolves relative reads against, and the project root whose managed kcl.mod files are checked for a legacy `forge` dependency (forgeModuleArg), so it is part of the contract. The `forge` module itself is supplied from this binary as an external package. dArgs are `-D key=value` top-level option assignments (e.g. "env=dev"). `kubeconfig` is appended here for every render — see withKubeconfigDArg — as are the active dev-stack git facts, see withDevStackDArgs. kpm progress/diagnostics go to stderr.
func RunInWorkDir ¶ added in v0.1.45
RunInWorkDir is Run with one addition: the process enters workDir for the duration of the evaluation, so the KCL runtime's own `file.read` resolves a relative path against it.
Why this is not just what Run does ¶
kpm's client.WithWorkDir decides where kpm resolves the PACKAGE from. It does NOT reach `file.read`, which the KCL runtime resolves against the real process cwd — so a project whose KCL reads a file by project-relative path (control-plane's deploy/kcl/lib/barman_plugin.k does `file.read("deploy/cnpg/plugin-barman-cloud.yaml")`) renders correctly only when forge was invoked from the project root, and fails with "No such file or directory" naming a path that plainly exists from anywhere else.
Why it is OPT-IN rather than the default ¶
Because os.Chdir is process-global, and this package is a library. The chdir sits inside the KCL evaluation lock, so no two evaluations can race each other — but nothing stops UNRELATED code in the same process from resolving its own relative path while an evaluation holds that lock. That is not hypothetical: making it unconditional turned internal/templates.TestBornContractTestSurvivesDepValidation intermittently red, because it computes the forge module root as filepath.Abs(filepath.Join("..", "..")) in a t.Parallel() subtest and resolved it against a render's workDir instead. A flaky suite is a worse defect than the one being fixed, and forge's own root.go names this hazard as the reason `--project-dir` exists at all.
So a CLI command — one process, one evaluation, no concurrent readers — opts in, and the shared render paths stay byte-identical. `forge env render` therefore still has the `-C` defect described above; fixing it needs kcl-go to accept a read-root for `file.read`, which is an upstream change, or every render path to become chdir-safe.
func SnapshotDArgs ¶ added in v0.1.46
SnapshotDArgs binds exact per-workload/named-slot references. KCL's immutable switch makes a missing slot an error rather than a repository/tag fallback. Callers render each cluster separately if duplicate workload names exist.
func WithRelease ¶ added in v0.1.45
WithRelease says which release version this render is for. It surfaces in KCL as option("release_version") and from there as `service.version` in each workload's OTEL_RESOURCE_ATTRIBUTES. Empty leaves the render unbound, which omits the attribute: forge reports a version only when it knows one.
func WithSnapshot ¶ added in v0.1.46
WithSnapshot validates and freezes the complete render pin context. Duplicate workload names across destinations with differing pins refuse because today's KCL binding is workload-relative; render those destinations separately instead.
Types ¶
This section is empty.
Source Files