Compile-time evaluation

Purpose

Compile-time evaluation (comptime) is the cornerstone language feature. Functions, types, and values can all be evaluated by the compiler. The implementation spans the frontend (which marks ZIR with comptime-only opcodes), the analyzer (Sema, which actually runs them), and the value/intern-pool model (which represents the results).

Where it lives

File	Role
lib/std/zig/AstGen.zig	Lowers comptime blocks, calls, and parameters into ZIR.
lib/std/zig/Zir.zig	ZIR encoding; carries comptime-only opcodes.
src/Sema.zig	The fixed-point evaluator. Runs at type-check time.
src/Sema/arith.zig	Comptime-correct arithmetic (saturating/wrapping/overflow checks).
src/Sema/bitcast.zig	@bitCast and union punning at comptime.
src/Sema/comptime_ptr_access.zig	Reading and writing through comptime pointers, including aggregates.
src/Sema/LowerZon.zig	Loads .zon files as comptime values.
src/Type.zig	The type model that comptime returns.
src/Value.zig	The value model.
src/mutable_value.zig	Mutable comptime values (var at comptime).
src/InternPool.zig	Identity for types and values across the compilation.

How it runs

1. AstGen produces ZIR. ZIR opcodes carry a "must be comptime" flag where appropriate (@TypeOf, @typeInfo, type expressions, etc.). Other opcodes can be comptime-evaluated when their operands are.
2. Sema walks ZIR. Whenever an instruction has all-comptime operands, it computes the result eagerly and stores it as a Value in the InternPool, then continues.
3. Aggregate values (structs, arrays, slices into comptime memory) are represented in the InternPool too. Comptime pointer arithmetic is handled by Sema/comptime_ptr_access.zig.
4. Type construction (@Type({ .Struct = .{...} }), generic functions) builds a new entry in InternPool with the proper layout.
5. AIR is only emitted for non-comptime work. Pure-comptime decls produce no runtime code at all.

Generic functions

Generic functions are comptime-parameterized functions. Sema instantiates them by:

1. Evaluating the comptime-only parameters against the call site.
2. Constructing a specialized type/decl in the InternPool.
3. Re-running analysis on the body with the specialization.

The InternPool's identity guarantees that two calls with the same comptime arguments share a single specialized instance.

comptime memory model

var declarations in comptime blocks are real, mutable storage held by the compiler. Sema/comptime_ptr_access.zig implements the rules for taking pointers, slicing, and writing through them while preserving type safety. This is the same code path that supports compile-time generated lookup tables and the type-construction utilities in lib/std/meta.zig.

Tests

• test/behavior/comptime.zig, test/behavior/comptime_* — language-level coverage.
• test/cases/compile_errors/ — a large fraction is comptime diagnostics.
• test/cases/safety/ — runtime-safety counterparts (overflow, integer cast, etc.).

Entry points for modification

• New comptime arithmetic edge case: src/Sema/arith.zig.
• New @builtin: lib/std/zig/BuiltinFn.zig + lib/std/zig/AstGen.zig + src/Sema.zig.
• New comptime memory operation: src/Sema/comptime_ptr_access.zig.
• Better comptime diagnostics: the relevant site in src/Sema.zig, plus a fixture under test/cases/compile_errors/.

See Compiler and Frontend for the components this feature glues together.