// Copyright (c) 2020-2024 Joe Conigliaro. All rights reserved.
// Use of this source code is governed by an MIT license
// that can be found in the LICENSE file.
module builder

import os
import v2.ast
import v2.abi
import v2.eval
import v2.gen.arm64
import v2.gen.c
import v2.gen.cleanc
import v2.gen.v as gen_v
import v2.gen.x64
import v2.insel
import v2.markused
import v2.parser
import v2.mir
import v2.pref
import v2.ssa
import v2.ssa.optimize as ssa_optimize
import v2.token
import v2.transformer
import v2.types
import time
import runtime

const staged_c_file = '/tmp/v2_codegen.tmp.c'
const staged_main_obj_file = '/tmp/v2_codegen.tmp.main.o'

struct Builder {
	pref &pref.Preferences
mut:
	files                                 []ast.File
	user_files                            []string // original user-provided files (for output name)
	file_set                              &token.FileSet     = token.FileSet.new()
	env                                   &types.Environment = unsafe { nil } // Type checker environment
	parsed_full_files_n                   int
	parsed_vh_files_n                     int
	entry_v_lines_n                       int
	parsed_v_lines_n                      int
	parsed_full_files                     []string
	parsed_vh_files                       []string
	used_fn_keys                          map[string]bool
	cached_called_fn_names                map[string]bool
	v2compiler_generic_setup_snapshot     cleanc.GenericSetupSnapshot
	has_v2compiler_generic_setup_snapshot bool
	used_vh_for_parse                     bool
	used_import_vh_for_parse              bool
	used_virtual_vh_for_parse             bool
	// flat is the canonical parse output. parse_batch streams directly into
	// flat_builder so b.flat is built incrementally during parsing rather than
	// via a redundant flatten_files() pass afterwards.
	flat         ast.FlatAst
	flat_builder ast.FlatBuilder
	// flat_builder_inited tracks whether flat_builder has been seeded with
	// pre-sized arenas. We can only size after we know the input set, so
	// the first parse_batch call lazily initializes it.
	flat_builder_inited bool
	// native_flat_pipeline_enabled means the transform phase produced a
	// post-transform FlatAst and intentionally did not materialize b.files.
	native_flat_pipeline_enabled bool
	// Source snapshot used only for an isolated macOS tiny candidate graph.
	// The normal hosted graph is still built separately and remains the fallback.
	macos_tiny_candidate_source_files []ast.File
	macos_tiny_candidate_source_flat  ast.FlatAst
}

pub fn new_builder(prefs &pref.Preferences) &Builder {
	unsafe {
		return &Builder{
			pref:                   prefs
			used_fn_keys:           map[string]bool{}
			cached_called_fn_names: map[string]bool{}
		}
	}
}

// exec_build_c_file returns the staging C file path for executable builds.
// A stable temp path avoids output-name-derived string construction in
// self-hosted arm64 binaries, where that path is currently unstable.
fn (b &Builder) exec_build_c_file(output_name string) string {
	if b.pref.keep_c {
		return output_name + '.c'
	}
	return staged_c_file
}

fn (b &Builder) should_use_native_flat_pipeline() bool {
	if os.getenv('V2_NATIVE_FLAT') == '' {
		return false
	}
	if os.getenv('V2_NO_NATIVE_FLAT') != '' {
		return false
	}
	return b.pref.backend == .arm64 && b.pref.hot_fn.len == 0
}

fn (b &Builder) backend_uses_markused_pruning() bool {
	return b.pref.backend != .arm64
}

// should_skip_markused_for_self_build avoids a self-host-only pruning pass that
// costs more than it saves once the v2 compiler object caches are hot.
fn (b &Builder) should_skip_markused_for_self_build() bool {
	return b.pref.backend == .cleanc && b.is_cmd_v2_self_build()
}

fn (b &Builder) should_build_ssa_from_flat() bool {
	return b.flat.files.len > 0
}

fn (b &Builder) should_keep_flat_for_codegen() bool {
	return match b.pref.backend {
		.cleanc, .c, .x64, .arm64 { true }
		else { false }
	}
}

fn (b &Builder) can_compile_cleanc_locally() bool {
	if b.pref == unsafe { nil } {
		return true
	}
	return b.pref.can_compile_cleanc_locally()
}

fn (b &Builder) cflags_target_os_for_local_compile() string {
	if b.pref == unsafe { nil } {
		return normalize_target_os_name(os.user_os())
	}
	if b.pref.is_cross_target() && b.can_compile_cleanc_locally() {
		return b.pref.source_filter_target_os()
	}
	return b.pref.target_os_or_host()
}

fn cleanc_c_output_name(output_name string) string {
	if output_name.ends_with('.c') {
		return output_name
	}
	return output_name + '.c'
}

fn (mut b Builder) compile_cleanc_executable(output_name string, cc string, cc_flags string, cc_link_flags string, error_limit_flag string, mut sw time.StopWatch) {
	cc_start := sw.elapsed()
	if b.pref.is_shared_lib {
		// Shared library: compile with -shared -fPIC -undefined dynamic_lookup
		// Use -fvisibility=hidden so only explicitly exported (impl_live_*) symbols
		// are visible. All other functions become hidden, causing the dylib to
		// resolve them from the host executable at load time.
		mut cc_cmd := '${cc} ${cc_flags} -shared -fPIC -fvisibility=hidden -undefined dynamic_lookup -w -Wno-incompatible-function-pointer-types "${staged_c_file}"'
		if cc_link_flags.len > 0 {
			cc_cmd += ' -x none ${cc_link_flags}'
		}
		cc_cmd += ' -o "${output_name}"${error_limit_flag}'
		run_cc_cmd_or_exit(cc_cmd, 'shared lib compilation', b.pref.show_cc)
		print_time('CC (shared)', time.Duration(sw.elapsed() - cc_start))
		println('[*] Compiled shared library ${output_name}')
		return
	}
	// Non-cached path: compile and link in one step.
	// Place link flags (which may include .o files) AFTER the source file.
	// Use `-x none` to reset the language before .o files, since -x objective-c
	// would cause cc to treat .o files as source code.
	mut cc_cmd := '${cc} ${cc_flags} -w -Wno-incompatible-function-pointer-types "${staged_c_file}"'
	if cc_link_flags.len > 0 {
		cc_cmd += ' -x none ${cc_link_flags}'
	}
	cc_cmd += ' -o "${output_name}"${error_limit_flag}'
	run_cc_cmd_or_exit(cc_cmd, 'C compilation', b.pref.show_cc)
	print_time('CC', time.Duration(sw.elapsed() - cc_start))

	println('[*] Compiled ${output_name}')
}

// print_rss prints process RSS in MB at the given phase boundary.
// Gated on V2_MEM=1.
//
// CAVEAT: v2 is force-built with `-gc none` (see is_v2_compiler_target in
// vlib/v/pref/default.v), so allocations are never reclaimed. RSS is
// dominated by the OS's decision of which pages to keep resident, not by
// what the program is actually using. Run-to-run variance is huge
// (observed 500 MB to 4.8 GB on identical runs). Treat these numbers as
// a coarse signal, not a precision metric.
//
// For reliable peak-memory comparisons between optimizations, use
// `/usr/bin/time -l <cmd>` and read `peak memory footprint` — that
// metric is stable to within ~0.1% across runs.
fn print_rss(stage string) {
	if os.getenv('V2_MEM') == '' {
		return
	}
	rss := runtime.used_memory() or { 0 }
	$if macos {
		// Under -gc none nothing is freed, so `live` is monotonic and its
		// per-phase delta is the exact bytes that phase allocated. `peak` is
		// the high-water mark. Both are stable run-to-run, unlike `rss`.
		live, peak := darwin_live_malloc_bytes()
		mb := u64(1024 * 1024)
		eprintln('  [mem] ${stage}: live ${live / mb} MB  peak ${peak / mb} MB  (rss ${rss / mb} MB)')
		return
	}
	eprintln('  [mem] ${stage}: ${rss / (1024 * 1024)} MB')
}

pub fn (mut b Builder) build(files []string) {
	b.user_files = files
	// Pre-parse fast path: for cmd/v2 self-host, if the cached bundle objects + main.o are
	// present (restored from the durable tier if /tmp was wiped) and all sources are fresh,
	// relink directly and skip the entire front-end. Falls through on any staleness.
	if b.try_self_build_fast_relink() {
		return
	}
	mut sw := time.new_stopwatch()
	print_rss('start')
	$if parallel ? {
		if b.pref.no_parallel {
			b.parse_files(files)
		} else {
			b.parse_files_parallel(files)
		}
	} $else {
		b.parse_files(files)
	}
	b.files = []ast.File{}
	parse_time := sw.elapsed()
	print_time('Scan & Parse', parse_time)
	print_rss('after parse')
	// FlatBuilder is the canonical parse output; both parse paths stream into
	// it. parse_files / parse_files_parallel return [] in flat mode, so b.flat
	// is the live source of truth from here on. The rehydration to legacy
	// []ast.File is deferred until a compatibility consumer actually needs it.
	b.flat = b.flat_builder.flat
	b.update_parse_summary_counts()
	print_parse_summary(b.parsed_full_files_n, b.parsed_vh_files_n, b.entry_v_lines_n,
		b.parsed_v_lines_n, b.pref.stats, b.pref.print_parsed_files, b.parsed_full_files,
		b.parsed_vh_files)
	if b.pref.stats {
		b.print_flat_ast_summary()
	}

	if b.pref.backend == .cleanc && !b.validate_freestanding_cleanc_contract() {
		exit(1)
	}

	if b.pref.skip_type_check {
		b.env = types.Environment.new()
	} else {
		b.env = if b.pref.no_parallel {
			b.type_check_files()
		} else {
			b.type_check_files_parallel()
		}
	}
	type_check_time := time.Duration(sw.elapsed() - parse_time)
	print_time('Type Check', type_check_time)
	print_rss('after type check')

	b.prepare_macos_tiny_candidate_source_files()

	// Transform AST (flag enum desugaring, etc.)
	transform_start := sw.elapsed()
	mut trans := transformer.Transformer.new_with_pref(b.env, b.pref)
	trans.set_file_set(b.file_set)
	sequential_transform := b.pref.no_parallel_transform || b.pref.ownership
	use_native_flat_pipeline := b.should_use_native_flat_pipeline()
	b.native_flat_pipeline_enabled = use_native_flat_pipeline
	// The transform is flat-only for every backend: both the sequential and
	// the parallel path emit cursor-native into a FlatBuilder and never
	// materialize a transformed []ast.File. The legacy backends that still
	// consume []ast.File (.v/eval) rehydrate once from the transformed flat
	// at the codegen boundary below instead of dragging a compatibility
	// path through the transform.
	if sequential_transform {
		b.flat = trans.transform_flat_to_flat_direct(&b.flat, b.files)
	} else {
		b.flat = b.transform_files_parallel_flat_direct(mut trans)
	}
	b.files = []ast.File{}
	transform_time := time.Duration(sw.elapsed() - transform_start)
	print_time('Transform', transform_time)
	print_rss('after transform')

	// Mark used functions/methods for backend pruning.
	if b.pref.no_markused || !b.backend_uses_markused_pruning()
		|| b.should_skip_markused_for_self_build() {
		b.used_fn_keys = map[string]bool{}
	} else {
		mark_used_start := sw.elapsed()
		// Flat markused consumes the post-transform FlatAst. Both sequential
		// and parallel paths populate b.flat as part of their *_to_flat wedge,
		// so the separate flatten_files() pass is gone.
		if b.uses_minimal_x64_runtime_roots() {
			opts := markused.MarkUsedOptions{
				minimal_runtime_roots: true
			}
			b.used_fn_keys = markused.mark_used_flat_with_options(&b.flat, b.env, opts)
		} else {
			b.used_fn_keys = markused.mark_used_flat(&b.flat, b.env)
		}
		mark_used_time := time.Duration(sw.elapsed() - mark_used_start)
		print_time('Mark Used', mark_used_time)
		print_rss('after markused')
	}
	if !b.should_keep_flat_for_codegen() {
		// .v/eval still consume legacy []ast.File: rehydrate once from the
		// transformed flat at the backend boundary, then drop the flat.
		if (b.pref.backend == .v && !b.pref.skip_genv) || b.pref.backend == .eval {
			b.files = b.flat.to_files()
		}
		b.flat = ast.FlatAst{}
	}

	// Generate output based on backend
	match b.pref.backend {
		.v {
			if !b.pref.skip_genv {
				b.gen_v_files()
			}
		}
		.cleanc {
			b.gen_cleanc()
		}
		.c {
			b.gen_ssa_c()
		}
		.x64 {
			b.gen_native(.x64)
		}
		.arm64 {
			b.gen_native(.arm64)
		}
		.eval {
			mut runner := eval.new(b.pref)
			runner.run_files(b.files) or {
				eprintln('error: ${err.msg()}')
				exit(1)
			}
		}
	}

	print_time('Total', sw.elapsed())
	print_rss('after codegen (peak)')
}

fn (mut b Builder) gen_v_files() {
	mut gen := gen_v.new_gen(b.pref)
	for file in b.files {
		gen.gen(file)
		if b.pref.debug {
			gen.print_output()
		}
	}
}

fn (mut b Builder) gen_cleanc() {
	// Clean C Backend (AST -> C)
	mut sw := time.new_stopwatch()

	// The cached-core split is currently unstable in some module builds
	// (including cmd/v2 self-host and directory-style user module builds).
	// Force single-unit cleanc generation there.
	force_no_cache := b.should_disable_cleanc_cache()
	use_cache := !b.pref.no_cache && !force_no_cache
	if os.getenv('V2_TRACE_CACHE') != '' {
		eprintln('TRACE_CACHE use_cache=${use_cache} no_cache=${b.pref.no_cache} force_no_cache=${force_no_cache} self_build=${b.is_cmd_v2_self_build()} files=${b.user_files}')
	}

	// Determine output name
	output_name := if b.pref.output_file != '' {
		b.pref.output_file
	} else if b.user_files.len > 0 {
		b.default_output_name()
	} else {
		'out'
	}

	generation_only := output_name.ends_with('.c') || !b.can_compile_cleanc_locally()
	if generation_only {
		c_output_name := cleanc_c_output_name(output_name)
		c_source := b.gen_cleanc_source([]string{})
		print_time('C Gen', sw.elapsed())
		if c_source == '' {
			eprintln('error: cleanc backend is not fully functional (compiled with stubbed functions)')
			eprintln('hint: use v2 compiled with v1 for proper C code generation')
			return
		}
		os.write_file(c_output_name, c_source) or { panic(err) }
		if output_name.ends_with('.c') {
			println('[*] Wrote ${c_output_name}')
		} else {
			println('[*] Wrote ${c_output_name} (local C compilation disabled for this target)')
		}
		return
	}

	mut cc := if b.pref.ccompiler.len > 0 {
		b.pref.ccompiler
	} else {
		configured_cc(b.pref.vroot)
	}
	// -prod requires a real optimizing compiler — TCC cannot handle -O3/-flto.
	// Switch to system cc (gcc/clang) when the default compiler is TCC.
	if b.pref.is_prod && cc.contains('tcc') {
		cc = 'cc'
	}
	directive_flags := b.collect_cflags_from_sources()
	$if macos {
		if cc.contains('tcc') && cflags_need_objc_mode(directive_flags) {
			cc = 'cc'
		}
	}
	// Separate directive flags into compile-only and link-only flags.
	// -framework, -l, -L, .o/.a/.so/.dylib are linker flags and must NOT
	// be passed during -c compilation (they can trigger unwanted header
	// processing, e.g. MetalKit SIMD errors on macOS).
	directive_compile_flags, directive_link_flags := split_compile_and_link_flags(directive_flags)
	mut cc_flag_parts := []string{}
	mut cc_link_parts := []string{}
	env_flags := configured_cflags()
	if env_flags.trim_space() != '' {
		cc_flag_parts << env_flags.trim_space()
	}
	if cc.contains('tcc') && directive_flags.contains('thirdparty/sqlite/sqlite3.c')
		&& !directive_compile_flags.contains('SQLITE_DISABLE_INTRINSIC') {
		cc_flag_parts << '-DSQLITE_DISABLE_INTRINSIC'
	}
	if directive_compile_flags.trim_space() != '' {
		cc_flag_parts << directive_compile_flags.trim_space()
	}
	if directive_link_flags.trim_space() != '' {
		cc_link_parts << directive_link_flags.trim_space()
	}
	tcc_extra := tcc_flags(cc, b.pref.vroot)
	if tcc_extra.trim_space() != '' {
		cc_flag_parts << tcc_extra.trim_space()
	}
	// macOS code can include Objective-C (.m) files via #include directives.
	// Tell the C compiler to treat the source as Objective-C only when needed.
	$if macos {
		if cflags_need_objc_mode(directive_flags) {
			cc_flag_parts << '-x objective-c'
		}
	}
	cc_flag_parts << '-std=gnu11'
	cc_flag_parts << '-fwrapv'

	// Detect compiler type for optimization flags and error limit.
	is_tcc := cc.contains('tcc')
	mut is_clang := false
	if !is_tcc {
		version_res := os.execute('${cc} --version')
		if version_res.exit_code == 0 && version_res.output.contains('clang') {
			is_clang = true
		}
	}

	// -prod: add -O3, -flto, -DNDEBUG for gcc/clang
	if b.pref.is_prod {
		cc_flag_parts << '-O3'
		cc_flag_parts << '-DNDEBUG'
		if !b.pref.is_shared_lib {
			$if !windows {
				cc_flag_parts << '-flto'
			}
		}
		if !is_clang {
			cc_flag_parts << '-fno-strict-aliasing'
		}
	}

	cc_flags := cc_flag_parts.join(' ')
	cc_link_flags := cc_link_parts.join(' ')
	mut error_limit_flag := ''
	if is_clang {
		error_limit_flag = ' -ferror-limit=0'
	}

	// Fast path: cache one core object (builtin+strconv), compile/link only the rest.
	if use_cache && !b.pref.skip_builtin && b.has_module('builtin') && b.has_module('strconv') {
		if b.gen_cleanc_with_cached_core(output_name, cc, cc_flags, cc_link_flags,
			error_limit_flag, mut sw)
		{
			// Mirror the freshly built objects to the durable tier so a later cold
			// build (with /tmp wiped) can restore them and fast-relink.
			b.save_durable_object_cache(b.core_cache_dir())
			return
		}
	}

	// Fallback: compile one full C translation unit.
	c_source := b.gen_cleanc_source([]string{})
	print_time('C Gen', sw.elapsed())
	if c_source == '' {
		eprintln('error: cleanc backend is not fully functional (compiled with stubbed functions)')
		eprintln('hint: use v2 compiled with v1 for proper C code generation')
		return
	}
	os.write_file(staged_c_file, c_source) or { panic(err) }
	println('[*] Wrote ${staged_c_file}')
	b.compile_cleanc_executable(output_name, cc, cc_flags, cc_link_flags, error_limit_flag, mut sw)
}

fn (b &Builder) is_cmd_v2_self_build() bool {
	if b.user_files.len != 1 {
		return false
	}
	// Avoid path normalization here: during bootstraps, some intermediate
	// compilers can still have unstable path helpers.
	path := b.user_files[0].replace('\\', '/')
	if path == 'v2.v' || path.ends_with('/v2.v') {
		return true
	}
	return path.ends_with('/cmd/v2/v2.v') || path.ends_with('cmd/v2/v2.v')
}

fn (b &Builder) should_disable_cleanc_cache() bool {
	// ARM64 cache previously disabled due to runtime helpers being emitted
	// as static inline, which dropped them at cached-core boundaries.
	// Fixed: __v2_array_eq is now a regular function with its body in the
	// builtin cache unit and a forward declaration in the main TU.
	for raw_input in b.user_files {
		input := raw_input.trim_right('/\\')
		if input.len == 0 {
			continue
		}
		if input.ends_with('.v') || input.ends_with('.vv') || input.ends_with('.vsh')
			|| input.ends_with('.vh') {
			continue
		}
	}
	return false
}

fn (b &Builder) default_output_name() string {
	if b.user_files.len == 0 {
		return 'out'
	}
	last_input := b.user_files[b.user_files.len - 1].trim_right('/\\')
	if last_input.len == 0 || last_input == '.' {
		cwd := os.getwd()
		base := os.file_name(cwd)
		return if base.len > 0 { base } else { 'out' }
	}
	if os.is_dir(last_input) {
		base := os.file_name(last_input)
		return if base.len > 0 { base } else { 'out' }
	}
	base := os.file_name(last_input).all_before_last('.v')
	return if base.len > 0 { base } else { os.file_name(last_input) }
}

fn (mut b Builder) gen_ssa_c() {
	// SSA -> C backend.
	mut sw := time.new_stopwatch()

	mut mod := ssa.Module.new('main')
	if mod == unsafe { nil } {
		eprintln('error: ssa c backend not available (compiled with stubbed ssa module)')
		eprintln('hint: use v2 compiled with v1 for ssa c code generation')
		return
	}
	mut ssa_builder := ssa.Builder.new_with_env(mod, b.env)
	ssa_builder.target_os = b.pref.target_os_or_host()

	mut stage_start := sw.elapsed()
	mut built_from_flat := false
	if b.should_build_ssa_from_flat() {
		ssa_builder.build_all_from_flat(&b.flat)
		built_from_flat = true
	} else {
		ssa_builder.build_all(b.files)
	}
	print_time('SSA Build', time.Duration(sw.elapsed() - stage_start))

	// TODO: re-enable SSA optimization once the new builder is mature
	// stage_start = sw.elapsed()
	// optimize.optimize(mut mod)
	// print_time('SSA Optimize', time.Duration(sw.elapsed() - stage_start))

	output_name := if b.pref.output_file != '' {
		b.pref.output_file
	} else if b.user_files.len > 0 {
		b.default_output_name()
	} else {
		'out'
	}

	if output_name.ends_with('.c') {
		if built_from_flat {
			b.flat = ast.FlatAst{}
		}
		stage_start = sw.elapsed()
		mut gen := c.new_gen(mod)
		c_source := gen.gen()
		print_time('C Gen', time.Duration(sw.elapsed() - stage_start))
		if c_source == '' {
			eprintln('error: ssa c backend failed to generate C source')
			return
		}
		os.write_file(output_name, c_source) or { panic(err) }
		println('[*] Wrote ${output_name}')
		return
	}

	cc := if b.pref.ccompiler.len > 0 { b.pref.ccompiler } else { configured_cc(b.pref.vroot) }
	directive_flags := b.collect_cflags_from_sources()
	if built_from_flat {
		// SSA has copied the program into MIR, and directive scanning has read
		// source names from the FlatAst. Keep the later C generator/compiler
		// working sets clear of the transformed FlatAst.
		b.flat = ast.FlatAst{}
	}
	mut cc_flag_parts := []string{}
	env_flags := configured_cflags()
	if env_flags.trim_space() != '' {
		cc_flag_parts << env_flags.trim_space()
	}
	if cc.contains('tcc') && directive_flags.contains('thirdparty/sqlite/sqlite3.c')
		&& !directive_flags.contains('SQLITE_DISABLE_INTRINSIC') {
		cc_flag_parts << '-DSQLITE_DISABLE_INTRINSIC'
	}
	if directive_flags.trim_space() != '' {
		cc_flag_parts << directive_flags.trim_space()
	}
	tcc_extra := tcc_flags(cc, b.pref.vroot)
	if tcc_extra.trim_space() != '' {
		cc_flag_parts << tcc_extra.trim_space()
	}
	cc_flags := cc_flag_parts.join(' ')
	mut error_limit_flag := ''
	if !cc.contains('tcc') {
		version_res := os.execute('${cc} --version')
		if version_res.exit_code == 0 && version_res.output.contains('clang') {
			error_limit_flag = ' -ferror-limit=0'
		}
	}

	// Try to get pre-compiled builtin.o and vlib.o from the cleanc cache
	mut builtin_obj := ''
	mut vlib_obj := ''
	if !b.pref.skip_builtin && b.has_module('builtin') && b.has_module('strconv')
		&& b.ensure_core_cache_dir() {
		cache_dir := b.core_cache_dir()
		builtin_obj = b.ensure_cached_module_object(cache_dir, builtin_cache_name,
			builtin_cached_module_paths, builtin_cached_module_names, cc, cc_flags, '',
			error_limit_flag, false) or { '' }
		if builtin_obj.len > 0 && vlib_cached_module_paths.len > 0 {
			vlib_obj = b.ensure_cached_module_object(cache_dir, vlib_cache_name,
				vlib_cached_module_paths, vlib_cached_module_names, cc, cc_flags, '',
				error_limit_flag, false) or { '' }
		}
	}
	stage_start = sw.elapsed()
	mut gen := c.new_gen(mod)
	gen.link_builtin = builtin_obj.len > 0
	c_source := gen.gen()
	print_time('C Gen', time.Duration(sw.elapsed() - stage_start))
	if c_source == '' {
		eprintln('error: ssa c backend failed to generate C source')
		return
	}

	c_file := b.exec_build_c_file(output_name)
	os.write_file(c_file, c_source) or { panic(err) }
	if c_file != staged_c_file {
		os.write_file(staged_c_file, c_source) or { panic(err) }
	}
	println('[*] Wrote ${c_file}')

	cc_start := sw.elapsed()
	mut cc_cmd := ''
	if builtin_obj.len > 0 {
		// Compile SSA main.c and link against pre-compiled builtin.o
		main_obj := staged_main_obj_file
		compile_cmd := '${cc} ${cc_flags} -w -c "${c_file}" -o "${main_obj}"${error_limit_flag}'
		if b.pref.show_cc {
			println(compile_cmd)
		}
		compile_res := os.execute(compile_cmd)
		if compile_res.exit_code != 0 {
			eprintln('error: ssa c backend compilation failed')
			lines := compile_res.output.split_into_lines()
			limit := if lines.len < 20 { lines.len } else { 20 }
			for line in lines[..limit] {
				eprintln(line)
			}
			exit(1)
		}
		mut link_objects := '"${main_obj}" "${builtin_obj}"'
		if vlib_obj.len > 0 {
			link_objects += ' "${vlib_obj}"'
		}
		cc_cmd = '${cc} ${cc_flags} -w ${link_objects} -o "${output_name}"'
		if b.pref.show_cc {
			println(cc_cmd)
		}
		cc_res := os.execute(cc_cmd)
		if cc_res.exit_code != 0 {
			eprintln('error: ssa c backend linking failed')
			lines := cc_res.output.split_into_lines()
			limit := if lines.len < 20 { lines.len } else { 20 }
			for line in lines[..limit] {
				eprintln(line)
			}
			exit(1)
		}
		if !b.pref.keep_c {
			os.rm(main_obj) or {}
		}
	} else {
		// Single-file compilation (no builtin linking)
		cc_cmd = '${cc} ${cc_flags} -w "${c_file}" -o "${output_name}"${error_limit_flag}'
		if b.pref.show_cc {
			println(cc_cmd)
		} else if os.getenv('V2VERBOSE') != '' {
			dump(cc_cmd)
		}
		cc_res := os.execute(cc_cmd)
		if cc_res.exit_code != 0 {
			eprintln('error: ssa c backend compilation failed')
			lines := cc_res.output.split_into_lines()
			limit := if lines.len < 20 { lines.len } else { 20 }
			for line in lines[..limit] {
				eprintln(line)
			}
			exit(1)
		}
	}
	print_time('CC', time.Duration(sw.elapsed() - cc_start))

	if !b.pref.keep_c {
		os.rm(c_file) or {}
	}
	println('[*] Compiled ${output_name}')
}

fn (mut b Builder) gen_cleanc_source(modules []string) string {
	return b.gen_cleanc_source_with_options(modules, []string{}, false, '', []string{}, true,
		[]string{})
}

fn (mut b Builder) gen_cleanc_source_for_cache(modules []string, cache_bundle_name string, use_markused bool) string {
	return b.gen_cleanc_source_with_options(modules, []string{}, true, cache_bundle_name,
		[]string{}, use_markused, []string{})
}

fn (mut b Builder) gen_cleanc_source_for_cache_files(modules []string, emit_files []string, cache_bundle_name string, use_markused bool) string {
	return b.gen_cleanc_source_with_options(modules, emit_files, true, cache_bundle_name,
		[]string{}, use_markused, []string{})
}

fn (mut b Builder) gen_cleanc_source_with_cache_init_calls(modules []string, cached_init_calls []string) string {
	return b.gen_cleanc_source_with_options(modules, []string{}, false, '', cached_init_calls,
		true, []string{})
}

fn (mut b Builder) gen_cleanc_source_with_cache_init_calls_and_files(modules []string, emit_files []string, cached_init_calls []string, use_markused bool) string {
	return b.gen_cleanc_source_with_options(modules, emit_files, false, '', cached_init_calls,
		use_markused, []string{})
}

fn (mut b Builder) gen_cleanc_source_with_cache_init_calls_files_force(modules []string, emit_files []string, cached_init_calls []string, use_markused bool, force_emit_fn_names []string) string {
	return b.gen_cleanc_source_with_options(modules, emit_files, false, '', cached_init_calls,
		use_markused, force_emit_fn_names)
}

fn (mut b Builder) gen_cleanc_source_with_options(modules []string, emit_files []string, export_const_symbols bool, cache_bundle_name string, cached_init_calls []string, use_markused bool, force_emit_fn_names []string) string {
	type_modules := if cache_bundle_name.len > 0 {
		b.expand_type_modules_with_imports(cache_type_module_names(cache_bundle_name, modules))
	} else {
		cache_type_module_names(cache_bundle_name, modules)
	}
	mut type_module_names := map[string]bool{}
	restrict_to_cache_modules := cache_bundle_name.len > 0 && type_modules.len > 0
	if restrict_to_cache_modules {
		for module_name in type_modules {
			if module_name != '' {
				type_module_names[module_name] = true
			}
		}
	}
	// Cache-bundle generation restricts emission to a fixed set of type
	// modules. The legacy gen achieves this by filtering its input `gen_files`;
	// the flat gen drives every pass off `flat.files`, so for a restricted
	// bundle in flat mode we hand it a FlatAst scoped to the bundle's type
	// modules (sharing b.flat's arena). The main translation unit
	// (`restrict_to_cache_modules == false`) uses the full b.flat.
	scope_flat_bundle := restrict_to_cache_modules && b.flat.files.len > 0
	scoped_flat := if scope_flat_bundle {
		b.flat_scoped_to_modules(type_module_names)
	} else {
		ast.FlatAst{}
	}
	mut gen_files := []ast.File{cap: b.files.len}
	if !scope_flat_bundle {
		for file in b.files {
			if restrict_to_cache_modules && ast_file_module_name(file) !in type_module_names {
				continue
			}
			gen_files << file
		}
	}
	if !scope_flat_bundle && cached_init_calls.len > 0 && b.used_vh_for_parse {
		mut has_vh_files := false
		for file in gen_files {
			if file.name.ends_with('.vh') {
				has_vh_files = true
				break
			}
		}
		if !has_vh_files {
			mut p := parser.Parser.new(b.pref)
			header_files := p.parse_files(b.core_cached_parse_paths(), mut b.file_set)
			for header_file in header_files {
				gen_files << header_file
			}
		}
	}
	mut gen := if scope_flat_bundle {
		cleanc.Gen.new_with_env_pref_and_flat(&scoped_flat, b.env, b.pref)
	} else if b.flat.files.len > 0 {
		cleanc.Gen.new_with_env_pref_and_flat(&b.flat, b.env, b.pref)
	} else {
		cleanc.Gen.new_with_env_and_pref(gen_files, b.env, b.pref)
	}
	if modules.len > 0 {
		gen.set_emit_modules(modules)
	}
	if type_modules.len > 0 {
		gen.set_type_modules(type_modules)
	}
	if emit_files.len > 0 {
		gen.set_emit_files(emit_files)
	}
	if use_markused && b.used_fn_keys.len > 0 {
		gen.set_used_fn_keys(b.used_fn_keys)
	}
	if force_emit_fn_names.len > 0 {
		gen.set_force_emit_fn_names(force_emit_fn_names)
	}
	gen.set_export_const_symbols(export_const_symbols)
	if cache_bundle_name.len > 0 {
		gen.set_cache_bundle_name(cache_bundle_name)
	}
	if cached_init_calls.len > 0 {
		gen.set_cached_init_calls(cached_init_calls)
	}
	if cache_bundle_name.len == 0 && cached_init_calls.len > 0 && b.cached_called_fn_names.len > 0 {
		gen.add_called_fn_names(b.cached_called_fn_name_list())
	}
	if cache_bundle_name.len == 0 && cached_init_calls.len > 0
		&& b.has_v2compiler_generic_setup_snapshot {
		gen.use_generic_setup_snapshot(b.v2compiler_generic_setup_snapshot)
	}
	use_parallel := b.pref != unsafe { nil } && !b.pref.no_parallel
	if use_parallel {
		gen.gen_passes_1_to_4()
		if cache_bundle_name == v2compiler_cache_name {
			b.v2compiler_generic_setup_snapshot = gen.generic_setup_snapshot()
			b.has_v2compiler_generic_setup_snapshot = true
		}
		b.gen_cleanc_parallel(mut gen)
		source := gen.gen_finalize()
		if cache_bundle_name.len > 0 {
			b.add_cached_called_fn_names(gen.external_called_fn_names())
		}
		if os.getenv('V2TRACE_CLEANC') != '' {
			eprintln('TRACE_CLEANC builder_files=${b.files.len} gen_files=${gen_files.len} source_len=${source.len}')
		}
		return source
	}
	source := gen.gen()
	if cache_bundle_name == v2compiler_cache_name {
		b.v2compiler_generic_setup_snapshot = gen.generic_setup_snapshot()
		b.has_v2compiler_generic_setup_snapshot = true
	}
	if cache_bundle_name.len > 0 {
		b.add_cached_called_fn_names(gen.external_called_fn_names())
	}
	if os.getenv('V2TRACE_CLEANC') != '' {
		eprintln('TRACE_CLEANC builder_files=${b.files.len} gen_files=${gen_files.len} source_len=${source.len}')
	}
	return source
}

fn (mut b Builder) add_cached_called_fn_names(names []string) {
	for name in names {
		if name.len > 0 {
			b.cached_called_fn_names[name] = true
		}
	}
}

fn (b &Builder) cached_called_fn_name_list() []string {
	mut names := b.cached_called_fn_names.keys()
	names.sort()
	return names
}

fn cached_called_fn_names_path(cache_dir string, cache_name string) string {
	return cache_path_join(cache_dir, '${cache_name}.calls')
}

fn (mut b Builder) load_cached_called_fn_names(cache_dir string, cache_name string) bool {
	data := os.read_file(cached_called_fn_names_path(cache_dir, cache_name)) or { return false }
	for line in data.split_into_lines() {
		name := line.trim_space()
		if name.len > 0 {
			b.cached_called_fn_names[name] = true
		}
	}
	return true
}

fn (mut b Builder) write_cached_called_fn_names(cache_dir string, cache_name string, before map[string]bool) {
	mut names := []string{}
	for name, _ in b.cached_called_fn_names {
		if name.len == 0 || name in before {
			continue
		}
		names << name
	}
	names.sort()
	os.write_file(cached_called_fn_names_path(cache_dir, cache_name), names.join('\n')) or {}
}

fn (b &Builder) cgen_builder_stats_enabled() bool {
	return b.pref != unsafe { nil } && b.pref.stats
}

fn (b &Builder) mark_cgen_builder_step(stats_enabled bool, cache_name string, mut sw time.StopWatch, stage_start time.Duration, step string) time.Duration {
	if !stats_enabled {
		return stage_start
	}
	now := sw.elapsed()
	println('   - C Gen/cache:${cache_name} cache.${step}: ${time.Duration(now - stage_start).milliseconds()}ms')
	return now
}

fn cache_type_module_names(cache_bundle_name string, emit_modules []string) []string {
	if cache_bundle_name == '' {
		return emit_modules
	}
	mut names := []string{cap: core_cached_module_names.len + emit_modules.len}
	if cache_bundle_name == builtin_cache_name {
		names << emit_modules
	} else if cache_bundle_name == vlib_cache_name {
		names << builtin_cached_module_names
		names << emit_modules
	} else {
		names << core_cached_module_names
		names << emit_modules
	}
	return unique_sorted_strings(names)
}

fn (b &Builder) expand_type_modules_with_imports(modules []string) []string {
	mut type_modules := map[string]bool{}
	for module_name in modules {
		if module_name != '' {
			type_modules[module_name] = true
		}
	}
	use_flat := b.uses_flat_module_enumeration()
	mut changed := true
	for changed {
		changed = false
		if use_flat {
			for i in 0 .. b.flat.files.len {
				if b.flat_file_module_name(i) !in type_modules {
					continue
				}
				for import_stmt in b.flat.file_cursor(i).imports().import_stmts() {
					import_module := import_module_name(import_stmt.name)
					if import_module == '' || import_module in type_modules {
						continue
					}
					type_modules[import_module] = true
					changed = true
				}
			}
		} else {
			for file in b.files {
				if ast_file_module_name(file) !in type_modules {
					continue
				}
				for import_stmt in file.imports {
					import_module := import_module_name(import_stmt.name)
					if import_module == '' || import_module in type_modules {
						continue
					}
					type_modules[import_module] = true
					changed = true
				}
			}
		}
	}
	return unique_sorted_strings(type_modules.keys())
}

fn (b &Builder) has_external_cache_module_name_collision(module_names []string) bool {
	mut module_set := map[string]bool{}
	for module_name in module_names {
		if module_name != '' {
			module_set[module_name] = true
		}
	}
	mut vlib_modules := map[string]bool{}
	mut external_modules := map[string]bool{}
	if b.uses_flat_module_enumeration() {
		for i in 0 .. b.flat.files.len {
			name := b.flat.file_name(b.flat.files[i])
			if name == '' || name.ends_with('.vh') {
				continue
			}
			module_name := b.flat_file_module_name(i)
			if module_name !in module_set {
				continue
			}
			if b.is_vlib_source_file(name) {
				vlib_modules[module_name] = true
			} else {
				external_modules[module_name] = true
			}
		}
	} else {
		for file in b.files {
			if file.name == '' || file.name.ends_with('.vh') {
				continue
			}
			module_name := ast_file_module_name(file)
			if module_name !in module_set {
				continue
			}
			if b.is_vlib_source_file(file.name) {
				vlib_modules[module_name] = true
			} else {
				external_modules[module_name] = true
			}
		}
	}
	for module_name, _ in external_modules {
		if module_name in vlib_modules {
			return true
		}
	}
	return false
}

fn (b &Builder) is_vlib_source_file(file_name string) bool {
	root := if b.pref.vroot.len > 0 { b.pref.vroot } else { os.getwd() }
	vlib_root := os.norm_path(os.join_path(root, 'vlib')) + os.path_separator
	return os.norm_path(os.abs_path(file_name)).starts_with(vlib_root)
}

fn import_module_name(name string) string {
	return name.all_after_last('.').replace('.', '_')
}

fn unique_sorted_strings(items []string) []string {
	mut seen := map[string]bool{}
	mut out := []string{cap: items.len}
	for item in items {
		if item == '' || item in seen {
			continue
		}
		seen[item] = true
		out << item
	}
	out.sort()
	return out
}

fn (mut b Builder) gen_cleanc_with_cached_core(output_name string, cc string, cc_flags string, cc_link_flags string, error_limit_flag string, mut sw time.StopWatch) bool {
	cache_dir := b.core_cache_dir()
	if !b.ensure_core_cache_dir() {
		// If we cannot create a readable/writable cache dir, fall back to full compilation.
		if os.getenv('V2_TRACE_CACHE') != '' {
			eprintln('TRACE_CACHE cached_core=false reason=cache_dir_unusable')
		}
		return false
	}
	if b.try_link_cached_self_main_object(output_name, cache_dir, cc, cc_flags, cc_link_flags, mut
		sw)
	{
		return true
	}

	builtin_obj := b.ensure_cached_module_object(cache_dir, builtin_cache_name,
		builtin_cached_module_paths, builtin_cached_module_names, cc, cc_flags, '',
		error_limit_flag, false) or {
		if os.getenv('V2_TRACE_CACHE') != '' {
			eprintln('TRACE_CACHE cached_core=false reason=builtin_obj_failed')
		}
		return false
	}
	b.print_cached_bundle_modules(builtin_cache_name, builtin_cached_module_names)
	mut vlib_obj := ''
	if vlib_cached_module_paths.len > 0 {
		vlib_obj = b.ensure_cached_module_object(cache_dir, vlib_cache_name,
			vlib_cached_module_paths, vlib_cached_module_names, cc, cc_flags, '', error_limit_flag,
			false) or {
			if os.getenv('V2_TRACE_CACHE') != '' {
				eprintln('TRACE_CACHE cached_core=false reason=vlib_obj_failed')
			}
			return false
		}
		if vlib_obj.len > 0 {
			b.print_cached_bundle_modules(vlib_cache_name, vlib_cached_module_names)
		}
	}
	mut optional_cached_objs := []string{}
	mut optional_cached_cache_names := []string{}
	mut optional_cached_module_names := []string{}
	if veb_cached_module_paths.len > 0 && b.has_module('veb') {
		veb_cache_type_modules := b.expand_type_modules_with_imports(cache_type_module_names(veb_cache_name,
			veb_cached_module_names))
		veb_obj := if b.has_external_cache_module_name_collision(veb_cache_type_modules) {
			if os.getenv('V2_TRACE_CACHE') != '' {
				eprintln('TRACE_CACHE optional_cache=veb reason=external_module_name_collision')
			}
			''
		} else {
			b.ensure_cached_module_object(cache_dir, veb_cache_name, veb_cached_module_paths,
				veb_cached_module_names, cc, cc_flags, cc_link_flags, error_limit_flag, true) or {
				if os.getenv('V2_TRACE_CACHE') != '' {
					eprintln('TRACE_CACHE optional_cache=veb reason=${err}')
				}
				''
			}
		}
		if veb_obj.len > 0 {
			b.print_cached_bundle_modules(veb_cache_name, veb_cached_module_names)
			optional_cached_objs << veb_obj
			optional_cached_cache_names << veb_cache_name
			optional_cached_module_names << veb_cached_module_names
		}
	}
	mut v2compiler_obj := ''
	if v2compiler_cached_module_paths.len > 0 && b.is_cmd_v2_self_build() {
		v2compiler_obj = b.ensure_cached_module_object(cache_dir, v2compiler_cache_name,
			v2compiler_cached_module_paths, v2compiler_cached_module_names, cc, cc_flags, '',
			error_limit_flag, false) or {
			if os.getenv('V2_TRACE_CACHE') != '' {
				eprintln('TRACE_CACHE cached_core=false reason=v2compiler_obj_failed')
			}
			return false
		}
		if v2compiler_obj.len > 0 {
			b.print_cached_bundle_modules(v2compiler_cache_name, v2compiler_cached_module_names)
		}
	}
	mut dynamic_excluded := core_cached_module_names.clone()
	for module_name in optional_cached_module_names {
		dynamic_excluded << module_name
	}
	entry_module_names := b.user_entry_module_names()
	dynamic_excluded << entry_module_names
	if b.is_cmd_v2_self_build() {
		dynamic_excluded << v2compiler_cached_module_names
	}
	dynamic_excluded << 'main'
	dynamic_cached_module_names := b.collect_modules_excluding(dynamic_excluded)
	if dynamic_cached_module_names.len > 0 {
		mut import_dependency_cache_names := [builtin_cache_name]
		if vlib_obj.len > 0 {
			import_dependency_cache_names << vlib_cache_name
		}
		if v2compiler_obj.len > 0 {
			import_dependency_cache_names << v2compiler_cache_name
		}
		for cache_name in optional_cached_cache_names {
			import_dependency_cache_names << cache_name
		}
		import_dependency_compile_flags, import_dependency_link_flags :=
			b.cached_module_stamp_flags(import_dependency_cache_names)
		imports_cc_flags := join_flag_strings(cc_flags, import_dependency_compile_flags)
		imports_cc_link_flags := join_flag_strings(cc_link_flags, import_dependency_link_flags)
		imports_obj := b.ensure_cached_parsed_module_object(cache_dir, imports_cache_name,
			dynamic_cached_module_names, import_dependency_cache_names, cc, imports_cc_flags,
			imports_cc_link_flags, error_limit_flag, true) or {
			if os.getenv('V2_TRACE_CACHE') != '' {
				eprintln('TRACE_CACHE optional_cache=imports reason=${err}')
			}
			if b.used_import_vh_for_parse {
				return false
			}
			''
		}
		if imports_obj.len > 0 {
			b.print_cached_bundle_modules(imports_cache_name, dynamic_cached_module_names)
			optional_cached_objs << imports_obj
			optional_cached_cache_names << imports_cache_name
			optional_cached_module_names << dynamic_cached_module_names
		}
	}
	mut virtual_groups := if b.used_virtual_vh_for_parse {
		b.cached_virtual_manifest()
	} else {
		b.collect_virtual_main_modules()
	}
	mut virtual_source_files := []string{}
	mut virtuals_obj := ''
	if virtual_groups.len > 0 {
		mut virtual_dependency_cache_names := [builtin_cache_name]
		if vlib_obj.len > 0 {
			virtual_dependency_cache_names << vlib_cache_name
		}
		if v2compiler_obj.len > 0 {
			virtual_dependency_cache_names << v2compiler_cache_name
		}
		for cache_name in optional_cached_cache_names {
			virtual_dependency_cache_names << cache_name
		}
		virtual_dependency_compile_flags, virtual_dependency_link_flags :=
			b.cached_module_stamp_flags(virtual_dependency_cache_names)
		virtual_cc_flags := join_flag_strings(cc_flags, virtual_dependency_compile_flags)
		virtual_cc_link_flags := join_flag_strings(cc_link_flags, virtual_dependency_link_flags)
		virtuals_obj = b.ensure_cached_virtual_module_object(cache_dir, virtual_groups,
			virtual_dependency_cache_names, cc, virtual_cc_flags, virtual_cc_link_flags,
			error_limit_flag, true) or {
			if os.getenv('V2_TRACE_CACHE') != '' {
				eprintln('TRACE_CACHE optional_cache=${virtuals_cache_name} reason=${err}')
			}
			if b.used_virtual_vh_for_parse {
				return false
			}
			virtual_groups = []CachedVirtualModule{}
			''
		}
		if virtuals_obj.len > 0 {
			virtual_source_files = virtual_module_source_files(virtual_groups)
			b.print_cached_bundle_modules(virtuals_cache_name, virtual_module_names(virtual_groups))
		}
	}
	b.ensure_core_module_headers()
	b.ensure_import_module_headers(dynamic_cached_module_names)
	// The v2compiler .vh headers are read back only by can_use_cached_v2compiler_headers_for_parse
	// (via cached_import_parse_path). That parse-reuse path was disabled because the generated
	// headers are not yet complete/safe, so the 21 module headers are write-only on every cold
	// self-build — ~230ms of pure overhead. Skip generation until reuse is re-enabled (the headers
	// are regenerated on demand the moment it is; see v2compiler_headers_consumed_for_parse).
	if v2compiler_obj.len > 0 && b.v2compiler_headers_consumed_for_parse() {
		b.ensure_v2compiler_module_headers()
	}
	b.ensure_virtual_module_headers(virtual_groups)
	mut excluded := core_cached_module_names.clone()
	for module_name in optional_cached_module_names {
		excluded << module_name
	}
	if b.is_cmd_v2_self_build() {
		excluded << v2compiler_cached_module_names
	}
	main_modules := b.collect_modules_excluding(excluded)
	if main_modules.len == 0 {
		if os.getenv('V2_TRACE_CACHE') != '' {
			eprintln('TRACE_CACHE cached_core=false reason=no_main_modules')
		}
		return false
	}
	mut linked_cache_names := [builtin_cache_name]
	if vlib_obj.len > 0 {
		linked_cache_names << vlib_cache_name
	}
	if v2compiler_obj.len > 0 {
		linked_cache_names << v2compiler_cache_name
	}
	for cache_name in optional_cached_cache_names {
		linked_cache_names << cache_name
	}
	cached_compile_flags, cached_link_flags := b.cached_module_stamp_flags(linked_cache_names)

	// When TCC is the default compiler but fell back to cc for cache
	// compilation (e.g. due to TCC not supporting certain C constructs),
	// the cached .o files are Mach-O (from cc) while TCC would produce ELF.
	// Detect this mismatch and use cc for main compilation and linking too.
	// Also, -prod builds with -flto require gcc/clang for linking — TCC
	// cannot link LTO object files.
	mut main_cc := cc
	mut main_cc_flags := join_flag_strings(cc_flags, cached_compile_flags)
	main_cc_link_flags := join_flag_strings(cc_link_flags, cached_link_flags)
	if cc.contains('tcc') && os.exists(builtin_obj) {
		bytes := os.read_bytes(builtin_obj) or { []u8{} }
		is_elf := bytes.len >= 4 && bytes[0] == 0x7f && bytes[1] == 0x45 && bytes[2] == 0x4c
			&& bytes[3] == 0x46
		if !is_elf {
			// Cached .o was compiled by cc (via TCC fallback), not TCC.
			// Use cc for main compilation and linking to match formats.
			// Keep all flags (including directive -I paths) but strip
			// TCC-specific -I/-L paths that would conflict with system headers.
			main_cc = 'cc'
			tcc_dir2 := cc.all_before_last('/tcc')
			if tcc_dir2.len > 0 {
				mut parts := main_cc_flags.fields()
				mut filtered := []string{cap: parts.len}
				mut j := 0
				for j < parts.len {
					p := parts[j]
					if (p == '-I' || p == '-L') && j + 1 < parts.len && parts[j + 1].contains('tcc') {
						j += 2
						continue
					}
					if (p.starts_with('-I') || p.starts_with('-L')) && p.contains('tcc') {
						j++
						continue
					}
					// Strip quoted -I/-L containing tcc
					if (p.starts_with('-I"') || p.starts_with('-L"')
						|| p.starts_with("-I'") || p.starts_with("-L'")) && p.contains('tcc') {
						j++
						continue
					}
					filtered << p
					j++
				}
				main_cc_flags = filtered.join(' ')
			}
		}
	}

	mut cached_init_calls := []string{}
	cached_init_calls << '__v2_cached_init_${builtin_cache_name}'
	if vlib_obj.len > 0 {
		cached_init_calls << '__v2_cached_init_${vlib_cache_name}'
	}
	if v2compiler_obj.len > 0 {
		cached_init_calls << '__v2_cached_init_${v2compiler_cache_name}'
	}
	for cache_name in optional_cached_cache_names {
		cached_init_calls << '__v2_cached_init_${cache_name}'
	}
	all_main_emit_files := if virtual_source_files.len > 0 {
		filter_out_source_files(b.module_source_files(main_modules), virtual_source_files)
	} else {
		[]string{}
	}
	use_self_main_cache := b.should_skip_markused_for_self_build() && !b.pref.keep_c
	self_main_obj := cache_path_join(cache_dir, 'main.o')
	self_main_c := cache_path_join(cache_dir, 'main.c')
	self_main_stamp := cache_path_join(cache_dir, 'main.stamp')
	self_main_expected_stamp := if use_self_main_cache {
		b.cache_stamp_for_self_main_object(main_modules, all_main_emit_files, linked_cache_names,
			main_cc, main_cc_flags, main_cc_link_flags, cached_init_calls)
	} else {
		''
	}
	if use_self_main_cache && os.exists(self_main_obj) && os.exists(self_main_stamp) {
		if current_stamp := os.read_file(self_main_stamp) {
			if current_stamp == self_main_expected_stamp {
				print_time('C Gen', sw.elapsed())
				if os.getenv('V2VERBOSE') != '' {
					println('[*] Reusing ${self_main_obj}')
				}
				b.link_cleanc_cached_core_executable(output_name, main_cc, main_cc_flags,
					main_cc_link_flags, self_main_obj, builtin_obj, vlib_obj, v2compiler_obj,
					optional_cached_objs, virtuals_obj, mut sw)
				if os.getenv('V2_TRACE_CACHE') != '' {
					eprintln('TRACE_CACHE cached_core=true main_obj_cache=true')
				}
				return true
			}
		}
	}
	mut main_source := if all_main_emit_files.len > 0 {
		b.gen_cleanc_source_with_cache_init_calls_files_force(main_modules, all_main_emit_files,
			cached_init_calls, true, []string{})
	} else {
		b.gen_cleanc_source_with_cache_init_calls(main_modules, cached_init_calls)
	}
	print_time('C Gen', sw.elapsed())
	if main_source == '' {
		if os.getenv('V2_TRACE_CACHE') != '' {
			eprintln('TRACE_CACHE cached_core=false reason=empty_main_source')
		}
		return false
	}

	main_c_file := if use_self_main_cache { self_main_c } else { b.exec_build_c_file(output_name) }
	os.write_file(main_c_file, main_source) or { return false }
	if !use_self_main_cache && main_c_file != staged_c_file {
		os.write_file(staged_c_file, main_source) or { return false }
	}
	println('[*] Wrote ${main_c_file}')

	main_tmp_obj := cache_path_join(cache_dir, 'main.tmp.o')
	main_obj := if use_self_main_cache { main_tmp_obj } else { staged_main_obj_file }
	compile_main_cmd := '${main_cc} ${main_cc_flags} -w -Wno-incompatible-function-pointer-types -c "${main_c_file}" -o "${main_obj}"${error_limit_flag}'
	main_fell_back := run_cc_cmd_or_exit(compile_main_cmd, 'C compilation', b.pref.show_cc)
	if main_fell_back && main_cc.contains('tcc') {
		// TCC failed on main.c but cached .o files are ELF (from TCC).
		// Fallback produced Mach-O main.o — can't link with ELF cache.
		// Fall back to non-cached full compilation.
		os.rm(main_obj) or {}
		if os.getenv('V2_TRACE_CACHE') != '' {
			eprintln('TRACE_CACHE cached_core=false reason=main_compile_fell_back')
		}
		return false
	}
	mut link_main_obj := main_obj
	if use_self_main_cache {
		os.rm(self_main_obj) or {}
		os.mv(main_obj, self_main_obj) or { return false }
		os.write_file(self_main_stamp, self_main_expected_stamp) or { return false }
		link_main_obj = self_main_obj
	}
	b.link_cleanc_cached_core_executable(output_name, main_cc, main_cc_flags, main_cc_link_flags,
		link_main_obj, builtin_obj, vlib_obj, v2compiler_obj, optional_cached_objs, virtuals_obj, mut
		sw)

	if !b.pref.keep_c && !use_self_main_cache {
		os.rm(main_obj) or {}
		os.rm(main_c_file) or {}
	}
	if os.getenv('V2_TRACE_CACHE') != '' {
		eprintln('TRACE_CACHE cached_core=true')
	}
	return true
}

fn (mut b Builder) try_link_cached_self_main_object(output_name string, cache_dir string, cc string, cc_flags string, cc_link_flags string, mut sw time.StopWatch) bool {
	if !b.should_skip_markused_for_self_build() || b.pref.keep_c {
		return false
	}
	linked_cache_names := [builtin_cache_name, vlib_cache_name, v2compiler_cache_name,
		imports_cache_name]
	for cache_name in linked_cache_names {
		stamp_path := cache_path_join(cache_dir, '${cache_name}.stamp')
		if !os.exists(cache_path_join(cache_dir, '${cache_name}.o')) || !os.exists(stamp_path) {
			return false
		}
		stamp := os.read_file(stamp_path) or { return false }
		if !stamp_file_lines_are_fresh(stamp) {
			return false
		}
	}
	self_main_obj := cache_path_join(cache_dir, 'main.o')
	self_main_stamp := cache_path_join(cache_dir, 'main.stamp')
	if !os.exists(self_main_obj) || !os.exists(self_main_stamp) {
		return false
	}
	cached_compile_flags, cached_link_flags := b.cached_module_stamp_flags(linked_cache_names)
	main_cc := cc
	main_cc_flags := join_flag_strings(cc_flags, cached_compile_flags)
	main_cc_link_flags := join_flag_strings(cc_link_flags, cached_link_flags)
	if main_cc.contains('tcc') {
		builtin_obj := cache_path_join(cache_dir, '${builtin_cache_name}.o')
		bytes := os.read_bytes(builtin_obj) or { return false }
		is_elf := bytes.len >= 4 && bytes[0] == 0x7f && bytes[1] == 0x45 && bytes[2] == 0x4c
			&& bytes[3] == 0x46
		if !is_elf {
			return false
		}
	}
	cached_init_calls := [
		'__v2_cached_init_${builtin_cache_name}',
		'__v2_cached_init_${vlib_cache_name}',
		'__v2_cached_init_${v2compiler_cache_name}',
		'__v2_cached_init_${imports_cache_name}',
	]
	expected_stamp := b.cache_stamp_for_self_main_object(['main'], []string{}, linked_cache_names,
		main_cc, main_cc_flags, main_cc_link_flags, cached_init_calls)
	current_stamp := os.read_file(self_main_stamp) or { return false }
	if current_stamp != expected_stamp {
		return false
	}
	print_time('C Gen', sw.elapsed())
	if os.getenv('V2VERBOSE') != '' {
		println('[*] Reusing ${self_main_obj}')
	}
	b.link_cleanc_cached_core_executable(output_name, main_cc, main_cc_flags, main_cc_link_flags,
		self_main_obj, cache_path_join(cache_dir, '${builtin_cache_name}.o'), cache_path_join(cache_dir,
		'${vlib_cache_name}.o'), cache_path_join(cache_dir, '${v2compiler_cache_name}.o'), [
		cache_path_join(cache_dir, '${imports_cache_name}.o'),
	], '', mut sw)
	if os.getenv('V2_TRACE_CACHE') != '' {
		eprintln('TRACE_CACHE cached_core=true main_obj_cache=early')
	}
	return true
}

fn (mut b Builder) link_cleanc_cached_core_executable(output_name string, main_cc string, main_cc_flags string, main_cc_link_flags string, main_obj string, builtin_obj string, vlib_obj string, v2compiler_obj string, optional_cached_objs []string, virtuals_obj string, mut sw time.StopWatch) {
	cc_start := sw.elapsed()
	// Strip -c and -x flags from link command since we're linking, not compiling.
	// -x objective-c would cause cc to treat .o files as source code.
	mut link_flags :=
		main_cc_flags.replace('-x objective-c', '').replace('-x c', '').replace(' -c ', ' ')
	mut link_cmd := '${main_cc} ${link_flags} -w "${main_obj}" "${builtin_obj}"'
	if vlib_obj.len > 0 {
		link_cmd += ' "${vlib_obj}"'
	}
	if v2compiler_obj.len > 0 {
		link_cmd += ' "${v2compiler_obj}"'
	}
	for obj in optional_cached_objs {
		link_cmd += ' "${obj}"'
	}
	if virtuals_obj.len > 0 {
		link_cmd += ' "${virtuals_obj}"'
	}
	link_cmd += ' -o "${output_name}"'
	if main_cc_link_flags.len > 0 {
		link_cmd += ' ${main_cc_link_flags}'
	}
	run_cc_cmd_or_exit(link_cmd, 'Linking', b.pref.show_cc)
	print_time('CC', time.Duration(sw.elapsed() - cc_start))
	println('[*] Compiled ${output_name}')
}

// ---------------------------------------------------------------------------
// Durable persistent object cache (survives a /tmp obj-cache wipe).
// ---------------------------------------------------------------------------
// core_cache_dir() lives under os.temp_dir() and is what
// `rm -rf /tmp/v2_cleanc_obj_cache_<root>` removes for a "cold" measurement. A
// durable mirror under os.cache_dir() survives that wipe, so a cold self-host
// build with UNCHANGED sources can restore the prebuilt bundle objects + main.o
// and fast-relink instead of regenerating ~14MB of C. Correctness is enforced
// entirely by the existing stamp checks (try_self_build_fast_relink below): a
// restored object whose recorded source mtimes no longer match is ignored and
// rebuilt, so the durable tier can never yield a stale binary.

const self_build_persist_bundles = ['builtin', 'vlib', 'v2compiler', 'imports']

fn self_build_persist_file_names() []string {
	mut names := []string{cap: self_build_persist_bundles.len * 2 + 2}
	for name in self_build_persist_bundles {
		names << '${name}.o'
		names << '${name}.stamp'
	}
	names << 'main.o'
	names << 'main.stamp'
	return names
}

fn (b &Builder) durable_object_cache_dir() string {
	root := if b.pref.vroot.len > 0 { b.pref.vroot } else { os.getwd() }
	root_key := sanitize_cache_part(os.norm_path(os.abs_path(root)))
	base := if b.pref.is_prod { 'v2cleanc_persist_prod' } else { 'v2cleanc_persist' }
	return os.join_path(os.cache_dir(), base, root_key)
}

// copy_file_keep_mtime copies src->dst preserving src's mtime. Mtime preservation is
// required because main.stamp records `dependency:<bundle>:<mtime of that .stamp file>`,
// so a restored bundle .stamp must keep its original mtime or the relink probe misses.
fn copy_file_keep_mtime(src string, dst string) ! {
	data := os.read_bytes(src)!
	os.write_file_array(dst, data)!
	mtime := os.file_last_mod_unix(src)
	os.utime(dst, mtime, mtime)!
}

fn (b &Builder) save_durable_object_cache(cache_dir string) {
	if !b.is_cmd_v2_self_build() || b.pref.no_cache || b.pref.keep_c {
		return
	}
	durable_dir := b.durable_object_cache_dir()
	os.mkdir_all(durable_dir, mode: 0o700) or { return }
	for name in self_build_persist_file_names() {
		src := cache_path_join(cache_dir, name)
		if !os.exists(src) {
			continue
		}
		copy_file_keep_mtime(src, cache_path_join(durable_dir, name)) or { continue }
	}
}

fn (b &Builder) restore_durable_object_cache(cache_dir string) {
	if !b.is_cmd_v2_self_build() || b.pref.no_cache {
		return
	}
	durable_dir := b.durable_object_cache_dir()
	if !os.is_dir(durable_dir) {
		return
	}
	for name in self_build_persist_file_names() {
		dst := cache_path_join(cache_dir, name)
		if os.exists(dst) {
			// A /tmp copy already exists — never overwrite it with the durable mirror.
			continue
		}
		src := cache_path_join(durable_dir, name)
		if !os.exists(src) {
			continue
		}
		copy_file_keep_mtime(src, dst) or { continue }
	}
}

// try_self_build_fast_relink is the PRE-PARSE fast path for cmd/v2 self-host. When the
// cached bundle objects + main.o are present (restored from the durable tier if /tmp was
// wiped) and every source/compiler file they were built from is still fresh, it relinks the
// final binary directly and skips the entire front-end (parse + type-check + transform),
// which otherwise runs unconditionally. Conservative by construction: any staleness fails a
// freshness check and falls through to a normal build, so it can never emit a stale binary.
fn (mut b Builder) try_self_build_fast_relink() bool {
	trace := os.getenv('V2_TRACE_CACHE') != ''
	if b.pref.backend != .cleanc || b.pref.no_cache || b.pref.keep_c || b.pref.skip_builtin {
		return false
	}
	if !b.is_cmd_v2_self_build() || !b.should_skip_markused_for_self_build()
		|| b.should_disable_cleanc_cache() {
		if trace {
			eprintln('TRACE_CACHE fast_relink=false reason=guard self_build=${b.is_cmd_v2_self_build()} skip_mu=${b.should_skip_markused_for_self_build()} disable=${b.should_disable_cleanc_cache()}')
		}
		return false
	}
	// Mirror gen_cleanc()'s generation-only decision: a `.c` output, a target we
	// cannot compile locally, or a shared lib must go through normal C generation,
	// never a direct relink. is_cmd_v2_self_build() keys only on the input file, so
	// without this a warm-cache `-o foo.c cmd/v2/v2.v` would link an executable into
	// foo.c instead of writing C source.
	output_name := if b.pref.output_file != '' {
		b.pref.output_file
	} else if b.user_files.len > 0 {
		b.default_output_name()
	} else {
		'out'
	}
	if b.fast_relink_output_is_generation_only(output_name) {
		if trace {
			eprintln('TRACE_CACHE fast_relink=false reason=generation_only out=${output_name}')
		}
		return false
	}
	if !b.ensure_core_cache_dir() {
		return false
	}
	cache_dir := b.core_cache_dir()
	b.restore_durable_object_cache(cache_dir)

	// Every bundle object + stamp must exist and be source-fresh.
	for name in self_build_persist_bundles {
		if !os.exists(cache_path_join(cache_dir, '${name}.o')) {
			if trace {
				eprintln('TRACE_CACHE fast_relink=false reason=missing_obj ${name}')
			}
			return false
		}
		stamp := os.read_file(cache_path_join(cache_dir, '${name}.stamp')) or { return false }
		if !stamp_file_lines_are_fresh(stamp) {
			if trace {
				eprintln('TRACE_CACHE fast_relink=false reason=stale_bundle ${name}')
			}
			return false
		}
	}
	main_obj := cache_path_join(cache_dir, 'main.o')
	main_stamp := os.read_file(cache_path_join(cache_dir, 'main.stamp')) or { return false }
	if !os.exists(main_obj) || !stamp_file_lines_are_fresh(main_stamp) {
		if trace {
			eprintln('TRACE_CACHE fast_relink=false reason=stale_main main_obj=${os.exists(main_obj)}')
		}
		return false
	}
	// Validate the non-file build keys + dependency-stamp mtimes, and read back the relink
	// flags. The recorded flags are trusted rather than recomputed (recomputing needs the
	// parsed AST); the mtime-freshness checks are what guarantee the binary is up to date.
	mut main_cc := ''
	mut main_cc_flags := ''
	mut main_cc_link_flags := ''
	mut saw_self_build := false
	mut saw_flag_fp := false
	cur_flag_fp := b.preparse_flag_fingerprint()
	for line in main_stamp.split_into_lines() {
		if line.starts_with('cc=') {
			main_cc = line['cc='.len..]
		} else if line.starts_with('cc_flags=') {
			main_cc_flags = line['cc_flags='.len..]
		} else if line.starts_with('cc_link_flags=') {
			main_cc_link_flags = line['cc_link_flags='.len..]
		} else if line.starts_with('flag_fp=') {
			// The recorded cc/cc_flags/cc_link_flags are trusted (recomputing the
			// source-derived parts needs the AST). This fingerprint covers the
			// flag inputs that DON'T need parsing — compiler choice, prod/shared
			// mode, env CFLAGS — so a changed build environment invalidates the
			// relink even when every source file is unchanged.
			if line['flag_fp='.len..] != cur_flag_fp {
				if trace {
					eprintln('TRACE_CACHE fast_relink=false reason=flag_fp')
				}
				return false
			}
			saw_flag_fp = true
		} else if line.starts_with('context_alloc=') {
			if line['context_alloc='.len..] != '${b.pref.use_context_allocator}' {
				return false
			}
		} else if line.starts_with('target_os=') {
			if line['target_os='.len..] != b.pref.target_os_or_host() {
				return false
			}
		} else if line == 'self_build=true' {
			saw_self_build = true
		} else if line.starts_with('dependency:') {
			rest := line['dependency:'.len..]
			sep := rest.last_index(':') or { return false }
			dep_stamp := cache_path_join(cache_dir, '${rest[..sep]}.stamp')
			if '${os.file_last_mod_unix(dep_stamp)}' != rest[sep + 1..] {
				if trace {
					eprintln('TRACE_CACHE fast_relink=false reason=dep_mtime ${rest[..sep]} have=${os.file_last_mod_unix(dep_stamp)} want=${rest[
						sep + 1..]}')
				}
				return false
			}
		}
	}
	if !saw_self_build || main_cc.len == 0 || !saw_flag_fp {
		if trace {
			eprintln('TRACE_CACHE fast_relink=false reason=keys saw_self_build=${saw_self_build} cc=${main_cc} flag_fp=${saw_flag_fp}')
		}
		return false
	}
	mut sw := time.new_stopwatch()
	b.link_cleanc_cached_core_executable(output_name, main_cc, main_cc_flags, main_cc_link_flags,
		main_obj, cache_path_join(cache_dir, 'builtin.o'), cache_path_join(cache_dir, 'vlib.o'), cache_path_join(cache_dir,
		'v2compiler.o'), [cache_path_join(cache_dir, 'imports.o')], '', mut sw)
	if os.getenv('V2_TRACE_CACHE') != '' {
		eprintln('TRACE_CACHE self_build_fast_relink=true')
	}
	return true
}

fn (b &Builder) cache_stamp_for_self_main_object(main_modules []string, emit_files []string, linked_cache_names []string, main_cc string, main_cc_flags string, main_cc_link_flags string, cached_init_calls []string) string {
	source_files := b.module_source_files(main_modules)
	dependency_lines := b.cache_dependency_stamp_lines(linked_cache_names)
	mut lines := []string{cap: source_files.len + emit_files.len + dependency_lines.len +
		cached_init_calls.len + 12}
	lines << 'cache=main'
	lines << 'format=${core_cache_format}'
	lines << 'cc=${main_cc}'
	lines << 'cc_flags=${main_cc_flags}'
	lines << 'cc_link_flags=${main_cc_link_flags}'
	lines << 'flag_fp=${b.preparse_flag_fingerprint()}'
	lines << 'context_alloc=${b.pref.use_context_allocator}'
	lines << 'target_os=${b.pref.target_os_or_host()}'
	lines << 'self_build=true'
	exe := os.executable()
	lines << 'compiler_exe:${exe}:${os.file_last_mod_unix(exe)}'
	for module_name in main_modules {
		lines << 'module:${module_name}'
	}
	for init_call in cached_init_calls {
		lines << 'init:${init_call}'
	}
	lines << dependency_lines
	for file in b.user_entry_stamp_files() {
		lines << 'entry:${file}:${os.file_last_mod_unix(file)}'
	}
	for file in source_files {
		lines << 'source:${file}:${os.file_last_mod_unix(file)}'
	}
	for file in emit_files {
		lines << 'emit:${file}:${os.file_last_mod_unix(file)}'
	}
	return lines.join('\n')
}

fn (b &Builder) cached_module_stamp_flags(cache_names []string) (string, string) {
	cache_dir := b.core_cache_dir()
	mut compile_flags := ''
	mut link_flags := ''
	for cache_name in cache_names {
		stamp_path := os.join_path(cache_dir, '${cache_name}.stamp')
		stamp := os.read_file(stamp_path) or { continue }
		for line in stamp.split_into_lines() {
			if line.starts_with('cc_flags=') {
				compile_flags = join_flag_strings(compile_flags, line['cc_flags='.len..])
			} else if line.starts_with('cc_link_flags=') {
				link_flags = join_flag_strings(link_flags, line['cc_link_flags='.len..])
			}
		}
	}
	return compile_flags, link_flags
}

fn join_flag_strings(a string, b string) string {
	mut joined := []string{}
	for flags in [a, b] {
		for item in flag_string_items(flags) {
			if item !in joined {
				joined << item
			}
		}
	}
	return joined.join(' ')
}

fn flag_string_items(flags string) []string {
	tokens := flags.fields()
	mut items := []string{}
	mut i := 0
	for i < tokens.len {
		tok := tokens[i]
		if tok in ['-I', '-L', '-l', '-F', '-framework', '-isystem', '-include']
			&& i + 1 < tokens.len {
			items << '${tok} ${tokens[i + 1]}'
			i += 2
			continue
		}
		items << tok
		i++
	}
	return items
}

fn (mut b Builder) ensure_cached_module_object(cache_dir string, cache_name string, module_paths []string, emit_modules []string, cc string, cc_flags string, cc_link_flags string, error_limit_flag string, use_markused bool) !string {
	obj_path := cache_path_join(cache_dir, '${cache_name}.o')
	stamp_path := cache_path_join(cache_dir, '${cache_name}.stamp')
	c_path := cache_path_join(cache_dir, '${cache_name}.c')
	expected_stamp := b.cache_stamp_for_modules(cache_name, module_paths, cc, cc_flags,
		cc_link_flags, use_markused)
	if os.exists(obj_path) && os.exists(stamp_path) {
		if current_stamp := os.read_file(stamp_path) {
			if current_stamp == expected_stamp {
				if b.load_cached_called_fn_names(cache_dir, cache_name) {
					if os.getenv('V2VERBOSE') != '' {
						println('[*] Reusing ${obj_path}')
					}
					return obj_path
				}
			}
		}
	}
	if b.used_vh_for_parse {
		if os.exists(obj_path) && os.exists(stamp_path) {
			if b.load_cached_called_fn_names(cache_dir, cache_name) {
				return obj_path
			}
			return error('missing cached ${cache_name} call metadata for .vh parse')
		}
		return error('missing cached ${cache_name} object for .vh parse')
	}

	stats_enabled := b.cgen_builder_stats_enabled()
	mut stats_sw := time.new_stopwatch()
	mut stage_start := stats_sw.elapsed()
	cached_called_before := b.cached_called_fn_names.clone()
	stage_start = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start,
		'called_before_clone')
	module_source := b.gen_cleanc_source_for_cache(emit_modules, cache_name, use_markused)
	stage_start = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start,
		'source')
	if module_source == '' {
		return error('failed to generate C source for ${cache_name}')
	}
	os.write_file(c_path, module_source)!
	stage_start = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start,
		'write_c')

	compile_cmd := '${cc} ${cc_flags} -w -Wno-incompatible-function-pointer-types -c "${c_path}" -o "${obj_path}"${error_limit_flag}'
	run_cc_cmd_or_exit(compile_cmd, 'C compilation', b.pref.show_cc)
	stage_start =
		b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start, 'cc')
	b.write_cached_called_fn_names(cache_dir, cache_name, cached_called_before)
	os.write_file(stamp_path, expected_stamp)!
	_ = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start, 'metadata')
	return obj_path
}

fn (mut b Builder) ensure_cached_parsed_module_object(cache_dir string, cache_name string, module_names []string, dependency_cache_names []string, cc string, cc_flags string, cc_link_flags string, error_limit_flag string, use_markused bool) !string {
	obj_path := cache_path_join(cache_dir, '${cache_name}.o')
	stamp_path := cache_path_join(cache_dir, '${cache_name}.stamp')
	c_path := cache_path_join(cache_dir, '${cache_name}.c')
	expected_stamp := b.cache_stamp_for_parsed_modules(cache_name, module_names,
		dependency_cache_names, cc, cc_flags, cc_link_flags, use_markused)
	if os.exists(obj_path) && os.exists(stamp_path) {
		if current_stamp := os.read_file(stamp_path) {
			if current_stamp == expected_stamp {
				if b.load_cached_called_fn_names(cache_dir, cache_name) {
					if os.getenv('V2VERBOSE') != '' {
						println('[*] Reusing ${obj_path}')
					}
					return obj_path
				}
			}
		}
	}
	if b.used_import_vh_for_parse {
		if os.exists(obj_path) && os.exists(stamp_path) {
			if b.load_cached_called_fn_names(cache_dir, cache_name) {
				return obj_path
			}
			return error('missing cached ${cache_name} call metadata for .vh parse')
		}
		return error('missing cached ${cache_name} object for .vh parse')
	}

	stats_enabled := b.cgen_builder_stats_enabled()
	mut stats_sw := time.new_stopwatch()
	mut stage_start := stats_sw.elapsed()
	cached_called_before := b.cached_called_fn_names.clone()
	stage_start = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start,
		'called_before_clone')
	mut module_source := b.gen_cleanc_source_for_cache(module_names, cache_name, use_markused)
	stage_start = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start,
		'source')
	if module_source == '' {
		return error('failed to generate C source for ${cache_name}')
	}
	os.write_file(c_path, module_source)!
	stage_start = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start,
		'write_c')

	compile_cmd := '${cc} ${cc_flags} -w -Wno-incompatible-function-pointer-types -c "${c_path}" -o "${obj_path}"${error_limit_flag}'
	run_cc_cmd_or_exit(compile_cmd, 'C compilation', b.pref.show_cc)
	stage_start =
		b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start, 'cc')
	b.write_cached_called_fn_names(cache_dir, cache_name, cached_called_before)
	os.write_file(stamp_path, expected_stamp)!
	_ = b.mark_cgen_builder_step(stats_enabled, cache_name, mut stats_sw, stage_start, 'metadata')
	return obj_path
}

fn (mut b Builder) ensure_cached_virtual_module_object(cache_dir string, groups []CachedVirtualModule, dependency_cache_names []string, cc string, cc_flags string, cc_link_flags string, error_limit_flag string, use_markused bool) !string {
	obj_path := cache_path_join(cache_dir, '${virtuals_cache_name}.o')
	stamp_path := cache_path_join(cache_dir, '${virtuals_cache_name}.stamp')
	c_path := cache_path_join(cache_dir, '${virtuals_cache_name}.c')
	expected_stamp := b.cache_stamp_for_virtual_modules(groups, dependency_cache_names, cc,
		cc_flags, cc_link_flags, use_markused)
	if os.exists(obj_path) && os.exists(stamp_path) {
		if current_stamp := os.read_file(stamp_path) {
			if current_stamp == expected_stamp {
				if b.load_cached_called_fn_names(cache_dir, virtuals_cache_name) {
					if os.getenv('V2VERBOSE') != '' {
						println('[*] Reusing ${obj_path}')
					}
					return obj_path
				}
			}
		}
	}
	if b.used_virtual_vh_for_parse {
		if os.exists(obj_path) && os.exists(stamp_path) {
			if b.load_cached_called_fn_names(cache_dir, virtuals_cache_name) {
				return obj_path
			}
			return error('missing cached ${virtuals_cache_name} call metadata for .vh parse')
		}
		return error('missing cached ${virtuals_cache_name} object for .vh parse')
	}

	emit_files := virtual_module_source_files(groups)
	stats_enabled := b.cgen_builder_stats_enabled()
	mut stats_sw := time.new_stopwatch()
	mut stage_start := stats_sw.elapsed()
	cached_called_before := b.cached_called_fn_names.clone()
	stage_start = b.mark_cgen_builder_step(stats_enabled, virtuals_cache_name, mut stats_sw,
		stage_start, 'called_before_clone')
	mut module_source := b.gen_cleanc_source_for_cache_files(['main'], emit_files,
		virtuals_cache_name, use_markused)
	stage_start = b.mark_cgen_builder_step(stats_enabled, virtuals_cache_name, mut stats_sw,
		stage_start, 'source')
	if module_source == '' {
		return error('failed to generate C source for ${virtuals_cache_name}')
	}
	os.write_file(c_path, module_source)!
	stage_start = b.mark_cgen_builder_step(stats_enabled, virtuals_cache_name, mut stats_sw,
		stage_start, 'write_c')

	compile_cmd := '${cc} ${cc_flags} -w -Wno-incompatible-function-pointer-types -c "${c_path}" -o "${obj_path}"${error_limit_flag}'
	run_cc_cmd_or_exit(compile_cmd, 'C compilation', b.pref.show_cc)
	stage_start = b.mark_cgen_builder_step(stats_enabled, virtuals_cache_name, mut stats_sw,
		stage_start, 'cc')
	b.write_cached_called_fn_names(cache_dir, virtuals_cache_name, cached_called_before)
	os.write_file(stamp_path, expected_stamp)!
	_ = b.mark_cgen_builder_step(stats_enabled, virtuals_cache_name, mut stats_sw, stage_start,
		'metadata')
	return obj_path
}

// flat_file_module_name returns the normalized module name of the i-th flat
// file, mirroring `ast_file_module_name` for the flat-AST path: the raw module
// string with `.` replaced by `_`, defaulting to `main`. Used by the cleanc
// cached-core enumeration helpers when `b.files` has been dropped in favour of
// the post-transform FlatAst.
fn (b &Builder) flat_file_module_name(i int) string {
	mod := b.flat.string_at(b.flat.files[i].mod_idx)
	if mod == '' {
		return 'main'
	}
	return mod.replace('.', '_')
}

// uses_flat_module_enumeration reports whether module/file enumeration must run
// against `b.flat` instead of `b.files`. In flat-codegen mode the transformer
// drops `b.files` after producing the post-transform FlatAst, so the cleanc
// cache helpers source their module/file metadata from the flat cursors.
fn (b &Builder) uses_flat_module_enumeration() bool {
	return b.files.len == 0 && b.flat.files.len > 0
}

// flat_scoped_to_modules returns a FlatAst whose file list is restricted to the
// given module set, reusing b.flat's node/edge/string arena (the arrays are
// shared, not deep-copied). The cleanc gen drives every emission pass off
// `flat.files`, so a restricted file list makes the whole gen see exactly the
// bundle's type-module files — matching the legacy gen, which filtered its input
// `gen_files` to `type_module_names`. This lets restricted cache bundles run on
// the flat gen with no per-file legacy rehydrate.
fn (b &Builder) flat_scoped_to_modules(module_names map[string]bool) ast.FlatAst {
	mut files := []ast.FlatFile{cap: b.flat.files.len}
	for i in 0 .. b.flat.files.len {
		if b.flat_file_module_name(i) in module_names {
			files << b.flat.files[i]
		}
	}
	return ast.FlatAst{
		files:   files
		nodes:   b.flat.nodes
		edges:   b.flat.edges
		strings: b.flat.strings
	}
}

fn (b &Builder) has_module(module_name string) bool {
	if b.uses_flat_module_enumeration() {
		for i in 0 .. b.flat.files.len {
			if b.flat_file_module_name(i) == module_name {
				return true
			}
		}
		return false
	}
	for file in b.files {
		if ast_file_module_name(file) == module_name {
			return true
		}
	}
	return false
}

fn (b &Builder) collect_modules_excluding(excluded []string) []string {
	mut excluded_set := map[string]bool{}
	for module_name in excluded {
		excluded_set[module_name] = true
	}
	mut modules_set := map[string]bool{}
	if b.uses_flat_module_enumeration() {
		for i in 0 .. b.flat.files.len {
			module_name := b.flat_file_module_name(i)
			if module_name in excluded_set {
				continue
			}
			modules_set[module_name] = true
		}
	} else {
		for file in b.files {
			module_name := ast_file_module_name(file)
			if module_name in excluded_set {
				continue
			}
			modules_set[module_name] = true
		}
	}
	mut modules := modules_set.keys()
	modules.sort()
	return modules
}

fn (b &Builder) user_entry_module_names() []string {
	mut entry_files := map[string]bool{}
	for file in b.user_entry_stamp_files() {
		entry_files[os.norm_path(file)] = true
		entry_files[os.norm_path(os.abs_path(file))] = true
	}
	mut modules_set := map[string]bool{}
	if b.uses_flat_module_enumeration() {
		for i in 0 .. b.flat.files.len {
			name := b.flat.file_name(b.flat.files[i])
			if name == '' || name.ends_with('.vh') {
				continue
			}
			norm_name := os.norm_path(name)
			abs_name := os.norm_path(os.abs_path(name))
			if norm_name !in entry_files && abs_name !in entry_files {
				continue
			}
			module_name := b.flat_file_module_name(i)
			if module_name.len > 0 {
				modules_set[module_name] = true
			}
		}
	} else {
		for file in b.files {
			if file.name == '' || file.name.ends_with('.vh') {
				continue
			}
			norm_name := os.norm_path(file.name)
			abs_name := os.norm_path(os.abs_path(file.name))
			if norm_name !in entry_files && abs_name !in entry_files {
				continue
			}
			module_name := ast_file_module_name(file)
			if module_name.len > 0 {
				modules_set[module_name] = true
			}
		}
	}
	mut modules := modules_set.keys()
	modules.sort()
	return modules
}

fn (b &Builder) print_cached_bundle_modules(cache_name string, module_names []string) {
	if module_names.len == 0 {
		return
	}
	stats_enabled := b.pref != unsafe { nil } && b.pref.stats
	show_cc_enabled := b.pref != unsafe { nil } && b.pref.show_cc
	if !stats_enabled && !show_cc_enabled && os.getenv('V2_TRACE_CACHE') == '' {
		return
	}
	if stats_enabled {
		println(' * Cached ${cache_name} modules: ${module_names.len}')
		for module_name in module_names {
			println('   [cache ${cache_name}] ${module_name}')
		}
		return
	}
	println('[*] Cached ${cache_name} modules: ${module_names.join(', ')}')
}

fn ast_file_module_name(file ast.File) string {
	for stmt in file.stmts {
		if stmt is ast.ModuleStmt {
			return stmt.name.replace('.', '_')
		}
	}
	return 'main'
}

fn normalize_target_os_name(target_os string) string {
	return match target_os.to_lower() {
		'darwin', 'mac' { 'macos' }
		else { target_os.to_lower() }
	}
}

fn is_windows_x64_native_target(arch pref.Arch, target_os string) bool {
	return arch == .x64 && normalize_target_os_name(target_os) == 'windows'
}

fn is_linux_x64_native_target(arch pref.Arch, target_os string) bool {
	return arch == .x64 && normalize_target_os_name(target_os) == 'linux'
}

fn is_macos_x64_native_target(arch pref.Arch, target_os string) bool {
	return arch == .x64 && is_macos_native_target(target_os)
}

fn eprint_native_x64_link_error(message string) {
	if message.starts_with('x64: unsupported backend feature: ') {
		eprintln(message)
		eprintln(x64.x64_backend_limitation_hint)
		return
	}
	eprintln('Link failed:')
	eprintln(message)
}

fn (b &Builder) uses_minimal_windows_x64_runtime() bool {
	arch := b.pref.get_effective_arch()
	return b.pref.backend == .x64 && is_windows_x64_native_target(arch, b.pref.target_os_or_host())
}

fn (b &Builder) uses_minimal_linux_x64_runtime() bool {
	arch := b.pref.get_effective_arch()
	return b.pref.backend == .x64 && is_linux_x64_native_target(arch, b.pref.target_os_or_host())
}

fn (b &Builder) uses_minimal_x64_runtime() bool {
	return b.uses_minimal_windows_x64_runtime() || b.uses_minimal_linux_x64_runtime()
}

fn linux_x64_tiny_strict_enabled() bool {
	return os.getenv('V2_X64_LINUX_TINY') != ''
}

fn (b &Builder) uses_minimal_linux_x64_runtime_roots() bool {
	return b.uses_minimal_linux_x64_runtime() && linux_x64_tiny_strict_enabled()
}

fn (b &Builder) uses_minimal_x64_runtime_roots() bool {
	return b.uses_minimal_windows_x64_runtime() || b.uses_minimal_linux_x64_runtime_roots()
}

fn (b &Builder) uses_macos_x64_tiny_object(arch pref.Arch) bool {
	return b.pref.backend == .x64 && is_macos_x64_native_target(arch, b.pref.target_os_or_host())
		&& b.pref.macos_tiny
}

fn native_link_flags_suffix(link_flags string) string {
	trimmed := link_flags.trim_space()
	if trimmed == '' {
		return ''
	}
	return ' ${trimmed}'
}

fn macos_native_ld_link_flags(link_flags string) string {
	mut normalized := []string{}
	tokens := link_flags.fields()
	mut i := 0
	for i < tokens.len {
		tok := tokens[i]
		if tok.starts_with('-Wl,') {
			for linker_arg in tok['-Wl,'.len..].split(',') {
				if linker_arg != '' {
					normalized << linker_arg
				}
			}
			i++
			continue
		}
		if tok == '-Xlinker' {
			if i + 1 < tokens.len {
				i++
				normalized << tokens[i]
			}
			i++
			continue
		}
		normalized << tok
		i++
	}
	return normalized.join(' ')
}

fn native_driver_flag_is_dual_use(tok string) bool {
	return tok == '-pthread' || tok == '-fopenmp' || tok.starts_with('-fopenmp=')
}

fn macos_native_ld_unsupported_driver_link_flags(link_flags string) []string {
	mut unsupported := []string{}
	for tok in link_flags.fields() {
		if native_driver_flag_is_dual_use(tok) {
			unsupported << tok
		}
	}
	return unsupported
}

fn validate_macos_native_ld_link_flags(link_flags string) ! {
	unsupported := macos_native_ld_unsupported_driver_link_flags(link_flags)
	if unsupported.len > 0 {
		return error('x64: unsupported backend feature: macOS native ld cannot consume driver linker flags: ${unsupported.join(' ')}')
	}
}

fn native_linux_tiny_allows_system_lib(lib string) bool {
	return lib in ['pthread', 'm', 'dl', 'c']
}

fn native_internal_link_flags_allow_builtin_linux_tiny(link_flags string) bool {
	tokens := link_flags.trim_space().fields()
	mut i := 0
	for i < tokens.len {
		tok := tokens[i]
		if tok == '-l' {
			if i + 1 >= tokens.len {
				return false
			}
			i++
			if !native_linux_tiny_allows_system_lib(tokens[i]) {
				return false
			}
		} else if tok.starts_with('-l') {
			if !native_linux_tiny_allows_system_lib(tok['-l'.len..]) {
				return false
			}
		} else {
			return false
		}
		i++
	}
	return true
}

fn native_link_flags_allow_builtin_linux_tiny(link_flags string, user_link_flags string) bool {
	return user_link_flags.trim_space() == ''
		&& native_internal_link_flags_allow_builtin_linux_tiny(link_flags)
}

fn (b &Builder) native_link_flags_from_sources() string {
	_, directive_link_flags := split_compile_and_link_flags(b.collect_cflags_from_sources())
	return directive_link_flags.trim_space()
}

fn (b &Builder) native_compile_and_link_flags_from_sources() (string, string) {
	directive_compile_flags, directive_link_flags :=
		split_compile_and_link_flags(b.collect_cflags_from_sources())
	return directive_compile_flags.trim_space(), directive_link_flags.trim_space()
}

fn (b &Builder) native_user_compile_and_link_flags_from_sources() (string, string) {
	directive_compile_flags, directive_link_flags :=
		split_compile_and_link_flags(b.collect_user_cflags_from_sources())
	return directive_compile_flags.trim_space(), directive_link_flags.trim_space()
}

struct NativeExternalLinkInputs {
	link_flags   string
	source_files []string
	object_files []string
}

fn native_external_source_clean_token(tok string) string {
	return tok.trim('"').trim("'")
}

fn native_external_source_is_supported(tok string) bool {
	lower := native_external_source_clean_token(tok).to_lower()
	return lower.ends_with('.c') || lower.ends_with('.m')
}

fn native_external_source_is_unsupported(tok string) bool {
	lower := native_external_source_clean_token(tok).to_lower()
	return lower.ends_with('.cc') || lower.ends_with('.cpp') || lower.ends_with('.cxx')
		|| lower.ends_with('.mm')
}

fn native_external_source_unsupported_message(tok string) string {
	clean := native_external_source_clean_token(tok)
	if clean.to_lower().ends_with('.mm') {
		return 'x64: unsupported backend feature: Objective-C++ #flag source `${clean}`'
	}
	return 'x64: unsupported backend feature: C++ #flag source `${clean}`'
}

fn native_external_source_object_file(output_binary string, source_index int) string {
	output_name := if output_binary == '' { 'out' } else { os.file_name(output_binary) }
	clean_name := output_name.replace('/', '_').replace('\\', '_').replace('.', '_')
	return os.join_path(os.vtmp_dir(), 'v2_native_${os.getpid()}_${clean_name}_${source_index}.o')
}

fn native_external_link_inputs(link_flags string, output_binary string) !NativeExternalLinkInputs {
	mut rewritten := []string{}
	mut source_files := []string{}
	mut object_files := []string{}
	for tok in link_flags.fields() {
		clean := native_external_source_clean_token(tok)
		if native_external_source_is_unsupported(clean) {
			return error(native_external_source_unsupported_message(clean))
		}
		if native_external_source_is_supported(clean) {
			if tok.contains('"') || tok.contains("'") {
				return error('x64: unsupported backend feature: quoted #flag source path `${tok}`')
			}
			obj_file := native_external_source_object_file(output_binary, source_files.len)
			source_files << clean
			object_files << obj_file
			rewritten << os.quoted_path(obj_file)
			continue
		}
		rewritten << tok
	}
	return NativeExternalLinkInputs{
		link_flags:   rewritten.join(' ')
		source_files: source_files
		object_files: object_files
	}
}

fn native_external_source_compile_command(cc string, source_file string, object_file string, compile_flags string, sdk_path string, arch_flag string, target_os string) string {
	mut parts := [cc, '-c']
	if is_macos_native_target(target_os) {
		if sdk_path != '' {
			parts << '-isysroot'
			parts << os.quoted_path(sdk_path)
		}
		if arch_flag != '' {
			parts << '-arch'
			parts << arch_flag
		}
	}
	if compile_flags != '' {
		parts << compile_flags
	}
	parts << os.quoted_path(source_file)
	parts << '-o'
	parts << os.quoted_path(object_file)
	return parts.join(' ')
}

fn (b &Builder) native_external_source_compiler(target_os string) string {
	if b.pref.ccompiler.len > 0 {
		return b.pref.ccompiler
	}
	v2cc := (os.getenv_opt('V2CC') or { '' }).trim_space()
	if v2cc != '' {
		return v2cc
	}
	if is_macos_native_target(target_os) {
		return 'cc'
	}
	return configured_cc(b.pref.vroot)
}

fn (b &Builder) native_linux_hosted_link_compiler() string {
	if b.pref.ccompiler.len > 0 {
		return b.pref.ccompiler
	}
	v2cc := (os.getenv_opt('V2CC') or { '' }).trim_space()
	if v2cc != '' {
		return v2cc
	}
	return 'cc'
}

fn (b &Builder) compile_native_external_sources(inputs NativeExternalLinkInputs, compile_flags string, target_os string, sdk_path string, arch_flag string) ! {
	if inputs.source_files.len == 0 {
		return
	}
	cc := b.native_external_source_compiler(target_os)
	for i, source_file in inputs.source_files {
		cmd := native_external_source_compile_command(cc, source_file, inputs.object_files[i],
			compile_flags, sdk_path, arch_flag, target_os)
		if b.pref.show_cc {
			println(cmd)
		}
		res := os.execute(cmd)
		if res.exit_code != 0 {
			return error('native external source compilation failed:\n${cmd}\n${res.output}')
		}
	}
}

fn cleanup_native_external_objects(inputs NativeExternalLinkInputs) {
	for obj_file in inputs.object_files {
		os.rm(obj_file) or {}
	}
}

fn macos_native_link_command(output_binary string, obj_file string, sdk_path string, arch_flag string, tiny_object bool, link_flags string) string {
	ld_link_flags := macos_native_ld_link_flags(link_flags)
	normal_link_cmd := 'ld -o ${os.quoted_path(output_binary)} ${os.quoted_path(obj_file)}${native_link_flags_suffix(ld_link_flags)} -lSystem -syslibroot ${os.quoted_path(sdk_path)} -e _main -arch ${arch_flag} -platform_version macos 11.0.0 11.0.0'
	if tiny_object {
		return '${normal_link_cmd} -dead_strip -x -S'
	}
	return normal_link_cmd
}

fn macos_sdk_path_from_xcrun_output(output string) !string {
	mut sdk_path := ''
	for raw_line in output.split_into_lines() {
		line := raw_line.trim(' \t\r')
		if line == '' {
			continue
		}
		if is_clean_macos_sdk_path_line(line) {
			sdk_path = line
		}
	}
	if sdk_path == '' {
		return error('could not find a clean macOS SDK path in xcrun output')
	}
	return sdk_path
}

fn is_clean_macos_sdk_path_line(path string) bool {
	if !os.is_abs_path(path) {
		return false
	}
	base := os.file_name(path)
	return base.starts_with('MacOSX') && base.ends_with('.sdk')
}

fn validate_macos_sdk_path_for_native_link(sdk_path string) ! {
	if !os.is_dir(sdk_path) {
		return error('macOS SDK path does not exist: ${sdk_path}')
	}
	libsystem_tbd := os.join_path(sdk_path, 'usr', 'lib', 'libSystem.tbd')
	libsystem_dylib := os.join_path(sdk_path, 'usr', 'lib', 'libSystem.dylib')
	if !os.exists(libsystem_tbd) && !os.exists(libsystem_dylib) {
		return error('macOS SDK path is missing usr/lib/libSystem.tbd or usr/lib/libSystem.dylib: ${sdk_path}')
	}
}

fn linux_native_link_command(cc string, output_binary string, obj_file string, link_flags string) string {
	return '${cc} ${os.quoted_path(obj_file)} -o ${os.quoted_path(output_binary)} -no-pie${native_link_flags_suffix(link_flags)}'
}

fn native_external_object_file(output_binary string, target_os string) string {
	if !is_macos_native_target(target_os) {
		return 'main.o'
	}
	output_path := if os.is_abs_path(output_binary) {
		output_binary
	} else {
		os.abs_path(output_binary)
	}
	output_dir := os.dir(output_path)
	output_name := os.file_name(output_path)
	if output_name == '' {
		return os.join_path(output_dir, '.v_native_${os.getpid()}.o')
	}
	return os.join_path(output_dir, '.${output_name}.${os.getpid()}.o')
}

fn (mut b Builder) prepare_macos_tiny_candidate_source_files() {
	b.macos_tiny_candidate_source_files = []ast.File{}
	b.macos_tiny_candidate_source_flat = ast.FlatAst{}
	if !b.uses_macos_x64_tiny_object(.x64) {
		return
	}
	if b.flat.files.len > 0 {
		b.macos_tiny_candidate_source_flat = b.flat
		return
	}
	b.macos_tiny_candidate_source_files = b.files.clone()
}

fn is_macos_native_target(target_os string) bool {
	return normalize_target_os_name(target_os) == 'macos'
}

fn native_x64_object_format_for_os(target_os string) x64.ObjectFormat {
	return match normalize_target_os_name(target_os) {
		'macos' { x64.ObjectFormat.macho }
		'windows' { x64.ObjectFormat.coff }
		else { x64.ObjectFormat.elf }
	}
}

fn native_x64_codegen_abi_for_os(target_os string) x64.X64Abi {
	return match normalize_target_os_name(target_os) {
		'windows' { x64.X64Abi.windows }
		else { x64.X64Abi.sysv }
	}
}

fn native_x64_lowering_abi_for_os(target_os string) abi.X64Abi {
	return match normalize_target_os_name(target_os) {
		'windows' { abi.X64Abi.windows }
		else { abi.X64Abi.sysv }
	}
}

fn native_x64_mir_unsupported_external_symbol_message(mir_mod &mir.Module, obj_format x64.ObjectFormat) ?string {
	for val in mir_mod.values {
		if val.kind != .func_ref {
			continue
		}
		if msg := x64.unsupported_external_symbol_message_for_name(obj_format, val.name,
			'needed while preparing native x64 output')
		{
			return msg
		}
	}
	return none
}

fn (b &Builder) native_backend_requires_ssa_optimization(arch pref.Arch) bool {
	return arch == .x64
}

fn flag_os_matches(cond string, target_os string) bool {
	current := normalize_target_os_name(target_os)
	return match cond.to_lower() {
		'darwin', 'macos', 'mac' { current == 'macos' || current == 'darwin' }
		'linux' { current == 'linux' }
		'windows' { current == 'windows' }
		'bsd' { current in ['macos', 'freebsd', 'openbsd', 'netbsd', 'dragonfly'] }
		'freebsd' { current == 'freebsd' }
		'openbsd' { current == 'openbsd' }
		'netbsd' { current == 'netbsd' }
		'dragonfly' { current == 'dragonfly' }
		'android' { current == 'android' }
		'termux' { current == 'termux' }
		'ios' { current == 'ios' }
		'solaris' { current == 'solaris' }
		'qnx' { current == 'qnx' }
		'serenity' { current == 'serenity' }
		'plan9' { current == 'plan9' }
		'vinix' { current == 'vinix' }
		'cross' { current == 'cross' }
		'none' { current == 'none' }
		else { false }
	}
}

fn flag_pref_matches(cond string, prefs &pref.Preferences) bool {
	if prefs == unsafe { nil } {
		return false
	}
	lower := cond.to_lower()
	if pref.comptime_flag_value(prefs, lower) {
		return true
	}
	return flag_os_matches(lower, prefs.target_os_or_host())
}

fn find_vmod_root_for_file(file_path string) string {
	mut dir := os.dir(file_path)
	for _ in 0 .. 12 {
		if os.exists(os.join_path(dir, 'v.mod')) {
			return dir
		}
		parent := os.dir(dir)
		if parent == dir || parent == '' {
			break
		}
		dir = parent
	}
	return os.dir(file_path)
}

fn resolve_flag_path(path string, file_dir string, vmod_root string) string {
	mut resolved := path.replace('@VMODROOT', vmod_root)
	if os.is_abs_path(resolved) {
		return resolved
	}
	// Resolve any relative path (including bare relative like 'r/qrcodegen')
	// relative to the source file's directory, matching V1 behavior
	return os.norm_path(os.join_path(file_dir, resolved))
}

fn expand_existing_path_macros(flag_value string) ?string {
	mut out := ''
	mut i := 0
	for i < flag_value.len {
		if flag_value[i] == `$` {
			remainder := flag_value[i..]
			mut literal := ''
			if remainder.starts_with(r'$when_first_existing') {
				literal = r'$when_first_existing'
			} else if remainder.starts_with(r'$first_existing') {
				literal = r'$first_existing'
			}
			if literal != '' {
				if remainder.len <= literal.len || remainder[literal.len] != `(` {
					out += flag_value[i].ascii_str()
					i++
					continue
				}
				params_part := remainder[literal.len + 1..]
				params := params_part.all_before(')')
				if params == params_part {
					return none
				}
				paths := params.replace(',', '\n').split_into_lines().map(it.trim('\t \'"'))
				mut found := ''
				for path in paths {
					if path != '' && os.exists(path) {
						found = path
						break
					}
				}
				if found == '' {
					return none
				}
				out += found
				i += literal.len + 1 + params.len + 1
				continue
			}
		}
		out += flag_value[i].ascii_str()
		i++
	}
	return out
}

fn normalize_flag_value_for_file(flag_value string, file_path string) string {
	file_dir := os.dir(os.real_path(file_path))
	vmod_root := find_vmod_root_for_file(file_path)
	expanded_flag_value := expand_existing_path_macros(flag_value) or { return '' }
	mut tokens := expanded_flag_value.fields()
	mut out := []string{}
	mut i := 0
	for i < tokens.len {
		tok := tokens[i]
		if tok in ['-I', '-L', '-F'] && i + 1 < tokens.len {
			out << tok
			out << resolve_flag_path(tokens[i + 1], file_dir, vmod_root)
			i += 2
			continue
		}
		if tok.starts_with('-I') && tok.len > 2 {
			out << '-I' + resolve_flag_path(tok[2..], file_dir, vmod_root)
			i++
			continue
		}
		if tok.starts_with('-L') && tok.len > 2 {
			out << '-L' + resolve_flag_path(tok[2..], file_dir, vmod_root)
			i++
			continue
		}
		if tok.starts_with('-F') && tok.len > 2 {
			out << '-F' + resolve_flag_path(tok[2..], file_dir, vmod_root)
			i++
			continue
		}
		if tok.contains('@VMODROOT') || tok.contains('@VEXEROOT') || tok.starts_with('./')
			|| tok.starts_with('../') || tok.ends_with('.c') || tok.ends_with('.m')
			|| tok.ends_with('.o') {
			out << resolve_flag_path(tok, file_dir, vmod_root)
			i++
			continue
		}
		out << tok
		i++
	}
	return out.join(' ')
}

fn parse_flag_directive_line(line string, file_path string, target_os string) ?string {
	return parse_flag_directive_line_with_context(line, file_path, target_os, unsafe {
		&pref.Preferences(nil)
	})
}

fn parse_flag_directive_line_with_pref(line string, file_path string, prefs &pref.Preferences) ?string {
	target_os := if prefs == unsafe { nil } { '' } else { prefs.target_os_or_host() }
	return parse_flag_directive_line_with_context(line, file_path, target_os, prefs)
}

fn parse_flag_directive_line_with_context(line string, file_path string, target_os string, prefs &pref.Preferences) ?string {
	trimmed := line.trim_space()
	if trimmed.starts_with('#pkgconfig') {
		if prefs != unsafe { nil } && prefs.is_cross_target() {
			return none
		}
		rest := trimmed['#pkgconfig'.len..].trim_space()
		return resolve_pkgconfig_directive_flags(rest)
	}
	if !trimmed.starts_with('#flag') {
		return none
	}
	mut rest := trimmed['#flag'.len..].trim_space()
	if rest == '' {
		return none
	}
	if comment_idx := rest.index('//') {
		rest = rest[..comment_idx].trim_space()
		if rest == '' {
			return none
		}
	}
	parts := rest.fields()
	if parts.len == 0 {
		return none
	}
	if !parts[0].starts_with('-') && !parts[0].starts_with('@') && parts.len > 1 {
		matches := if prefs == unsafe { nil } {
			flag_os_matches(parts[0], target_os)
		} else {
			flag_os_matches(parts[0], target_os) || flag_pref_matches(parts[0], prefs)
		}
		if !matches {
			return none
		}
		rest = rest[parts[0].len..].trim_space()
	}
	if rest == '' {
		return none
	}
	return normalize_flag_value_for_file(rest, file_path)
}

fn resolve_pkgconfig_directive_flags(value string) ?string {
	if value == '' {
		return none
	}
	args := if value.contains('--') {
		value.fields()
	} else {
		'--cflags --libs ${value}'.fields()
	}
	flags := pref.pkgconfig_result(args) or { return none }
	if flags == '' {
		return none
	}
	return flags
}

fn flag_references_missing_file(flag string, include_flags []string) bool {
	for tok in flag.fields() {
		clean := tok.trim('"').trim("'")
		if clean.len == 0 {
			continue
		}
		if clean.ends_with('.o') || clean.ends_with('.a') || clean.ends_with('.so')
			|| clean.ends_with('.dylib') || clean.ends_with('.m') || clean.ends_with('.c') {
			if os.is_abs_path(clean) || clean.starts_with('./') || clean.starts_with('../') {
				if !os.exists(clean) {
					// For .o files, try to build from corresponding .c file
					if clean.ends_with('.o') {
						c_file := clean[..clean.len - 2] + '.c'
						if os.exists(c_file) {
							inc_flags := include_flags.join(' ')
							compile_cmd := 'cc -c -w -O2 ${inc_flags} "${c_file}" -o "${clean}"'
							res := os.execute(compile_cmd)
							if res.exit_code == 0 {
								continue // successfully compiled, not missing
							}
						}
					}
					return true
				}
			}
		}
	}
	return false
}

fn (b &Builder) collect_cflags_from_sources() string {
	// Collect source file paths to scan.  When .vh headers were used for
	// parsing, b.files references the .vh summaries which lack #flag
	// directives.  Always include the original core module source files
	// so that directive flags (e.g. -I paths) are never lost.
	mut scan_paths := []string{}
	for file in b.files {
		if file.name != '' {
			scan_paths << file.name
		}
	}
	for ff in b.flat.files {
		name := b.flat.file_name(ff)
		if name != '' {
			scan_paths << name
		}
	}
	cflags_target_os := b.cflags_target_os_for_local_compile()
	if !b.pref.skip_builtin {
		target_os := cflags_target_os
		for module_path in core_cached_module_paths {
			vlib_path := b.pref.get_vlib_module_path(module_path)
			module_files := get_v_files_from_dir(vlib_path, b.pref.user_defines, target_os)
			for mf in module_files {
				scan_paths << mf
			}
		}
	}
	return b.collect_cflags_from_scan_paths(scan_paths)
}

fn (b &Builder) source_path_is_internal_vlib(path string) bool {
	vlib_root := os.real_path(os.join_path(b.pref.vroot, 'vlib')).replace('\\', '/').trim_right('/')
	real_path := os.real_path(path).replace('\\', '/')
	return real_path == vlib_root || real_path.starts_with('${vlib_root}/')
}

fn (b &Builder) collect_user_cflags_from_sources() string {
	mut scan_paths := []string{}
	for path in b.user_files {
		if path != '' {
			scan_paths << path
		}
	}
	for file in b.files {
		if file.name != '' && !b.source_path_is_internal_vlib(file.name) {
			scan_paths << file.name
		}
	}
	for ff in b.flat.files {
		name := b.flat.file_name(ff)
		if name != '' && !b.source_path_is_internal_vlib(name) {
			scan_paths << name
		}
	}
	return b.collect_cflags_from_scan_paths(scan_paths)
}

fn (b &Builder) collect_cflags_from_scan_paths(paths []string) string {
	mut flags := []string{}
	mut seen := map[string]bool{}
	mut scanned_files := map[string]bool{}
	mut scan_paths := paths.clone()
	cflags_target_os := b.cflags_target_os_for_local_compile()
	scan_paths.sort()
	for scan_path in scan_paths {
		if scan_path == '' || scan_path in scanned_files {
			continue
		}
		scanned_files[scan_path] = true
		lines := os.read_lines(scan_path) or { continue }
		// Track $if nesting to skip flags inside non-matching comptime blocks.
		// skip_depth > 0 means we are inside a non-matching $if block.
		// chain_matched[i] tracks whether the i-th enclosing $if chain has
		// already matched some branch (so subsequent $else / $else $if at the
		// same level should be skipped even if their cond would otherwise match).
		mut skip_depth := 0
		mut chain_matched := []bool{}
		for line in lines {
			trimmed := line.trim_space()
			// Strip a leading "} " so chained patterns like "} $else $if X {" parse
			// the same way as "$else $if X {" on their own line.
			rest := if trimmed.starts_with('} ') { trimmed[2..].trim_space() } else { trimmed }
			leading_close := rest != trimmed
			// $else $if cond { (a chain continuation)
			if rest.starts_with(r'$else $if ') {
				new_cond := rest[10..].trim_right('{ ').trim_space()
				if skip_depth > 1 {
					// nested skipping; just continue without touching outer state
					continue
				}
				cur := chain_matched.len - 1
				if cur < 0 {
					continue
				}
				if chain_matched[cur] {
					skip_depth = 1
				} else if comptime_cond_matches_with_context(new_cond, cflags_target_os, b.pref) {
					chain_matched[cur] = true
					skip_depth = 0
				} else {
					skip_depth = 1
				}
				continue
			}
			// plain $else { (chain terminator)
			if rest.starts_with(r'$else') {
				if skip_depth > 1 {
					continue
				}
				cur := chain_matched.len - 1
				if cur < 0 {
					continue
				}
				if chain_matched[cur] {
					skip_depth = 1
				} else {
					chain_matched[cur] = true
					skip_depth = 0
				}
				continue
			}
			// $if cond { (chain opener)
			if rest.starts_with(r'$if ') {
				cond := rest[4..].trim_right('{ ').trim_space()
				matched := comptime_cond_matches_with_context(cond, cflags_target_os, b.pref)
				chain_matched << matched
				if skip_depth > 0 {
					skip_depth++
				} else if !matched {
					skip_depth = 1
				}
				continue
			}
			// closing }
			if trimmed == '}' {
				if skip_depth > 0 {
					skip_depth--
				}
				if chain_matched.len > 0 {
					chain_matched.delete_last()
				}
				continue
			}
			// "} something" where the leading } closed a chain but the rest is
			// unrecognized: treat the } as a chain close.
			if leading_close && rest == '' {
				if skip_depth > 0 {
					skip_depth--
				}
				if chain_matched.len > 0 {
					chain_matched.delete_last()
				}
				continue
			}
			if skip_depth > 0 {
				continue
			}
			// Replace @VEXEROOT before parsing so path normalization sees absolute paths
			resolved_line := line.replace('@VEXEROOT', b.pref.vroot).replace('VEXEROOT',
				b.pref.vroot)
			mut flag := parse_flag_directive_line_with_context(resolved_line, scan_path,
				cflags_target_os, b.pref) or { continue }
			// Build include flags from already-collected flags for compiling missing .o files
			mut inc_flags := []string{}
			for f in flags {
				if f.starts_with('-I') {
					inc_flags << f
				}
			}
			if flag_references_missing_file(flag, inc_flags) {
				continue
			}
			if flag == '' || flag in seen {
				continue
			}
			seen[flag] = true
			flags << flag
		}
	}
	return flags.join(' ')
}

// split_compile_and_link_flags separates a flags string into compiler-only
// flags (for -c compilation) and linker-only flags (for the link step).
// Linker flags include: -l*, -L*, -Wl,*, -Xlinker, -framework, C source files
// and prebuilt object/library files. Minimal dual-use driver flags, plus -F
// framework search paths, are kept in both outputs. Source files from #flag
// directives must not be passed to
// per-module `-c -o module.o` cache compilations.
fn split_compile_and_link_flags(flags string) (string, string) {
	tokens := flags.fields()
	mut compile := []string{}
	mut link := []string{}
	mut i := 0
	for i < tokens.len {
		tok := tokens[i]
		if native_driver_flag_is_dual_use(tok) {
			compile << tok
			link << tok
		} else if tok == '-F' {
			compile << tok
			link << tok
			if i + 1 < tokens.len {
				i++
				compile << tokens[i]
				link << tokens[i]
			}
		} else if tok.starts_with('-F') {
			compile << tok
			link << tok
		} else if tok == '-Xlinker' {
			link << tok
			if i + 1 < tokens.len {
				i++
				link << tokens[i]
			}
		} else if tok == '-framework' {
			// -framework Name: two tokens, linker only
			link << tok
			if i + 1 < tokens.len {
				i++
				link << tokens[i]
			}
		} else if tok.starts_with('-Wl,') || tok.starts_with('-l') || tok.starts_with('-L') {
			link << tok
			// -L or -l alone (space-separated from its argument): grab the next token
			if (tok == '-L' || tok == '-l') && i + 1 < tokens.len {
				i++
				link << tokens[i]
			}
		} else if tok.ends_with('.c') || tok.ends_with('.cc') || tok.ends_with('.cpp')
			|| tok.ends_with('.cxx') || tok.ends_with('.m') || tok.ends_with('.mm')
			|| tok.ends_with('.o') || tok.ends_with('.obj') || tok.ends_with('.a')
			|| tok.ends_with('.so') || tok.ends_with('.dylib') {
			link << tok
		} else if tok == '-I' && i + 1 < tokens.len {
			// -I alone (space-separated from its argument): grab the next token
			compile << tok
			i++
			compile << tokens[i]
		} else {
			compile << tok
		}
		i++
	}
	return compile.join(' '), link.join(' ')
}

fn comptime_cond_matches(cond string, target_os string) bool {
	return comptime_cond_matches_with_context(cond, target_os, unsafe { &pref.Preferences(nil) })
}

fn comptime_cond_matches_with_pref(cond string, prefs &pref.Preferences) bool {
	target_os := if prefs == unsafe { nil } { '' } else { prefs.target_os_or_host() }
	return comptime_cond_matches_with_context(cond, target_os, prefs)
}

fn comptime_cond_matches_with_context(cond string, target_os string, prefs &pref.Preferences) bool {
	trimmed := cond.trim_space()
	if or_idx := top_level_bool_op_index(trimmed, '||') {
		left := trimmed[..or_idx].trim_space()
		right := trimmed[or_idx + 2..].trim_space()
		return comptime_cond_matches_with_context(left, target_os, prefs)
			|| comptime_cond_matches_with_context(right, target_os, prefs)
	}
	if and_idx := top_level_bool_op_index(trimmed, '&&') {
		left := trimmed[..and_idx].trim_space()
		right := trimmed[and_idx + 2..].trim_space()
		return comptime_cond_matches_with_context(left, target_os, prefs)
			&& comptime_cond_matches_with_context(right, target_os, prefs)
	}
	if trimmed.starts_with('!') {
		return !comptime_cond_matches_with_context(trimmed[1..], target_os, prefs)
	}
	if stripped := strip_outer_bool_parens(trimmed) {
		return comptime_cond_matches_with_context(stripped, target_os, prefs)
	}
	if optional_name := optional_user_ct_flag_name(trimmed) {
		if prefs == unsafe { nil } {
			return false
		}
		return pref.comptime_optional_flag_value(prefs, optional_name)
	}
	if pkg_name := pkgconfig_cond_name(trimmed) {
		if prefs != unsafe { nil } && prefs.is_cross_target() {
			return false
		}
		return pref.comptime_pkgconfig_value(pkg_name)
	}
	if prefs != unsafe { nil } {
		return flag_os_matches(trimmed, target_os) || flag_pref_matches(trimmed, prefs)
	}
	current := normalize_target_os_name(target_os)
	return match trimmed.to_lower() {
		'macos', 'darwin', 'mac' { current == 'macos' || current == 'darwin' }
		'linux' { current == 'linux' }
		'windows' { current == 'windows' }
		'bsd' { current in ['macos', 'freebsd', 'openbsd', 'netbsd', 'dragonfly'] }
		'freebsd' { current == 'freebsd' }
		'openbsd' { current == 'openbsd' }
		'netbsd' { current == 'netbsd' }
		'dragonfly' { current == 'dragonfly' }
		'android' { current == 'android' }
		'termux' { current == 'termux' }
		'ios' { current == 'ios' }
		'solaris' { current == 'solaris' }
		'qnx' { current == 'qnx' }
		'serenity' { current == 'serenity' }
		'plan9' { current == 'plan9' }
		'vinix' { current == 'vinix' }
		'cross' { current == 'cross' }
		'native' { false }
		'emscripten' { false }
		else { false } // unknown user-defined flags default to false
	}
}

fn pkgconfig_cond_name(cond string) ?string {
	trimmed := cond.trim_space()
	if !trimmed.starts_with(r'$pkgconfig(') || !trimmed.ends_with(')') {
		return none
	}
	arg := trimmed[r'$pkgconfig('.len..trimmed.len - 1].trim_space()
	if arg.len < 2 {
		return none
	}
	quote := arg[0]
	if (quote != `'` && quote != `"`) || arg[arg.len - 1] != quote {
		return none
	}
	return arg[1..arg.len - 1]
}

fn optional_user_ct_flag_name(cond string) ?string {
	trimmed := cond.trim_space()
	if !trimmed.ends_with('?') {
		return none
	}
	name := trimmed[..trimmed.len - 1].trim_space()
	if name == '' {
		return none
	}
	return name
}

fn top_level_bool_op_index(expr string, op string) ?int {
	mut depth := 0
	mut i := 0
	for i < expr.len {
		ch := expr[i]
		if ch == `(` {
			depth++
		} else if ch == `)` {
			if depth > 0 {
				depth--
			}
		} else if depth == 0 && i + op.len <= expr.len && expr[i..i + op.len] == op {
			return i
		}
		i++
	}
	return none
}

fn strip_outer_bool_parens(expr string) ?string {
	if expr.len < 2 || expr[0] != `(` || expr[expr.len - 1] != `)` {
		return none
	}
	mut depth := 0
	for i, ch in expr {
		if ch == `(` {
			depth++
		} else if ch == `)` {
			depth--
			if depth == 0 && i < expr.len - 1 {
				return none
			}
		}
	}
	if depth == 0 {
		return expr[1..expr.len - 1].trim_space()
	}
	return none
}

fn default_cc(vroot string) string {
	// Try to use tcc by default, like v1 does.
	tcc_path := os.join_path(vroot, 'thirdparty', 'tcc', 'tcc.exe')
	if os.exists(tcc_path) {
		return tcc_path
	}
	return 'cc'
}

// fast_relink_output_is_generation_only mirrors gen_cleanc()'s generation-only
// decision: a `.c` output, a target we cannot compile locally, or a shared lib.
// Such a request must go through normal C generation, never the pre-parse relink
// (is_cmd_v2_self_build() keys only on the input file, so the relink path would
// otherwise link an executable into e.g. foo.c). Extracted so the decision is
// unit-testable without a warm object cache.
fn (b &Builder) fast_relink_output_is_generation_only(output_name string) bool {
	return output_name.ends_with('.c') || !b.can_compile_cleanc_locally() || b.pref.is_shared_lib
}

// preparse_flag_fingerprint captures the flag-affecting build inputs that are
// knowable WITHOUT parsing the sources: the C compiler choice (-cc / V2CC /
// default), prod/shared mode, and the env CFLAGS (V2CFLAGS). It is recorded in
// main.stamp and re-checked by the pre-parse fast relink so a changed compiler or
// CFLAGS environment invalidates a relink even when every source file is
// unchanged. Source-derived `#flag` directives are intentionally excluded — they
// change only when a source file changes, which the stamp freshness checks catch.
fn (b &Builder) preparse_flag_fingerprint() string {
	cc := if b.pref.ccompiler.len > 0 { b.pref.ccompiler } else { configured_cc(b.pref.vroot) }
	return 'cc=${cc}\x01ccpref=${b.pref.ccompiler}\x01prod=${b.pref.is_prod}\x01shared=${b.pref.is_shared_lib}\x01env=${configured_cflags()}'
}

fn configured_cc(vroot string) string {
	cc := (os.getenv_opt('V2CC') or { '' }).trim_space()
	if cc != '' {
		return cc
	}
	return default_cc(vroot)
}

fn configured_cflags() string {
	return (os.getenv_opt('V2CFLAGS') or { '' }).trim_space()
}

fn tcc_flags(cc string, vroot string) string {
	if !cc.contains('tcc') {
		return ''
	}
	tcc_dir := os.join_path(vroot, 'thirdparty', 'tcc')
	return '-I "${os.join_path(tcc_dir, 'lib', 'include')}" -L "${os.join_path(tcc_dir, 'lib')}"'
}

fn cflags_need_objc_mode(flags string) bool {
	lower_flags := flags.to_lower()
	for tok in lower_flags.fields() {
		clean := tok.trim('"\'')
		if clean.ends_with('.m') || clean.ends_with('.mm') {
			return true
		}
	}
	return lower_flags.contains('-framework cocoa') || lower_flags.contains('-framework appkit')
		|| lower_flags.contains('-framework foundation') || lower_flags.contains('-framework uikit')
		|| lower_flags.contains('-framework metal') || lower_flags.contains('-framework metalkit')
		|| lower_flags.contains('-framework quartzcore')
}

fn cc_recompile_flags_from_cmd(cmd string) string {
	parts := cmd.fields()
	mut flags := []string{}
	mut i := 1 // skip compiler
	for i < parts.len {
		p := parts[i]
		if p == '-o' {
			i += 2
			continue
		}
		if p == '-x' {
			if i + 1 < parts.len && parts[i + 1] != 'none' {
				flags << p
				flags << parts[i + 1]
			}
			i += 2
			continue
		}
		if p in ['-I', '-D', '-U', '-F', '-include', '-isystem', '-idirafter'] {
			flags << p
			if i + 1 < parts.len {
				i++
				flags << parts[i]
			}
			i++
			continue
		}
		if p.starts_with('-I') || p.starts_with('-D') || p.starts_with('-U') || p.starts_with('-F')
			|| p.starts_with('-std=') || p.starts_with('-W') || p.starts_with('-f')
			|| p.starts_with('-m') || p == '-pthread' {
			flags << p
		}
		i++
	}
	return flags.join(' ')
}

// run_cc_cmd_or_exit runs a C compiler command, falling back from tcc to cc
// if needed. Returns true if tcc fell back to cc.
fn run_cc_cmd_or_exit(cmd string, stage string, show_cc bool) bool {
	if show_cc {
		println(cmd)
	} else if os.getenv('V2VERBOSE') != '' {
		dump(cmd)
	}
	result := os.execute(cmd)
	if result.exit_code != 0 {
		// If tcc failed, fall back to cc.
		// Check only the compiler binary (before the first space), not the full
		// command string which contains tcc in include/library flag paths.
		cc_binary := cmd.all_before(' ')
		if cc_binary.contains('tcc') {
			eprintln('Failed to compile with tcc, falling back to cc')
			eprintln('tcc cmd: ${cmd}')
			eprintln(result.output)
			// Replace TCC binary with cc and strip TCC-specific include/lib
			// paths. TCC's tgmath.h conflicts with macOS system headers,
			// causing SIMD ambiguity errors in MetalKit when compiling as
			// Objective-C.
			mut fallback_cmd := cmd.replace_once(cc_binary, 'cc')
			tcc_dir := cc_binary.all_before_last('/tcc')
			if tcc_dir.len > 0 {
				// Remove -I and -L flags pointing into the TCC directory.
				mut parts := fallback_cmd.fields()
				mut filtered := []string{cap: parts.len}
				mut i2 := 0
				for i2 < parts.len {
					p := parts[i2]
					if (p == '-I' || p == '-L') && i2 + 1 < parts.len
						&& parts[i2 + 1].contains('tcc') {
						i2 += 2
						continue
					}
					if (p.starts_with('-I') || p.starts_with('-L')) && p.contains('tcc') {
						i2++
						continue
					}
					filtered << p
					i2++
				}
				fallback_cmd = filtered.join(' ')
			}
			// cc cannot read .o files produced by tcc on macOS arm64. Recompile
			// any cached .o files referenced in the command from their .c siblings
			// using cc before retrying the link.
			recompile_flags := cc_recompile_flags_from_cmd(fallback_cmd)
			for tok in fallback_cmd.fields() {
				clean_tok := tok.trim('"')
				if !clean_tok.ends_with('.o') {
					continue
				}
				stem := clean_tok.all_before_last('.o')
				mut c_sibling := stem + '.c'
				if !os.exists(c_sibling) && stem.ends_with('.main') {
					c_sibling = stem.all_before_last('.main') + '.c'
				}
				if !os.exists(c_sibling) {
					continue
				}
				recompile_cmd := 'cc ${recompile_flags} -w -Wno-incompatible-function-pointer-types -c "${c_sibling}" -o "${clean_tok}"'
				if show_cc {
					println(recompile_cmd)
				}
				rr := os.execute(recompile_cmd)
				if rr.exit_code != 0 {
					eprintln('cc recompile failed for ${c_sibling}:')
					eprintln(rr.output)
				}
				// Invalidate stamp so future builds rebuild from .c too.
				stamp_path := stem + '.stamp'
				if os.exists(stamp_path) {
					os.rm(stamp_path) or {}
				}
			}
			run_cc_cmd_or_exit(fallback_cmd, stage, show_cc)
			return true
		}
		eprintln('${stage} failed:')
		lines := result.output.split_into_lines()
		limit := if lines.len < 50 { lines.len } else { 50 }
		for line in lines[..limit] {
			eprintln(line)
		}
		mut error_count := 0
		mut warning_count := 0
		for line in lines {
			if line.contains(': error:') || line.contains(': fatal error:') {
				error_count += 1
			} else if line.contains(': warning:') {
				warning_count += 1
			}
		}
		if stage == 'C compilation' {
			eprintln('Total: ${warning_count} warnings and ${error_count} errors')
		}
		exit(1)
	}
	return false
}

fn native_graph_stage_title(label string, title string) string {
	if label == '' {
		return title
	}
	return '${label} ${title}'
}

const macos_tiny_candidate_graph_label = 'macOS Tiny Candidate'

fn (b &Builder) native_mir_build_sequential(label string) bool {
	return label == macos_tiny_candidate_graph_label || b.pref.no_parallel || b.pref.hot_fn.len > 0
}

fn (b &Builder) should_prune_native_backend_modules(arch pref.Arch) bool {
	return b.pref.single_backend || arch == .arm64
}

fn native_backend_module_file_fragment(backend_mod string) string {
	return match backend_mod {
		'eval' { '/vlib/v2_toberemoved/eval/' }
		else { '/vlib/v2_toberemoved/gen/${backend_mod}/' }
	}
}

fn (mut b Builder) build_native_mir_from_files(files []ast.File, arch pref.Arch, target_os string, minimal_runtime_roots bool, used_fn_keys map[string]bool, label string) mir.Module {
	mut mod := ssa.Module.new('main')
	if mod == unsafe { nil } {
		eprintln('error: native backend not available (compiled with stubbed ssa module)')
		eprintln('hint: use v2 compiled with v1 for native code generation')
		exit(1)
	}
	mut ssa_builder := ssa.Builder.new_with_env(mod, b.env)
	ssa_builder.guard_invalid_type_payloads = true
	ssa_builder.target_os = target_os
	ssa_builder.minimal_runtime_roots = minimal_runtime_roots
	ssa_builder.native_backend_bulk_zero_alloca = arch == .x64
	mut native_sw := time.new_stopwatch()

	// Pass markused data for dead code elimination. The ARM64 backend has its own
	// relocation-based dead stripping; using markused before SSA makes self-hosted
	// compiler builds fragile when the markused set is under-collected.
	if used_fn_keys.len > 0 && arch != .arm64 {
		ssa_builder.used_fn_keys = used_fn_keys.clone()
	}

	// Strip unused compiler backend modules before SSA. ARM64 already strips
	// these symbols after codegen, so avoid building MIR for them in the first place.
	if b.should_prune_native_backend_modules(arch) {
		all_backends := ['cleanc', 'eval', 'v', 'c', 'x64', 'arm64']
		own := match b.pref.backend {
			.arm64 { 'arm64' }
			.x64 { 'x64' }
			.cleanc { 'cleanc' }
			.v { 'v' }
			.c { 'c' }
			.eval { 'eval' }
		}

		for backend_mod in all_backends {
			if backend_mod != own {
				ssa_builder.skip_modules[backend_mod] = true
				ssa_builder.skip_module_file_fragments[backend_mod] =
					native_backend_module_file_fragment(backend_mod)
			}
		}
	}

	// In hot_fn mode, only build the target function body (skip all others)
	if b.pref.hot_fn.len > 0 {
		ssa_builder.hot_fn = b.pref.hot_fn
	}

	mut stage_start := native_sw.elapsed()
	// Route the whole SSA build through the cursor-native build_all_from_flat
	// on the post-transform b.flat (kept alive above). Sequential only
	// (build_all_from_flat builds fn bodies in-phase).
	//
	// b.flat is only POST-TRANSFORM when flat markused has routed transform
	// through transform_files_to_flat, or the direct native flat pipeline has
	// emitted transform output directly into FlatAst.
	build_from_flat := b.should_build_ssa_from_flat()
		|| (b.flat.files.len > 0 && b.native_flat_pipeline_enabled && label == '')
	if build_from_flat {
		ssa_builder.build_all_from_flat(&b.flat)
		// SSA has copied the program into MIR; keep the FlatAst lifetime out of
		// the later optimizer and machine-code generator working sets.
		b.flat = ast.FlatAst{}
	} else if b.native_mir_build_sequential(label) {
		ssa_builder.build_all(files)
	} else {
		// Phases 1-3 sequential, Phase 4 parallel, Phase 5 sequential
		ssa_builder.skip_fn_bodies = true
		ssa_builder.build_all(files)
		ssa_builder.skip_fn_bodies = false
		b.ssa_build_parallel(mut ssa_builder, files)
		ssa_builder.generate_vinit()
	}
	if arch == .arm64 {
		b.env.release_expr_type_cache_after_ssa()
	}
	print_time(native_graph_stage_title(label, 'SSA Build'),
		time.Duration(native_sw.elapsed() - stage_start))
	print_rss(native_graph_stage_title(label, 'after SSA build'))

	stage_start = native_sw.elapsed()
	ssa_optimization_required := b.native_backend_requires_ssa_optimization(arch)
	ssa_optimization_ran := !b.pref.no_optimize || ssa_optimization_required
	if ssa_optimization_required {
		if b.pref.no_optimize {
			eprintln('  opt: required for x64 backend (-O0 SSA is not supported yet)')
		}
		ssa_optimize.optimize(mut mod)
	} else if b.pref.no_optimize {
		eprintln('  opt: skipped (-O0)')
	} else {
		ssa_optimize.optimize(mut mod)
	}
	print_time(native_graph_stage_title(label, 'SSA Optimize'),
		time.Duration(native_sw.elapsed() - stage_start))
	print_rss(native_graph_stage_title(label, 'after SSA optimize'))
	$if debug {
		// Post-opt SSA verification is useful while debugging the optimizer, but it
		// is currently noisy enough to block normal self-host builds. Keep it
		// opt-in so `test_all.sh` and manual self-hosting can still complete.
		if ssa_optimization_ran && os.getenv('V2_VERIFY') != '' {
			ssa_optimize.verify_and_panic(mod, 'full optimization')
		}
	}

	// Post-optimization SSA dump for debugging
	dump_fn_name := os.getenv('V2_DUMP_OPT_SSA')
	if dump_fn_name.len > 0 {
		for func in mod.funcs {
			if func.name == dump_fn_name {
				eprintln('=== POST-OPT SSA DUMP: ${func.name} ===')
				eprintln('  params_len: ${func.params.len}')
				for pi, pid in func.params {
					pval := mod.values[pid]
					eprintln('  param[${pi}]: v${pid} kind=${pval.kind} name=`${pval.name}` typ=${pval.typ}')
				}
				for blk_id in func.blocks {
					blk := mod.blocks[blk_id]
					eprintln('  block ${blk_id} (${blk.name}):')
					for dval_id in blk.instrs {
						dval := mod.values[dval_id]
						if dval.kind != .instruction {
							continue
						}
						dinstr := mod.instrs[dval.index]
						mut ops_str := ''
						for oi, op_id in dinstr.operands {
							op_v := mod.values[op_id]
							ops_str += 'v${op_id}(${op_v.kind}:${op_v.name})'
							if oi < dinstr.operands.len - 1 {
								ops_str += ', '
							}
						}
						eprintln('    v${dval_id}: ${dinstr.op} [${ops_str}] typ=${dval.typ}')
					}
				}
				eprintln('=== END POST-OPT SSA DUMP ===')
			}
		}
	}

	stage_start = native_sw.elapsed()
	mut mir_mod := mir.lower_from_ssa(mod)
	print_time(native_graph_stage_title(label, 'MIR Lower'),
		time.Duration(native_sw.elapsed() - stage_start))
	mod.release_outer_arenas_after_mir_lower()
	print_rss(native_graph_stage_title(label, 'after MIR lower'))

	stage_start = native_sw.elapsed()
	if is_windows_x64_native_target(arch, target_os) {
		abi.lower_with_x64_abi(mut mir_mod, arch, native_x64_lowering_abi_for_os(target_os))
	} else {
		abi.lower(mut mir_mod, arch)
	}
	print_time(native_graph_stage_title(label, 'ABI Lower'),
		time.Duration(native_sw.elapsed() - stage_start))
	print_rss(native_graph_stage_title(label, 'after ABI lower'))

	if arch != .arm64 {
		stage_start = native_sw.elapsed()
		insel.select(mut mir_mod, arch)
		print_time(native_graph_stage_title(label, 'InsSel'),
			time.Duration(native_sw.elapsed() - stage_start))
		print_rss(native_graph_stage_title(label, 'after InsSel'))
	}
	return mir_mod
}

fn (mut b Builder) build_macos_tiny_candidate_mir(arch pref.Arch, target_os string) mir.Module {
	if b.macos_tiny_candidate_source_flat.files.len == 0
		&& b.macos_tiny_candidate_source_files.len == 0 {
		eprintln('internal error: macOS tiny candidate graph was not prepared')
		exit(1)
	}
	mut trans := transformer.Transformer.new_with_pref(b.env, b.pref)
	trans.set_file_set(b.file_set)
	trans.enable_macos_tiny_candidate_graph()
	opts := markused.MarkUsedOptions{
		minimal_runtime_roots: true
	}
	if b.macos_tiny_candidate_source_flat.files.len > 0 {
		candidate_flat :=
			trans.transform_flat_to_flat_direct(&b.macos_tiny_candidate_source_flat, [])
		candidate_used_fn_keys := markused.mark_used_flat_with_options(&candidate_flat, b.env, opts)
		old_flat := b.flat
		b.flat = candidate_flat
		candidate_mir := b.build_native_mir_from_files([], arch, target_os, true,
			candidate_used_fn_keys, macos_tiny_candidate_graph_label)
		b.flat = old_flat
		return candidate_mir
	}
	candidate_files := trans.transform_files(b.macos_tiny_candidate_source_files)
	candidate_used_fn_keys := markused.mark_used_with_options(candidate_files, b.env, opts)
	return b.build_native_mir_from_files(candidate_files, arch, target_os, true,
		candidate_used_fn_keys, macos_tiny_candidate_graph_label)
}

fn (mut b Builder) gen_native(backend_arch pref.Arch) {
	arch := if backend_arch == .auto { b.pref.get_effective_arch() } else { backend_arch }
	target_os := b.pref.target_os_or_host()
	native_compile_flags, native_link_flags := b.native_compile_and_link_flags_from_sources()
	_, native_user_link_flags := b.native_user_compile_and_link_flags_from_sources()
	mut native_external_inputs := NativeExternalLinkInputs{
		link_flags: native_link_flags
	}

	mut mir_mod := b.build_native_mir_from_files(b.files, arch, target_os,
		b.uses_minimal_x64_runtime_roots(), b.used_fn_keys, '')
	// The hosted SSA build has consumed b.files into `mir_mod`; the rest of the
	// normal native pipeline operates on MIR only. Drop the ~120MB legacy AST so
	// it can be reclaimed before codegen's working-set grows. The macOS tiny
	// candidate, when requested, uses its own saved source snapshot.
	b.files = []ast.File{}

	// Determine output binary name from the last user file
	output_binary := if b.pref.output_file != '' {
		b.pref.output_file
	} else if b.user_files.len > 0 {
		b.default_output_name()
	} else {
		'out'
	}

	if arch == .arm64 && is_macos_native_target(target_os) {
		// Use built-in linker for ARM64 macOS
		mut native_sw := time.new_stopwatch()
		stage_start := native_sw.elapsed()
		mut gen := arm64.Gen.new(&mir_mod)
		if b.pref.no_parallel {
			gen.gen()
		} else {
			b.gen_arm64_parallel(mut gen)
		}
		gen.release_scratch_after_gen()
		mir_mod.release_after_native_codegen()
		print_time('ARM64 Gen', time.Duration(native_sw.elapsed() - stage_start))

		if b.pref.hot_fn.len > 0 {
			// Hot code reloading: extract raw machine code for a single function
			code := gen.extract_function(b.pref.hot_fn)
			if code.len > 0 {
				os.write_file_array(output_binary, code) or { panic(err) }
				println('hot-fn: wrote ${code.len} bytes for "${b.pref.hot_fn}" to ${output_binary}')
			}
			return
		}

		gen.link_executable(output_binary)

		if b.pref.verbose {
			println('[*] Linked ${output_binary} (built-in linker)')
		}
	} else {
		// Generate object file and use external linker
		obj_file := native_external_object_file(output_binary, target_os)
		mut used_macos_tiny_object := false

		if arch == .arm64 {
			mut gen := arm64.Gen.new(&mir_mod)
			if b.pref.no_parallel {
				gen.gen()
			} else {
				b.gen_arm64_parallel(mut gen)
			}
			gen.release_scratch_after_gen()
			mir_mod.release_after_native_codegen()
			gen.write_file(obj_file)
		} else {
			obj_format := native_x64_object_format_for_os(target_os)
			codegen_abi := native_x64_codegen_abi_for_os(target_os)
			if msg := native_x64_mir_unsupported_external_symbol_message(&mir_mod, obj_format) {
				eprint_native_x64_link_error(msg)
				exit(1)
			}
			if is_windows_x64_native_target(arch, target_os) {
				mut windows_gen := x64.Gen.new_with_format_and_abi(&mir_mod, obj_format,
					codegen_abi)
				windows_gen.gen()
				windows_gen.link_executable(output_binary) or {
					eprint_native_x64_link_error(err.msg())
					exit(1)
				}
				if b.pref.verbose {
					println('[*] Linked ${output_binary} (built-in PE linker)')
				}
				return
			}
			if is_linux_x64_native_target(arch, target_os) {
				mut linux_gen := x64.Gen.new_with_format_and_abi(&mir_mod, obj_format, codegen_abi)
				linux_gen.gen()
				if native_link_flags_allow_builtin_linux_tiny(native_link_flags,
					native_user_link_flags)
				{
					if os.exists(output_binary) {
						os.rm(output_binary) or {}
					}
					linux_gen.link_linux_tiny_executable(output_binary) or {
						msg := err.msg()
						if linux_x64_tiny_strict_enabled()
							|| !msg.starts_with(x64.linux_tiny_not_eligible_prefix) {
							eprint_native_x64_link_error(msg)
							exit(1)
						}
					}
					if os.exists(output_binary) {
						if b.pref.verbose {
							println('[*] Linked ${output_binary} (built-in Linux tiny linker)')
						}
						return
					}
				}
				linux_gen.write_file(obj_file)
			} else if b.uses_macos_x64_tiny_object(arch) {
				if os.exists(obj_file) {
					os.rm(obj_file) or {}
				}
				if b.pref.verbose {
					println('[*] macOS tiny object candidate enabled')
				}
				mut candidate_mir := b.build_macos_tiny_candidate_mir(arch, target_os)
				mut candidate_gen := x64.Gen.new_with_format_and_abi(&candidate_mir, obj_format,
					codegen_abi)
				candidate_gen.gen()
				candidate_gen.write_macos_tiny_object(obj_file) or {
					msg := err.msg()
					if !msg.starts_with(x64.macos_tiny_not_eligible_prefix) {
						eprint_native_x64_link_error(msg)
						exit(1)
					}
					if b.pref.verbose {
						println('[*] macOS tiny object not eligible; falling back to normal Mach-O object: ${msg}')
					}
				}
				if os.exists(obj_file) {
					used_macos_tiny_object = true
				} else {
					if b.pref.verbose {
						println('[*] macOS tiny object fallback: writing normal Mach-O object')
					}
					mut macos_fallback_gen := x64.Gen.new_with_format_and_abi(&mir_mod, obj_format,
						codegen_abi)
					macos_fallback_gen.gen()
					macos_fallback_gen.write_file(obj_file)
				}
			} else {
				mut normal_x64_gen := x64.Gen.new_with_format_and_abi(&mir_mod, obj_format,
					codegen_abi)
				normal_x64_gen.gen()
				normal_x64_gen.write_file(obj_file)
			}
		}

		if b.pref.verbose {
			if used_macos_tiny_object {
				println('[*] Wrote ${obj_file} (macOS tiny candidate object)')
			} else {
				println('[*] Wrote ${obj_file}')
			}
		}

		// Link the object file into an executable
		if is_macos_native_target(target_os) {
			sdk_res := os.execute('xcrun -sdk macosx --show-sdk-path')
			if sdk_res.exit_code != 0 {
				eprintln('Link failed:')
				eprintln('failed to resolve macOS SDK path with xcrun:')
				eprintln(sdk_res.output)
				exit(1)
			}
			sdk_path := macos_sdk_path_from_xcrun_output(sdk_res.output) or {
				eprintln('Link failed:')
				eprintln(err.msg())
				eprintln('xcrun output:')
				eprintln(sdk_res.output)
				exit(1)
			}
			validate_macos_sdk_path_for_native_link(sdk_path) or {
				eprintln('Link failed:')
				eprintln(err.msg())
				exit(1)
			}
			arch_flag := if arch == .arm64 { 'arm64' } else { 'x86_64' }
			native_external_inputs = native_external_link_inputs(native_link_flags, output_binary) or {
				eprint_native_x64_link_error(err.msg())
				exit(1)
			}
			validate_macos_native_ld_link_flags(native_external_inputs.link_flags) or {
				eprint_native_x64_link_error(err.msg())
				exit(1)
			}
			b.compile_native_external_sources(native_external_inputs, native_compile_flags,
				target_os, sdk_path, arch_flag) or {
				cleanup_native_external_objects(native_external_inputs)
				eprint_native_x64_link_error(err.msg())
				exit(1)
			}
			normal_link_cmd := macos_native_link_command(output_binary, obj_file, sdk_path,
				arch_flag, false, native_external_inputs.link_flags)
			link_cmd := macos_native_link_command(output_binary, obj_file, sdk_path, arch_flag,
				used_macos_tiny_object, native_external_inputs.link_flags)
			mut link_result := os.execute(link_cmd)
			if link_result.exit_code != 0 && used_macos_tiny_object {
				if b.pref.verbose {
					println('[*] macOS tiny object link failed; retrying with normal Mach-O object')
					println('[*] macOS tiny object link exit code: ${link_result.exit_code}')
					println('[*] macOS tiny object link output:')
					if link_result.output.len > 0 {
						print(link_result.output)
						if !link_result.output.ends_with('\n') {
							println('')
						}
					} else {
						println('<empty>')
					}
				}
				if os.exists(output_binary) {
					os.rm(output_binary) or {}
				}
				obj_format := native_x64_object_format_for_os(target_os)
				codegen_abi := native_x64_codegen_abi_for_os(target_os)
				mut fallback_gen := x64.Gen.new_with_format_and_abi(&mir_mod, obj_format,
					codegen_abi)
				fallback_gen.gen()
				fallback_gen.write_file(obj_file)
				used_macos_tiny_object = false
				if b.pref.verbose {
					println('[*] Wrote ${obj_file} (normal Mach-O fallback after macOS tiny link failure)')
				}
				link_result = os.execute(normal_link_cmd)
			}
			if link_result.exit_code != 0 {
				eprintln('Link failed:')
				eprintln(link_result.output)
				cleanup_native_external_objects(native_external_inputs)
				exit(1)
			}
			if b.pref.verbose && used_macos_tiny_object {
				println('[*] Linked ${output_binary} (built-in macOS tiny object)')
			}
		} else {
			// Linux linking
			native_external_inputs = native_external_link_inputs(native_link_flags, output_binary) or {
				eprint_native_x64_link_error(err.msg())
				exit(1)
			}
			b.compile_native_external_sources(native_external_inputs, native_compile_flags,
				target_os, '', '') or {
				cleanup_native_external_objects(native_external_inputs)
				eprint_native_x64_link_error(err.msg())
				exit(1)
			}
			link_result := os.execute(linux_native_link_command(b.native_linux_hosted_link_compiler(),
				output_binary, obj_file, native_external_inputs.link_flags))
			if link_result.exit_code != 0 {
				eprintln('Link failed:')
				eprintln(link_result.output)
				cleanup_native_external_objects(native_external_inputs)
				exit(1)
			}
		}

		if b.pref.verbose {
			println('[*] Linked ${output_binary}')
		}

		// Clean up object file
		if !b.pref.keep_c {
			cleanup_native_external_objects(native_external_inputs)
			os.rm(obj_file) or {}
		}
	}
}

fn print_time(title string, time_d time.Duration) {
	println(' * ${title}: ${time_d.milliseconds()}ms')
}

fn (mut b Builder) update_parse_summary_counts() {
	mut parsed_full_files_n := 0
	mut parsed_vh_files_n := 0
	mut parsed_full_files := []string{}
	mut parsed_vh_files := []string{}
	for ff in b.flat.files {
		name := b.flat.file_name(ff)
		if name.ends_with('.vh') {
			parsed_vh_files_n++
			parsed_vh_files << name
		} else {
			parsed_full_files_n++
			parsed_full_files << name
		}
	}
	b.parsed_full_files_n = parsed_full_files_n
	b.parsed_vh_files_n = parsed_vh_files_n
	b.parsed_full_files = parsed_full_files
	b.parsed_vh_files = parsed_vh_files
	if b.pref.stats {
		b.entry_v_lines_n = count_v_lines_for_paths(b.user_files)
		b.parsed_v_lines_n = b.count_parsed_v_lines()
	} else {
		b.entry_v_lines_n = 0
		b.parsed_v_lines_n = 0
	}
}

fn (b &Builder) print_flat_ast_summary() {
	legacy_stats := ast.legacy_ast_stats(b.files)
	legacy_nodes := ast.count_legacy_nodes(b.files)
	flat_stats := b.flat.stats()
	mut mem_delta_pct := f64(0)
	if legacy_stats.bytes_estimate > 0 {
		mem_delta_pct = (f64(legacy_stats.bytes_estimate) - f64(flat_stats.bytes_estimate)) * 100.0 / f64(legacy_stats.bytes_estimate)
	}
	// Flat AST uses 4 arenas (files, nodes, edges, strings) regardless of payload
	// count; each is one allocation amortised across millions of cells.
	flat_allocs := u64(4)
	mut alloc_delta_pct := f64(0)
	if legacy_stats.allocs > 0 {
		alloc_delta_pct = (f64(legacy_stats.allocs) - f64(flat_allocs)) * 100.0 / f64(legacy_stats.allocs)
	}
	println(' * AST nodes:      legacy=${legacy_nodes}, flat=${flat_stats.nodes} (edges=${flat_stats.edges}, strings=${flat_stats.strings})')
	println(' * AST memory est: legacy=${legacy_stats.bytes_estimate}B, flat=${flat_stats.bytes_estimate}B (${mem_delta_pct:.2f}% reduction)')
	println(' * AST allocs:     legacy=${legacy_stats.allocs}, flat=${flat_allocs} (${alloc_delta_pct:.2f}% reduction)')
	if os.getenv('V2_FLAT_HIST') != '' {
		hist := b.flat.count_nodes_by_kind()
		mut keys := hist.keys()
		keys.sort_with_compare(fn [hist] (a &string, b &string) int {
			return hist[*b] - hist[*a]
		})
		println(' * AST per-kind histogram (top 20):')
		for i, k in keys {
			if i >= 20 {
				break
			}
			println('     ${k:-30s} ${hist[k]}')
		}
	}
}

fn count_v_lines_for_paths(paths []string) int {
	mut seen_paths := map[string]bool{}
	mut total_v_lines := 0
	for path in paths {
		norm_path := os.norm_path(path)
		if norm_path in seen_paths {
			continue
		}
		seen_paths[norm_path] = true
		lines := os.read_lines(norm_path) or { continue }
		total_v_lines += lines.len
	}
	return total_v_lines
}

fn (b &Builder) count_parsed_v_lines() int {
	mut parsed_paths := []string{}
	mut seen_files := map[string]bool{}
	for ff in b.flat.files {
		name := b.flat.file_name(ff)
		if name in seen_files {
			continue
		}
		seen_files[name] = true
		parsed_paths << name
	}
	return count_v_lines_for_paths(parsed_paths)
}

fn print_parse_summary(parsed_full_files_n int, parsed_vh_files_n int, entry_v_lines_n int, parsed_v_lines_n int, show_stats bool, print_parsed_files bool, parsed_full_files []string, parsed_vh_files []string) {
	println(' * Parsed files: fully parsed files: ${parsed_full_files_n}, parsed .vh files: ${parsed_vh_files_n}')
	if print_parsed_files {
		if parsed_full_files.len > 0 {
			println(' * Fully parsed files:')
			for path in parsed_full_files {
				println('   [full] ${path}')
			}
		}
	}
	if (show_stats || print_parsed_files) && parsed_vh_files.len > 0 {
		println(' * Parsed .vh files:')
		for path in parsed_vh_files {
			println('   [vh] ${path}')
		}
	}
	if show_stats {
		println(' * Parsed V LOC (entry files): ${entry_v_lines_n}')
		println(' * Parsed V LOC (all parsed sources): ${parsed_v_lines_n}')
	}
}