v.modulecache #

The v.modulecache module stores V3 module interfaces, compiled objects, and program plans.

Use module_headers_with_const_order when generating interfaces for several modules from the same checked AST. It builds the declaration, module, and import indexes once for the batch and preserves each module's source order, attributes, implicit imports, and runtime constant order. For a single module, module_header_with_const_order provides the same header text.

Struct interfaces preserve explicit field types, including names such as i64 i64, alongside embedded fields and field attributes. Cached imports retain the same field reflection and JSON keys.

Cached builds preserve the same module initialization order as uncached builds. Dependencies initialize before their importers, and direct imports are visited in source order even when the importer has no init() function of its own.

Custom free() methods keep their original function scope during incremental rebuilds. Calling a module's own free or a selectively imported function preserves receiver mutations, while a direct call to builtin free(receiver) retains the shallow-copy behavior for named values.

Declaration headers preserve macros that define static storage, including generated string literals. Parallel C compilation can include these definitions in each translation unit. GNU __extension__ markers remain on typedefs and external declarations. Replication checks recognize these type declarations while continuing to reject external definitions and static state.

Cleanup hooks follow the reverse dependency order, including through modules without initialization or cleanup hooks. Cleanup-only modules remain included when no startup or import metadata references them.

Manager.discard_program_entries(source_files) invalidates the whole-program C plan, prepared plan, generic and incremental snapshots, and cached executable for that source set. It removes their validation stamps while preserving the artifact files and compiled module entries. When C compilation rejects an incrementally restored program, the driver uses this method before retrying from sources with incremental restoration disabled.

fn c_source_declares_types(source string) bool

c_source_declares_types reports whether a local C input defines a type whose declaration may be required by generated V declarations in another cache unit.

fn c_source_function_identifiers(source string) map[string]bool

c_source_function_identifiers returns C functions defined or declared at file scope.

fn c_source_function_identifiers_with_status(source string) (map[string]bool, bool)

c_source_function_identifiers_with_status returns file-scope C function names and whether every function declaration could be classified.

fn c_source_has_static_storage(source string) bool

c_source_has_static_storage reports whether a local C input would give cached translation units separate copies of static storage.

fn c_source_is_replicable(source string) bool

c_source_is_replicable reports whether every translation unit can include a native input unchanged: it defines no function or variable with external linkage and keeps no static storage, so the copies that separate objects get can neither collide at link time nor diverge at run time.

fn c_source_replicated_function_has_static_storage(source string) bool

c_source_replicated_function_has_static_storage reports whether a function definition retained by declaration_header contains function-local static storage.

fn c_source_static_function_identifiers_with_status(source string) (map[string]bool, bool)

c_source_static_function_identifiers_with_status returns file-scope static C function names and whether every potentially static function declaration could be classified.

fn c_source_static_variable_identifiers(source string) (map[string]bool, bool)

c_source_static_variable_identifiers returns file-scope static variable names and whether every such declaration could be classified.

fn c_source_type_declarations(source string) string

c_source_type_declarations keeps preprocessor context and C type declarations, while omitting function bodies, function declarations, and storage.

fn c_source_type_declarations_with_status(source string) (string, bool)

c_source_type_declarations_with_status also reports whether every declaration-like file-scope macro invocation could be classified.

fn c_source_type_identifiers(source string) map[string]bool

c_source_type_identifiers returns C typedef aliases and named aggregate tags.

fn c_source_typedef_identifiers(source string) map[string]bool

c_source_typedef_identifiers returns file-scope C typedef aliases.

fn c_sources_macro_identifiers_referencing(sources []string, identifiers map[string]bool) map[string]bool

c_sources_macro_identifiers_referencing returns macro names whose replacements directly or transitively reference one of the supplied identifiers.

fn cached_source_signature(cache_dir string, namespace string, source_files []string) string

cached_source_signature returns a content signature while using precise file metadata to avoid rereading unchanged inputs on subsequent compiler runs.

fn declaration_header(prefix string) string

declaration_header converts the generated owner prefix into a C header for cached module translation units. Type definitions and static helpers stay local; owner functions and storage become declarations resolved from main.o.

fn declarations_use_recover(a &flat.FlatAst, tc &types.TypeChecker) bool

declarations_use_recover reports whether a declaration of the program may use the builtin recover, by calling it or using it as a value. A name the checker leaves unresolved counts, unless the function around it binds that name itself, so the answer errs toward panic frames. A build that keeps every concrete function (-no-skip-unused) can run any of them, as an object file can export them.

fn embedded_source_paths(source_file string, vroot string) []string

embedded_source_paths lists the resolved $embed_file paths in one source file. Callers use it to keep resources that cached declaration bodies omit in the whole-program cache identity.

fn file_metadata_signature(path string) string

file_metadata_signature returns a precise identity for an unchanged cache input. Include the running compiler build so a memoized source signature cannot survive a compiler update and make a new checker replay stale cached diagnostics. An empty result means the metadata cannot identify the file: the file system reports no identity for it (some network redirectors on Windows) or no change time (FAT and exFAT on Windows), or it was modified so recently that another same-size edit could still leave identical metadata. Callers must then compare the file contents instead, see file_change_signature.

fn file_signature(path string) string

file_signature returns a stable content signature for a cache input file.

fn header_c_struct_sources(header string) map[string]string

header_c_struct_sources recovers the original V source of each C struct in a compiler-generated module header. Native headers remain opaque: these records come only from the V declarations serialized into the cache.

fn header_calls_recover(entry Entry) bool

header_calls_recover reports whether the code of the module of a header calls recover(). Every defer of a build with such a module links a panic frame: the program may reach the call through a function that the header only declares, and the objects of its modules were compiled before it did.

fn header_needs_source(entry Entry) bool

header_needs_source reports whether a declaration header has bodies that must remain available to per-program monomorphization.

fn header_signature(header string) string

header_signature returns the stable content signature stored in dependent object stamps for a declaration-only module header.

fn header_text_calls_recover(header string) bool

header_text_calls_recover is header_calls_recover for the text of a header.

fn materialize_cached_body_string_definitions(source string) string

materialize_cached_body_string_definitions restores body-only string storage recorded as cache marker comments. Real definitions in source take precedence.

fn module_header(a &flat.FlatAst, tc &types.TypeChecker, module_name string, vroot string, import_paths map[string]string) string

module_header serializes the declaration-only interface for one flat-AST module.

fn module_header_with_const_order(a &flat.FlatAst, tc &types.TypeChecker, module_name string, vroot string, import_paths map[string]string, const_order []string) string

module_header_with_const_order preserves dependency ordering for runtime constants whose helper bodies are intentionally omitted from warm headers.

fn module_headers_with_const_order(a &flat.FlatAst, tc &types.TypeChecker, module_names []string, vroot string, import_paths map[string]string, const_order []string) map[string]string

module_headers_with_const_order generates module headers using one declaration index for the checked AST, preserving the same source and constant order as module_header_with_const_order.

fn new_manager(vroot string, salt string, enabled bool, build_pseudo_values string, version_pseudo_values string) Manager

new_manager creates a configuration-scoped persistent module cache manager. Delegated compilers retain V3_PRIMARY_VEXE for isolated cache lookup.

fn prune_unreferenced_static_string_definitions(prefix string) string

prune_unreferenced_static_string_definitions removes generated string storage that is referenced only by the program body. Cached module objects carry their own static copies, while the program translation unit retains the full prefix. Keeping body-only strings out of the shared dylib prefix makes an ordinary program literal edit reuse the same cached dylib.

fn rewrite_cached_runtime_strings(cached_source string, old_values []string, new_values []string) ?string

rewrite_cached_runtime_strings updates cached C literal symbols as one simultaneous rewrite.

fn source_files_use_build_time_pseudo(source_files []string) bool

source_files_use_build_time_pseudo reports whether selected sources depend on build time.

fn source_signature(source_files []string) string

source_signature hashes selected source paths, contents, resolved module roots, build/environment values, and pkg-config probe results in stable order.

fn split_generated_c(source string) !CSplit

split_generated_c separates a cache-marked monolithic translation unit.

fn static_string_definition_texts(source string) []string

static_string_definition_texts returns each generated literal definition of source, without its final newline. A definition can span several lines.

fn static_string_definitions(source string) string

static_string_definitions returns generated literal storage needed by the current program body. Cached dependency declarations omit these records.

fn without_duplicate_static_string_definitions(source string, existing_source string) string

without_duplicate_static_string_definitions removes literal storage already supplied by an earlier cached C prefix while retaining new body-only literals.

struct CSplit {
pub:
	prefix  string
	modules map[string]string
}

CSplit contains the declaration/runtime prefix and per-module C function bodies.

struct CgenEntry {
pub:
	source           string
	metadata         string
	stamp            string
	prepared_main    string
	prepared_tcc     string
	prepared_prefix  string
	prepared_objects string
	prepared_stamp   string
}

CgenEntry contains the persistent whole-program C generation artifacts.

struct CgenPreparedEntry {
pub:
	main   string
	tcc    string
	prefix string
}

CgenPreparedEntry contains cache-marked C sources already split for linking.

struct Entry {
	source_bodies       bool
	source_bodies_known bool
	calls_recover       bool
pub:
	header         string
	object         string
	header_stamp   string
	object_stamp   string
	c_source       string
	source_digests map[string]string
}

Entry contains the persistent artifacts for one V module.

struct GenericProgramEntry {
pub:
	specs        string
	used         string
	prefix       string
	declarations string
	body         string
	literals     string
	metadata     string
	stamp        string
}

GenericProgramEntry contains program-specific dependency specializations that remain valid across edits which do not change the program's generic ABI.

struct IncrementalProgramEntry {
pub:
	manifest         string
	body             string
	used             string
	specs            string
	prefix           string
	declarations     string
	tcc_declarations string
	objects          string
	metadata         string
	stamp            string
}

IncrementalProgramEntry contains a complete program body split into stable function sections plus the semantic/link metadata needed to regenerate only functions whose parsed bodies changed.

struct Manager {
	build_pseudo_values   string
	version_pseudo_values string
	pkg_probes            &PkgConfigProbes = unsafe { nil }
	source_paths          &SourcePaths     = unsafe { nil }
pub:
	dir     string
	enabled bool
	salt    string
}

Manager owns persistent v3 module cache paths for one compiler configuration.

fn (m &Manager) real_source_path(path string) string

real_source_path returns os.real_path(path) for a source file. The answer is kept for the rest of the build when it is asked for before freeze_source_paths.

fn (m &Manager) remember_source_path(path string, resolved string)

remember_source_path records that resolved is os.real_path(path), for a caller that has resolved the path already. It does nothing after freeze_source_paths.

fn (m &Manager) real_source_paths(files []string) []string

real_source_paths returns real_source_path of every file, in the order of files.

fn (m &Manager) freeze_source_paths()

freeze_source_paths ends the recording of resolved source paths. Call it on the thread that owns the build, outside any disposable allocation scope and before other threads use the manager; what was resolved until then stays available.

fn (m &Manager) ensure_dir() bool

ensure_dir creates the manager's private cache directory.

fn (m &Manager) entry(module_name string, source_files []string) Entry

entry returns collision-resistant artifact paths for a module and source root.

fn (m &Manager) object_entry(module_name string, source_files []string, compile_signature string) Entry

object_entry returns the C artifacts for one effective compile-flag set.

fn (m &Manager) object_alias(module_name string, source_files []string, alias_signature string) ?string

object_alias returns the content key of the object that an earlier build compiled or found for alias_signature. The key says nothing about the sources or the dependencies of the module: the stamp of the object it leads to does.

fn (m &Manager) write_object_alias(module_name string, source_files []string, alias_signature string, content_key string) !

write_object_alias records that a build with alias_signature generates the C that content_key identifies for this module.

fn (m &Manager) cgen_entry(source_files []string) CgenEntry

cgen_entry returns the artifact paths for one stable program source set.

fn (m &Manager) valid_entry(module_name string, source_files []string) ?Entry

valid_entry reports whether both interface and object artifacts match their sources.

fn (m &Manager) valid_entry_with_metadata_cache(module_name string, source_files []string, mut dependency_metadata map[string]string) ?Entry

valid_entry_with_metadata_cache reports whether both interface and object artifacts match their sources, reusing dependency metadata already observed during this compiler run.

fn (m &Manager) valid_header(module_name string, source_files []string) ?Entry

valid_header reports whether a declaration header matches its module sources.

fn (m &Manager) valid_object(cache_name string, source_files []string) ?Entry

valid_object reports whether a cached object matches the supplied sources.

fn (m &Manager) write_entry(module_name string, source_files []string, header string) !Entry

write_entry commits a module interface and stamp after its object was built.

fn (m &Manager) write_header(module_name string, source_files []string, header string) !Entry

write_header commits one declaration-only module header and its source stamp.

fn (m &Manager) valid_object_for_compile_signature(cache_name string, source_files []string, compile_signature string, dependency_inputs map[string]string) ?Entry

valid_object_for_compile_signature reports whether the flag-specific object matches its sources, dependency headers, and effective C compilation flags.

fn (m &Manager) reusable_object(cache_name string, source_files []string, compile_signature string, dependency_inputs map[string]string) ?Entry

reusable_object is valid_object_for_compile_signature for a build that has the C of the module and compiles it when the object is not there: nothing is missing then, so nothing is traced.

fn (m &Manager) valid_cgen(source_files []string, generation_signature string, dependency_inputs map[string]string) ?CgenEntry

valid_cgen reports whether a whole-program C plan matches its program sources, imported module headers, and semantic generation signature.

fn (m &Manager) has_cgen_commit(source_files []string) bool

has_cgen_commit reports whether an exact whole-program cache entry still has all payloads and its commit stamp, without validating their current inputs.

fn (m &Manager) cached_cgen_dependency_inputs(source_files []string, generation_signature string, fixed_dependencies map[string]string, restored_prefixes []string) ?map[string]string

cached_cgen_dependency_inputs restores dependency records whose prefixes are allowed to vary, after validating the program sources, generation signature, and every fixed dependency supplied by the caller.

fn (m &Manager) cached_incremental_dependency_inputs(source_files []string, declaration_signature string, generation_signature string, fixed_dependencies map[string]string, restored_prefixes []string) ?map[string]string

cached_incremental_dependency_inputs restores dependency records from a declaration-stable program snapshot after the main source bodies change.

fn (m &Manager) valid_generic_program(source_files []string, semantic_signature string, generation_signature string, dependency_inputs map[string]string) ?GenericProgramEntry

valid_generic_program reports whether cached dependency specializations match the program's type/call shape and all module cache inputs.

fn (m &Manager) write_cgen(source_files []string, generation_signature string, dependency_inputs map[string]string, source string, metadata string) !CgenEntry

write_cgen atomically commits a whole-program C plan and its generation metadata.

fn (m &Manager) write_generic_program(source_files []string, semantic_signature string, generation_signature string, dependency_inputs map[string]string, specs string, used string, prefix string, declarations string, body string, literals string, metadata string) !GenericProgramEntry

write_generic_program atomically publishes dependency specialization metadata. The stamp is written last so readers cannot observe mixed payloads.

fn (m &Manager) valid_incremental_program(source_files []string, declaration_signature string, generation_signature string, dependency_inputs map[string]string) ?IncrementalProgramEntry

valid_incremental_program restores function-level artifacts when declarations, compiler configuration, dependencies, and native inputs are unchanged.

fn (m &Manager) write_incremental_program(source_files []string, declaration_signature string, generation_signature string, dependency_inputs map[string]string, manifest string, body string, used string, specs string, prefix string, declarations string, tcc_declarations string, objects []string, metadata string) !IncrementalProgramEntry

write_incremental_program atomically publishes a function-level program snapshot. The stamp is the commit marker and is written after every payload.

fn (m &Manager) valid_cgen_prepared(entry CgenEntry) ?CgenPreparedEntry

valid_cgen_prepared reports whether all pre-split C plan sources match entry's generation.

fn (m &Manager) write_cgen_prepared(entry CgenEntry, main_source string, tcc_source string, prefix_source string) !

write_cgen_prepared publishes pre-split C plan sources, committing their stamp last.

fn (m &Manager) valid_cgen_prepared_objects(entry CgenEntry, compile_signature string) ?[]string

valid_cgen_prepared_objects restores the object set for one effective compile signature.

fn (m &Manager) write_cgen_prepared_objects(entry CgenEntry, compile_signature string, objects []string) !

write_cgen_prepared_objects publishes the object set for one effective compile signature.

fn (m &Manager) valid_program_executable(source_files []string, generation_signature string, dependency_inputs map[string]string, link_signature string) ?ProgramExecutable

valid_program_executable returns the executable that an earlier build linked from the inputs that this build has: the same program sources, module interfaces, native inputs and configuration (as for valid_cgen), the same link_signature, and inputs of the C compiler and of the linker that are the files they were. The headers that the compiler read and the files that the link read are compared by their metadata, and a path where either looked for a file in vain has to be absent still. Such a build has nothing left to generate, compile or link.

fn (m &Manager) discard_program_entries(source_files []string)

discard_program_entries removes the stamps of every whole-program entry of source_files (C plan, prepared plan, generic and incremental snapshots, linked executable). The entry files stay, but no build reads them again until it writes them afresh, so the next build generates the program from its sources.

fn (m &Manager) write_program_executable(source_files []string, generation_signature string, dependency_inputs map[string]string, link_signature string, link_files []string, link_identities []string, link_missing []string, executable string, notices string) !

write_program_executable keeps a copy of executable, which a build has just linked, for the next build of the same inputs. link_files are the files that the C compiler and the linker read besides the C of the build: headers, objects, libraries. link_identities is the metadata that each of them had when it was read, or before, link_missing the paths where a file would have been read too if it had been there, and notices what the build printed about the program, in a form that the driver can print again. A file that is no longer what it was then, or a path that is no longer absent, may or may not be what was read: nothing is kept then. One executable is kept for a program source set: the copy of the previous one is removed.

fn (m &Manager) write_stamp(module_name string, source_files []string, dependency_inputs map[string]string, compile_signature string) !

write_stamp refreshes a cache stamp after the object and header are durable. dependency_inputs maps every transitive imported .vh and non-V input path to the content signature that the object was compiled against.

struct ProgramExecutable {
	metadata string
pub:
	path    string
	notices string
}

ProgramExecutable is the linked executable that the cache keeps for a program, with what its build printed about the program.

fn (e &ProgramExecutable) restore(destination string) bool

restore copies the cached executable to destination, through a new file that replaces destination when it is complete. It reports false, and leaves destination alone, unless the bytes it copied are those of the executable that valid_program_executable found: a build that publishes at the same moment replaces that file, and never changes it in place.