/
Modules

Codex

moduleSource

Available on macOS, Linux, Windows, Wasm

#import "Codex";

Records facts about a build in a .codex file: the modules and files it loaded, and per-procedure code metrics such as call counts and loop depth. It can read the file back.

  • get_plugin is the metaprogram plugin that writes the file when the build finishes (-export_file <path>, default exported.codex).
  • make_help reads a file's bytes into a Codex_Help you can walk.
  • dump_file prints a summary of a .codex file.
Example↗
ok, help, error := make_help(.[]);
assert(!ok && error.count > 0);

Module parameters#

USAGE_MODE := Usage_Mode.WRITE
USAGE_MODE says what an importer does with the module: record a build (.WRITE, the default) or read a recorded one back (.READ), or both. Every declaration is available in every mode.

Procedures#

Codex inspection#

Codex lifetime#

deinitSource
(help: *Codex_Help)

Frees the index arrays of help. The records and strings belong to the file bytes, which the caller frees.

Codex wire values#

get2 overloadsSource
(s: *string, x: *$T)
(s: *string, result: *string, error: *bool)
get_short_stringSource
(input: *string, $count_type: Type, error: *bool, $allocate := true, $zero_terminated := false) -> string

Codex wire reader#

make_helpSource
(memory: [] u8) -> (success: bool, help: Codex_Help, error_string: string)

Checks the bytes of a .codex file and indexes its records. Returns false with a reason when the file is truncated or of another version. The result points into memory; release it with deinit.

memory := cast([] u8) "not a codex file";
ok, help, error := make_help(memory);
assert(!ok && error.count > 0);
↗
dump_fileSource
(name: string) -> bool

Prints the modules, files and procedures of the .codex file at name. Returns false if it cannot be read or is not valid.

assert(!dump_file("no/such/file.codex"));

Doesn't run in the browser (skipped on wasm).

Codex plugin#

get_pluginSource
() -> *Metaprogram_Plugin

Returns the plugin that records the build. Add it to a workspace and forward its messages; when the build finishes it writes the .codex file. The -export_file <path> option picks the path, and the plugin also accepts the project_name, comment and url_or_generation_command keys over the communication channel.

plugin := get_plugin();
assert(plugin.message != null);
↗

This one is only checked to compile, not run.

Codex metrics#

Types#

MetricsstructSource
:: struct

Code metrics for one procedure body: branch points and their depth, loop depth, call counts, allocations, and global reads and writes.

if_points: s32
maximum_if_depth: s32
maximum_loop_depth: s32
total_calls: s32
same_file_calls: s32
same_module_calls: s32
nonconstant_calls: s32
allocations: s32
frees: s32
reassignments: s32
global_reads: s32
global_writes: s32
Revision_Control_TypeenumSource
:: enum

The version control system the build came from, recorded in the file header.

UNKNOWN
SVN
GIT
KRAMPVS
MERCURIAL
PERFORCE
File_RecordstructSource
:: struct

A source file the build loaded: its path and the module it belongs to (an index into the module list).

fully_pathed_filename: Relative.Relative_String(s16)
module_index: s32
from_a_string: bool
Header_RecordstructSource
:: struct

The start of a .codex file: format version, when and for what target it was made, and the counts of the records that follow.

magic: u32
version: u32
time_generated: Basic.Apollo_Time
revision_control_type: Revision_Control_Type
revision_number: u64
num_modules: s32
num_files: s32
num_procedures: s32
reserved: [256] u8
OS: Operating_System_Tag
optimization_type: Compiler.Optimization_Type
project_name: Relative.Relative_String(s16)
executable_name: Relative.Relative_String(s16)
url_or_generation_command: Relative.Relative_String(s16)
comment: Relative.Relative_String(s16)

Constants#