Overview

Relevant source files

• .devcontainer/devcontainer.json
• README-zh.md
• README.md
• docs/dev_guide/1.about_this_guide.md
• kclvm/Cargo.lock
• kclvm/Cargo.toml
• kclvm/api/Cargo.toml
• kclvm/ast_pretty/Cargo.toml
• kclvm/cmd/Cargo.toml
• kclvm/config/Cargo.toml
• kclvm/driver/Cargo.toml
• kclvm/error/Cargo.toml
• kclvm/parser/Cargo.toml
• kclvm/query/Cargo.toml
• kclvm/runner/Cargo.toml
• kclvm/runner/build.rs
• kclvm/runtime/Cargo.toml
• kclvm/sema/Cargo.toml
• kclvm/tools/Cargo.toml
• kclvm/tools/src/LSP/Cargo.toml
• kclvm/utils/Cargo.toml
• samples/fib.k
• samples/kubernetes.k

Purpose and Scope

This document provides a high-level overview of the KCL (Kubernetes Configuration Language) compiler system, its architecture, and core capabilities. KCL is a constraint-based record and functional programming language designed for writing and managing complex configurations, particularly in cloud-native environments.

This overview introduces the major system components, execution flow, and workspace organization. For detailed information about specific subsystems, refer to:

• Language frontend (parsing and semantic analysis): See Language Frontend
• Code generation and execution: See Code Generation and Execution
• Developer tools (LSP, CLI, testing): See Developer Tools
• External APIs and integration: See API and Integration

Sources: README.md22-24 README.md42-57

What is KCL?

KCL is an open-source, constraint-based configuration language implemented primarily in Rust. It combines features from high-level languages like Python and Golang with functional programming principles to provide a type-safe, declarative approach to configuration management.

Key Characteristics:

Aspect	Description
Language Paradigm	Constraint-based record and functional language
Primary Use Case	Cloud-native configuration, especially Kubernetes
Type System	Static typing with inference, constraints, and validation rules
Execution Models	AST interpretation (FastRunner) and LLVM native compilation
Implementation	Rust with C/LLVM for high-performance runtime
Output Formats	JSON, YAML, or programmatic API results

Sources: README.md24 README.md44-51

System Architecture

The KCL system follows a layered architecture with clear separation between external interfaces, service orchestration, compilation pipeline, and execution backends.

High-Level Component Organization

Sources: kclvm/Cargo.toml38-63 Diagram 1 from high-level architecture

Core Components

Workspace Structure

The KCL compiler is organized as a Rust Cargo workspace with 20+ specialized crates. The workspace root is defined in kclvm/Cargo.toml38-63

Primary Crates:

Crate	Purpose	Location
kclvm-api	Service API implementation and protobuf interfaces	kclvm/api
kclvm-cmd	Command-line interface entry points	kclvm/cmd
kclvm-parser	Lexer and parser producing AST	kclvm/parser
kclvm-ast	Abstract Syntax Tree definitions	kclvm/ast
kclvm-sema	Semantic analysis, type checking, symbol resolution	kclvm/sema
kclvm-compiler	LLVM code generation	kclvm/compiler
kclvm-runner	Execution orchestration	kclvm/runner
kclvm-evaluator	AST interpretation engine	kclvm/evaluator
kclvm-runtime	Runtime library and built-in functions	kclvm/runtime
kclvm-driver	Workspace discovery and build coordination	kclvm/driver
kclvm-error	Error reporting and diagnostics	kclvm/error
kclvm-tools	Formatting, linting, testing, documentation	kclvm/tools
kcl-language-server	LSP implementation for IDE support	kclvm/tools/src/LSP

Sources: kclvm/Cargo.toml1-72 kclvm/api/Cargo.toml kclvm/parser/Cargo.toml kclvm/sema/Cargo.toml kclvm/runner/Cargo.toml kclvm/tools/src/LSP/Cargo.toml

Compilation Pipeline Flow

Sources: Diagram 2 from high-level architecture, kclvm/driver kclvm/parser kclvm/sema kclvm/runner

Execution Models

KCL supports two execution backends, selectable via feature flags in kclvm/Cargo.toml65-71:

1. FastRunner (Default)

• Module: kclvm-evaluator
• Mechanism: Direct AST interpretation
• Use Case: Development, debugging, environments without LLVM
• Performance: Faster compilation, slower runtime

2. LLVM Backend (Optional)

• Module: kclvm-compiler
• Mechanism: Compiles KCL to LLVM IR, then to native code
• Use Case: Production deployments requiring maximum runtime performance
• Performance: Slower compilation, faster runtime
• Activation: Build with --features llvm

Both backends share the same kclvm-runtime library for built-in functions and FFI support.

Sources: kclvm/Cargo.toml65-71 kclvm/runner/Cargo.toml50-51 kclvm/api/Cargo.toml50-51 Diagram 1 from high-level architecture

Integration Points

API Layers

Key Integration Components:

1. C API (FFI Boundary): Defined in kclvm/Cargo.toml8-11 as cdylib and staticlib outputs named kclvm_cli_cdylib
2. Service API: KclvmServiceImpl in kclvm-api provides unified interface for all operations
3. Multi-language SDKs: Wrap C API for language-specific ergonomics
4. Cloud-native Plugins: Integrate KCL into Kubernetes tooling ecosystem

Sources: kclvm/Cargo.toml8-11 kclvm/api/Cargo.toml README.md55-56 Diagram 4 from high-level architecture

Developer Experience

Language Server Protocol (LSP)

The kcl-language-server crate (kclvm/tools/src/LSP) provides IDE features:

• Code completion via semantic analysis
• Goto definition using symbol resolution
• Hover information from type system
• Find references through def-ref tracking
• Diagnostics from error subsystem

Sources: kclvm/tools/src/LSP/Cargo.toml README.md53 Diagram 3 from high-level architecture

Command-Line Tools

The kclvm-tools crate provides:

• Formatting: Code style enforcement
• Linting: Style checking
• Testing: Unit test framework
• Validation: Configuration validation
• Documentation: Auto-generated docs

Sources: kclvm/tools/Cargo.toml README.md53 Diagram 7 from high-level architecture

Platform Support

Target Platforms

KCL supports multiple platforms through CI/CD workflows:

Platform	Architecture	Build Environment
macOS	AMD64, ARM64	Native
Windows	AMD64	MSVC, MinGW
Linux	AMD64, ARM64	Ubuntu native
Linux	AMD64	CentOS7 (Docker)
Linux	AMD64 (musl)	Alpine (Docker)
WebAssembly	WASM32	WASI target

The default target is configured at build time in kclvm/runner/build.rs6-10

Sources: kclvm/runner/build.rs1-12 Diagram 6 from high-level architecture, .devcontainer/devcontainer.json

Example Usage

Simple Configuration

A basic KCL program (samples/fib.k):

Kubernetes Configuration

A Kubernetes deployment (samples/kubernetes.k):

Sources: samples/fib.k1-15 samples/kubernetes.k1-19

System Dependencies

External Dependencies

Key external libraries and their purposes:

Category	Dependencies	Purpose
Parsing	rustc_lexer, petgraph	Lexical analysis, dependency graphs
Serialization	serde, serde_json, serde_yaml_ng	JSON/YAML output
Compilation	LLVM libraries (optional)	Native code generation
LSP	lsp-server, lsp-types	IDE integration
Error Reporting	compiler_base_error, annotate-snippets	Diagnostics
Concurrency	tokio, crossbeam, parking_lot	Async runtime, thread safety

Sources: kclvm/Cargo.lock1-300 kclvm/parser/Cargo.toml8-36 kclvm/tools/src/LSP/Cargo.toml35-43 kclvm/runtime/Cargo.toml6-37

Project Organization

The project follows standard Rust conventions:

• Source code: kclvm/ directory containing all crates
• Documentation: docs/ directory with development guides
• Examples: samples/ directory with example .k files
• Build artifacts: Generated during cargo build in target/
• Development environment: .devcontainer/ for GitHub Codespaces support

For contribution guidelines, see docs/dev_guide/1.about_this_guide.md

Sources: docs/dev_guide/1.about_this_guide.md1-21 .devcontainer/devcontainer.json1-14 README.md75-78

Next Steps

This overview has introduced the KCL system architecture and major components. For deeper dives into specific subsystems:

• Architecture details: See Architecture
• Compilation pipeline: See Compilation Pipeline
• Language frontend: See Language Frontend
• Execution backends: See Code Generation and Execution
• Developer tools: See Developer Tools
• API integration: See API and Integration

Sources: Table of contents provided in prompt