Jacket
#import "Compiler";
The metaprogramming API: create and drive builds ("workspaces") from compile-time code, read and edit the program as syntax trees, and listen to what the compiler does.
Code_* relatives are the syntax tree; compiler_get_code and compiler_modify_procedure read and rewrite it.#run {
w := compiler_create_workspace("demo");
options := get_build_options(w);
options.output_type = .NO_OUTPUT;
set_build_options(options, w);
add_build_string("value :: 47; main :: () {}", w);
compiler_begin_intercept(w);
while true {
message := compiler_wait_for_message();
if message.kind == .COMPLETE break;
}
compiler_end_intercept(w);
}
main :: () {}Sets the options that go with an optimization level: bounds and cast checks, the LLVM optimization settings, inlining and so on. preserve_debug_info keeps or drops debug information.
options: Build_Options;
set_optimization(*options, .OPTIMIZED);
assert(options.array_bounds_check == .OFF);
set_optimization(*options, .DEBUG);
assert(options.array_bounds_check == .ON);Copies the options that a workspace passes on to the workspaces it creates (Build_Options.Commonly_Propagated) from a to b.
Allocates a number literal node with the value v, for building code by hand.
literal := make_integer_literal(42);
assert(literal._s64 == 42 && literal.kind == .LITERAL);Allocates a string literal node holding a copy of s.
literal := make_string_literal("hi");
assert(literal._string == "hi");Returns the file, line and column where c was written, as a Source_Code_Location.
Returns the full path of the file node was loaded from, or an empty string.
Splits a file path into its name without the extension and its folder (with the trailing slash).
name, folder := get_basename_and_path("src/lib/parser.jai");
assert(name == "parser" && folder == "src/lib/");True if the struct info is, or starts with a #as using member that is, a struct called base_name.
Returns the source spelling of an operator, such as "==" or "<<".
assert(operator_to_string(.IS_EQUAL) == "==");Starts a new workspace, an independent build with its own options, code and output. name shows up in messages and errors.
#run {
w := compiler_create_workspace("scratch");
assert(get_name(w) == "scratch");
compiler_destroy_workspace(w);
}
main :: () {}Frees a workspace made with compiler_create_workspace. Do it after its build is complete.
Returns the name of workspace w; the default is the workspace running the code.
Returns a copy of the options of workspace w; the default is the workspace running the code. Change the copy and hand it back with set_build_options.
Replaces the options of workspace w. Set them before adding code.
#run {
w := compiler_create_workspace("options");
options := get_build_options(w);
options.output_type = .NO_OUTPUT;
set_optimization(*options, .OPTIMIZED);
set_build_options(options, w);
assert(get_build_options(w).output_type == .NO_OUTPUT);
compiler_destroy_workspace(w);
}
main :: () {}Changes the few options that may still change while a build is running, such as its output name and path. Build_Options_During_Compile says which.
Adds the source file filename to workspace w, as if it were passed on the command line.
#import "File";
#run {
path := tprint("%/extra.jai", #filepath);
write_entire_file(path, "extra :: 1;");
w := compiler_create_workspace("from file");
options := get_build_options(w);
options.output_type = .NO_OUTPUT;
set_build_options(options, w);
add_build_file(path, w);
}
main :: () {}Doesn't run in the browser (skipped on wasm).
Adds the source text data to workspace w. Pass code to compile it in the scope that code was written in, so it can see that scope's names.
#run {
w := compiler_create_workspace("strings");
options := get_build_options(w);
options.output_type = .NO_OUTPUT;
set_build_options(options, w);
add_build_string("answer :: 42; main :: () {}", w);
}
main :: () {}Reports a problem at loc (by default the call site). The default mode, .ERROR, fails the build once the current step ends; .WARNING and .INFO only print.
#run compiler_report("heads up", mode = .INFO);
main :: () {}Fills version_info with the compiler's version numbers and returns the version as a string.
Returns the arguments of the command line the compiler was started with, so a build script can read its own options.
Returns the folder the compiler installation lives in.
Adds path to the folders searched for native libraries named by #library.
Makes #import "import_name" inside host_module_name load replacement_name instead. Use it from a message handler to swap in another version of a module.
Answers a Message_Failed_Import: tells the compiler where to find the module it could not. type says whether value is a module name, a file, a folder or the full source text.
Returns the syntax tree of code as its root node and the flat list of expressions in it.
Turns the node node back into a Code value you can insert with #insert. code_to_copy_scope_from says which scope the new code is read in.
Returns the type a typed Code value stands for, and a status that says why there is none when it fails.
Returns the Type that goes with a Type_Info pointer.
Returns the Type_Info of every type in workspace w.
Makes sure the procedure header is compiled into the program even if nothing calls it.
Replaces the body of a procedure with the (edited) tree under body, then compiles it again.
Starts receiving the compiler's Messages for workspace w. Read them with compiler_wait_for_message and finish with compiler_end_intercept. flags skips kinds of typechecked code you do not care about.
Stops receiving messages for w, which lets the build carry on to its end.
Marks workspace w as failed, so that building it ends with an error.
Blocks until the compiler has a message for an intercepted workspace, and returns it. Check kind and cast to the matching Message_* type. The last message of a build is .COMPLETE.
#run {
w := compiler_create_workspace("messages");
options := get_build_options(w);
options.output_type = .NO_OUTPUT;
set_build_options(options, w);
add_build_string("main :: () {}", w);
compiler_begin_intercept(w);
files := 0;
while true {
message := compiler_wait_for_message();
if message.kind == .FILE files += 1;
if message.kind == .COMPLETE break;
}
compiler_end_intercept(w);
assert(files > 0);
}
main :: () {}Asks for a named data segment in the program being built. Returns it and whether the compiler will really create it on this target.
Copies data into a data segment and returns the stored bytes, which live in the built program.
Returns the type table and the global data layout of workspace w. Used by tools that read a program's memory.
A data segment added to the built program with add_data_segment. Pass it back as user_segment to add_global_data.
What a custom data segment allows: reading, writing, executing, and whether it starts zeroed.
Which segment add_global_data puts data in: one of the built-in ones, or USER_SEGMENT for one you added.
The global data of a built program, as a list of segments. Part of Runtime_Info.
One segment of the global data: what kind it is (zeroed, writable, read-only, ...) and its bytes.
What a program knows about itself at run time: its type table and its global data. Get it from get_runtime_info.
Switches for how much type information a workspace keeps, set with compiler_set_type_info_flags.
Every setting of a build: what to produce (output_type), where to write it, the checks to compile in, the optimizer and the backend. Get a copy with get_build_options, change it, and apply it with set_build_options. set_optimization fills in the fields that go with an optimization level.
options: Build_Options;
assert(options.output_type == .EXECUTABLE);
options.output_type = .NO_OUTPUT;
options.array_bounds_check = .OFF;The build options that can still change while a build is running. Apply them with set_build_options_dc.
How hard LLVM optimizes the program: O0 to O3 for speed, OS and OZ for size.
How hard LLVM optimizes when it turns the program into machine code.
Settings for the LLVM backend: optimization levels, inlining, vectorization, and what intermediate output to keep.
An optimization preset for set_optimization, from DEBUG to VERY_OPTIMIZED, plus two that favor size.
The compiler's version, filled in by compiler_get_version_info.
Settings for the built-in x64 backend.
Which kinds of typechecked code compiler_begin_intercept should leave out of its messages, and which performance reports to send.
The start of every compiler message. kind says which Message_* type it really is; cast to that type to read the rest. workspace is the build it belongs to.
The last message of a build. error_code says whether it worked.
The text of a #debug_dump request.
A module could not be found. Answer it with provide_import, or the build fails.
A source file was loaded, with its full path and the import it belongs to.
A module was imported, with its name, path and kind.
Timing and counts about the build, sent when Intercept_Flags asks for them.
The build reached a stage, such as all source being parsed or the executable being written.
A batch of code finished type checking: declarations, procedure headers and bodies, structs and everything else, each with the nodes inside it.
What the answer to a Message_Failed_Import is: a module name, a file, a folder or source text.
How serious a compiler_report is. ERROR fails the build; the others only print.
Whether a workspace is still good, for compiler_set_workspace_status.
One argument in a call or return: its expression, and its name if it was passed by name.
The details of an array literal: element type, alignment and members.
An inline assembly block.
A two-operand expression such as a + b: the operator and the left and right nodes.
A { ... } block: its statements and the declarations it makes.
One case of an if == switch.
A cast, explicit or inserted by the compiler, with the type it converts to.
One entry of a Code_Comma_Separated_Arguments list.
A comma-separated list on the left of := or =, as in a, b := f();.
A declaration of several names at once, as in a, b := f();.
The context value.
A declaration: a variable, constant, parameter or procedure name, with its type, value, notes and flags.
A defer statement and its block.
An #add_context directive.
A #bake or $$ expression, which fixes some arguments of a procedure.
A #bytes directive.
A #code expression, whose body becomes a Code value.
A #context directive.
An #exists query.
An #import directive: the module name and its parameters.
An #insert directive and the code it inserts.
A #library directive naming a native library.
A #load directive: the file it names and its resolved path.
A #location expression.
A #modify block on a procedure or struct.
A #module_parameters directive.
An #overlay directive.
A #poke_name directive.
A #procedure_name directive.
A #run directive and the procedure it runs.
A #scope_export, #scope_file or #scope_module directive.
A #through directive.
A #wildcard placeholder.
An enum definition: its members, notes and whether it is a flags or complete enum.
A type_of, is_constant or #code_of query about an expression.
Picks one value out of a multiple-value expression.
A for loop: what it iterates, its body and its it and it_index names.
A name, and the declaration it resolved to.
An if or ifx, including a #if and an if == switch.
A literal: a number, string, boolean, array, struct, pointer or type. value_type says which, and the matching union member holds the value.
A break, continue or remove.
The list of extra arguments a call passes to a variadic procedure.
The part every syntax node shares: its kind, where it is in the source, its type once checked and flags. Cast a node to the Code_* type that matches its kind to read the rest.
A @note attached to a declaration, procedure or struct.
A stand-in for code that is not there yet.
The details of a pointer constant: the symbol or literal it points into, and an offset.
The body of a procedure, with its header.
A procedure call: the procedure, its arguments (as written and in parameter order) and the overload it resolved to.
A procedure's declaration: name, parameters, return values, notes and flags such as MACRO or POLYMORPHIC.
A push_context statement and its block.
An overloaded name after the compiler chose a procedure.
A return statement and its values.
Something named in a scope. Code_Declaration builds on it.
A struct or union definition: its members, notes and the type it defines.
The details of a struct literal: its type and its arguments.
A type that is used as a value, with its Type_Info.
A type as written in source, such as *[] int, and the Type_Info it resolved to.
A size_of, type_info or initializer_of expression.
A one-operand expression such as -x or !x.
A using statement or parameter.
A while loop and its body.
Why get_root_type succeeded or failed.
An operator that has no single-character name. Single-character operators use their character, as in cast(Operator_Type) #char "+".
How many calls and instructions the compile-time interpreter ran, and how many were inlined.
A plugin for a metaprogram. Fill in the procedures you care about and the compiler calls them: init once, message for every compiler message, finish at the end. workspace is the build it works on.
plugin: Metaprogram_Plugin;
plugin.message = (p: *Metaprogram_Plugin, message: *Message) {};
assert(plugin.init == null);Counts of the polymorphic procedures the compiler instantiated, and from where.
How long each #run took.
How long the compile-time interpreter spent running code, inlining and generating bytecode.
A node that has finished type checking, with all the nodes inside it. Found in Message_Typechecked.