This document provides a high-level introduction to the KCL (KCL Constraint Language) project, explaining its purpose as a constraint-based configuration language for cloud-native environments, its core architectural components, and how the repository is organized. This overview establishes the foundation for understanding the detailed documentation in subsequent sections.
For detailed information about KCL's language features and design principles, see Language Features and Design Principles. For practical use cases, see Use Cases and Applications. For development setup and contribution guidelines, see Getting Started.
KCL is an open-source, constraint-based record and functional language for writing complex configurations in cloud-native scenarios. The language provides advanced programming language technology with practical configuration management capabilities.
Primary Design Goals:
Sources: README.md21-23 README.md29-39 README.md43-56
The KCL system architecture comprises four major subsystems that collaborate to provide a complete configuration language platform. The architecture emphasizes clear separation between the core compilation system, infrastructure services, external interfaces, and development workflow.
Diagram: KCL Complete System Architecture
The architecture is organized into four layers. The KCL Core System contains the compiler (crates/ast, crates/parser, crates/sema, crates/evaluator), runtime (crates/runtime), and type system (crates/sema). The Compiler Infrastructure (compiler_base/session, compiler_base/error) provides session management, diagnostics, and error emission. The External API Layer exposes spec.proto RPC services (KclService, BuiltinService) consumed by multi-language SDKs. The Development Workflow orchestrates builds (Makefile, Cargo.toml, scripts/build.sh), testing, CI/CD (.github/workflows), and releases (scripts/release.sh). The runtime generates multiple output formats (JSON, YAML, native binaries .so/.dll/.dylib, WebAssembly wasm32-wasip1), and SDKs integrate with Kubernetes ecosystem tools.
Sources: README.md41-56 .gitignore60-86 .devcontainer/devcontainer.json5
The KCL repository follows a structured workspace layout that separates language implementation, compiler infrastructure, tooling, build system, and documentation. The organization facilitates clear separation of concerns and modular development.
Diagram: Repository Directory Structure
The repository root contains five primary directories. The crates/ workspace includes compiler crates (ast, parser, sema, evaluator, codegen), runtime infrastructure (runtime, loader, query), and developer tools (cli, driver, tools). The compiler_base/ directory provides foundational services (session, error, span). Root-level build configuration consists of Makefile (build orchestration), Cargo.toml (workspace definition), .gitignore (ignore patterns), .devcontainer/devcontainer.json (container specification), and .github/workflows/ (CI/CD). Documentation resides in docs/dev_guide/, and build scripts in scripts/ (build.sh, build.ps1, release.sh).
| Directory | Purpose | Key Files |
|---|---|---|
crates/ | Cargo workspace members | 11+ crates including ast, parser, sema, evaluator, runtime |
compiler_base/ | Compiler infrastructure | session/, error/, span/ subdirectories |
docs/ | Documentation | dev_guide/1.about_this_guide.md |
scripts/ | Build automation | build.sh, build.ps1, release.sh |
.github/workflows/ | CI/CD definitions | Multiple workflow YAML files |
.devcontainer/ | Development container | devcontainer.json |
The .gitignore file specifies ignored artifacts including:
/build/, /target, /_output, /dist/*.o, *.a, *.so, *.dylib, *.dll__pycache__, __kclcache__/, .pytest_cache.DS_Store (macOS), .vs/ (Visual Studio).coverage, coverage.xml*.tar.gz, /kcl-*.zipSources: .gitignore1-87 docs/dev_guide/1.about_this_guide.md1-21 .devcontainer/devcontainer.json1-14
The KCL system consists of several interconnected subsystems, each with specific responsibilities:
| Component | Location | Purpose | Key Types/Modules |
|---|---|---|---|
| Compiler Infrastructure | compiler_base/session/, compiler_base/error/, compiler_base/span/ | Compilation state management, diagnostics, source tracking | Session, DiagnosticHandler, SourceMap, Span, BytePos |
| AST & Parsing | crates/ast/, crates/parser/ | Token generation, AST construction, syntax tree representation | Module, Stmt, Expr, Lexer, Parser |
| Semantic Analysis | crates/sema/, crates/loader/, crates/query/ | Type checking, name resolution, dependency loading | Type system, symbol resolution, package loader |
| Evaluation & Codegen | crates/evaluator/, crates/codegen/ | Configuration evaluation, native/WASM code generation | Evaluator engine, code generation backends |
| Runtime | crates/runtime/ | Runtime library for executing compiled KCL | Runtime support functions |
| Language Server | crates/tools/src/LSP/ | LSP protocol implementation for IDE integration | LanguageServerState, main_loop, Event handlers |
| CLI Tools | crates/cli/, crates/cmd/ | Command-line interface implementation | Format, lint, test, vet, doc commands |
| Driver | crates/driver/ | High-level compilation orchestration | Compilation workflow coordination |
| Build System | ./Makefile, Cargo.toml | Multi-platform build orchestration, workspace management | make build, make test, cargo build |
| RPC API | spec.proto | gRPC service definitions | KclService, BuiltinService, 30+ operations |
| Multi-language SDKs | External repos | Programmatic API access across languages | Rust, Go, Python, .NET, Java, Node.js bindings |
| K8s Integration | External repos | Kubernetes tooling plugins | kubectl-kcl, kustomize-kcl, helm-kcl, KPT, Crossplane |
Sources: README.md41-56 docs/dev_guide/1.about_this_guide.md9
KCL processes configuration files through a multi-stage compilation pipeline that transforms source code into validated configuration data or executable code. The pipeline integrates compiler infrastructure services for session management, source tracking, and diagnostic reporting.
Diagram: KCL Compilation Pipeline
The compilation flow begins with .k source files processed by crates/parser (Lexer, Parser) to produce crates/ast structures (Module, Stmt, Expr). The AST flows through crates/loader (package loading), crates/sema (semantic analysis and type checking), and schema validation (rules and constraints). The validated AST is processed by crates/evaluator (Evaluator), crates/runner (Runner), and crates/codegen (Code Generator) to produce three output types: native code (.so/.dll/.dylib), WASM modules (wasm32-wasip1), and configuration files (JSON/YAML). Throughout the pipeline, compiler infrastructure services provide support: compiler_base/session (Session, SourceMap), compiler_base/error (DiagnosticHandler, Emitter), and compiler_base/span (Span, BytePos/CharPos tracking).
| Stage | Crate | Key Components | Output |
|---|---|---|---|
| Lexical Analysis | crates/parser | Lexer | Token stream |
| Syntax Analysis | crates/parser | Parser | AST (Module, Stmt, Expr) |
| Package Loading | crates/loader | Package Loader | Dependency-resolved AST |
| Semantic Analysis | crates/sema | Type Checker, Semantic Analyzer | Type-checked AST |
| Validation | crates/sema | Schema Validator, Rules | Validated AST |
| Evaluation | crates/evaluator | Evaluator | Evaluated configuration |
| Code Generation | crates/codegen | Code Generator | Native code, WASM, JSON/YAML |
The compilation pipeline integrates with infrastructure services at every stage:
compiler_base/session provides Session struct and SourceMap for compilation contextcompiler_base/span provides Span, BytePos, CharPos for precise source location trackingcompiler_base/error provides DiagnosticHandler for error collection and Emitter for formatted outputSources: README.md44-50 .gitignore60-86
KCL supports cross-platform development and deployment through a comprehensive build and release system that targets multiple operating systems, architectures, and runtime environments.
The build system uses Makefile as the primary orchestration layer, coordinating Cargo workspace compilation and platform-specific scripts:
| Component | Location | Purpose |
|---|---|---|
| Makefile | Root directory | Build orchestration with targets: build, build-wasm, build-lsp, build-cli, test, test-grammar, test-runtime, fmt, check |
| Cargo.toml | Root directory | Workspace definition managing 11+ member crates and dependencies |
| scripts/build.sh | scripts/ | Unix/Linux build automation script |
| scripts/build.ps1 | scripts/ | Windows PowerShell build script |
| scripts/release.sh | scripts/ | Release packaging: kcl-<version>-<os>-<arch>.tar.gz format |
| Platform Category | Architectures | Build Artifacts | CI Coverage |
|---|---|---|---|
| macOS | x86_64, ARM64 (Apple Silicon) | Native binaries, .dylib | .github/workflows/ macOS matrix |
| Linux | x86_64, ARM64 | Native binaries, .so | .github/workflows/ Ubuntu, CentOS, Alpine |
| Windows | x86_64 (AMD64) | Native binaries, .dll | .github/workflows/ MinGW, Native |
| WebAssembly | wasm32-wasip1 | .wasm modules | .github/workflows/ WASM jobs |
The repository provides containerized development environments for consistent tooling:
Container Configuration (.devcontainer/devcontainer.json:1-14):
docker.io/kcllang/kcl-builder:latestrust-lang.rust-analyzer, ms-vscode.makefile-toolsRequirements:
Build artifacts follow specific patterns defined in .gitignore:1-87:
| Artifact Type | Pattern | Purpose |
|---|---|---|
| Build directories | /build/, /target, /_output | Cargo and make output |
| Compiled libraries | *.so, *.dylib, *.dll, *.o, *.a | Native code outputs |
| Archives | *.tar.gz, /kcl-*.zip | Release packages |
| Cache files | __pycache__, __kclcache__/, lark_parser.pickle | Runtime caches |
| Coverage reports | .coverage, coverage.xml, /cover | Test coverage data |
The .github/workflows/ directory contains GitHub Actions workflows that implement the complete development lifecycle:
Sources: .devcontainer/devcontainer.json1-14 README.md74-76 .gitignore1-87
KCL provides a comprehensive set of capabilities that address various configuration management challenges:
crates/semaSchema constructs for reusable configuration templatesRule constructs for policy enforcementLambda expressions for configuration transformationcrates/cli binary with format, lint, test, vet, doc subcommandscrates/tools/src/LSP/ provides LanguageServerState with autocomplete, diagnostics, go-to-definitionspec.proto (KclService, BuiltinService) with SDKs: Rust, Go, Python, .NET, Java, Node.jscrates/evaluator, crates/runtimewasm32-wasip1 target via make build-wasmSources: README.md42-56
To begin working with KCL:
Quick Access Points:
Sources: README.md62-84 docs/dev_guide/1.about_this_guide.md16-20
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.
