lu_sys/luacode.rs
1#![allow(clippy::missing_safety_doc)]
2#![allow(non_camel_case_types)]
3#![allow(non_snake_case)]
4
5use std::ffi::{c_char, c_double, c_float, c_int, c_void};
6
7/// A constant that can be configured during compilation to enable constant
8/// folding and other optimizations.
9pub type lua_CompileConstant = *mut c_void;
10
11/// A callback to retrieve the type of a member in a library, which is used to
12/// provide type information during native codegen.
13///
14/// Waiting on https://github.com/luau-lang/luau/discussions/1885 for more
15/// details on how this works.
16pub type lua_LibraryMemberTypeCallback =
17 extern "C" fn(library: *const c_char, member: *const c_char) -> c_int;
18
19/// Allows the configuration of a constant in a library at compile time. This
20/// enables the compiler to optimize code with constant folding and other
21/// optimizations.
22pub type lua_LibraryMemberConstantCallback = extern "C" fn(
23 library: *const c_char,
24 member: *const c_char,
25 constant: *mut lua_CompileConstant,
26);
27
28/// Options to configure the Luau compiler with.
29///
30/// All memory pointed to by this struct must be valid for the duration of the
31/// [`luau_compile`] call that this struct is passed to.
32#[repr(C)]
33pub struct lua_CompileOptions {
34 /// What kind of optimizations the compiler should perform.
35 ///
36 /// 0: No optimizations.
37 /// 1: Optimizations that do not impact debugging or debugging information.
38 /// 2: Optimizations that may impact debugging or debugging information.
39 pub optimizationLevel: c_int,
40
41 /// The amount of debug information to include in the compiled bytecode.
42 ///
43 /// 0: No debug information.
44 /// 1: Line info and function names, sufficient for backtraces.
45 /// 2: Full debug information including variable names.
46 pub debugLevel: c_int,
47
48 /// The type information to include in the compiled bytecode.
49 ///
50 /// 0: Emit type information only for native codegen.
51 /// 1: Emit type information for all code.
52 pub typeInfoLevel: c_int,
53
54 /// The amount of coverage information to include in the compiled bytecode.
55 ///
56 /// 0: No coverage information.
57 /// 1: Coverage information for statements.
58 /// 2: Coverage information for statements and expressions.
59 pub coverageLevel: c_int,
60
61 /// An alternative global used to construct vectors in addition to
62 /// `vector.create`.
63 ///
64 /// This field is the library name. The constructor name is in
65 /// [`lua_CompileOptions::vectorCtor`].
66 ///
67 /// The full configured vector constructor is
68 /// `<vectorLib>.<vectorCtor>(x, y, z)`.
69 pub vectorLib: *const c_char,
70
71 /// The name of the alternative vector constructor function.
72 ///
73 /// This field is the constructor name. The library name is in
74 /// [`lua_CompileOptions::vectorLib`].
75 ///
76 /// The full configured vector constructor is
77 /// `<vectorLib>.<vectorCtor>(x, y, z)`.
78 pub vectorCtor: *const c_char,
79
80 /// An alternative name for the vector type in addition to `vector`.
81 pub vectorType: *const c_char,
82
83 /// An array of global names that are mutable globals.
84 ///
85 /// The import optimization will be disabled for these globals. This array
86 /// is null-terminated.
87 pub mutableGlobals: *const *const c_char,
88
89 /// Waiting to document alongside [`lua_LibraryMemberTypeCallback`]
90 pub userdataTypes: *const *const c_char,
91
92 /// An array of global names that are libraries with known members.
93 ///
94 /// This array is null-terminated.
95 pub librariesWithKnownMembers: *const *const c_char,
96
97 /// A callback to retrieve the type of a member in a library.
98 pub libraryMemberTypeCb: Option<lua_LibraryMemberTypeCallback>,
99
100 /// A callback to retrieve the constant value of a member in a library.
101 pub libraryMemberConstantCb: Option<lua_LibraryMemberConstantCallback>,
102
103 /// An array of global or library function names that are normally built-in
104 /// to the language, but are disabled for this compilation.
105 ///
106 /// This array contains members like "print" or "table.insert". This array
107 /// is null-terminated.
108 pub disabledBuiltins: *const *const c_char,
109}
110
111unsafe extern "C" {
112 /// Compiles the given source code into Luau bytecode.
113 ///
114 /// The `source` parameter is a pointer to the source code as a string of
115 /// length `size`. The `options` parameter is a pointer to a
116 /// [`lua_CompileOptions`] struct that configures the compilation process.
117 /// The `outsize` parameter is a pointer to a variable that will receive the
118 /// size of the compiled bytecode.
119 ///
120 /// If compilation is successful, this function returns a pointer to the
121 /// compiled bytecode. If compilation fails, the error is encoded in the
122 /// returned bytecode. This can be detected by checking if the first byte
123 /// of the returned bytecode is `0`, which indicates an error. The remaining
124 /// bytes will contain the error message.
125 ///
126 /// All produced bytecode, both successful and non-successful, can be loaded
127 /// into a Luau VM using [`luau_load`](crate::luau_load).To drop, the returned pointer should
128 /// be passed into [`libc::free`].
129 pub fn luau_compile(
130 source: *const c_char,
131 size: usize,
132 options: *mut lua_CompileOptions,
133 outsize: *mut usize,
134 ) -> *mut c_char;
135
136 /// Sets the given compile constant to `nil`.
137 pub fn luau_set_compile_constant_nil(constant: *mut lua_CompileConstant);
138
139 /// Sets the given compile constant to a boolean value.
140 pub fn luau_set_compile_constant_boolean(constant: *mut lua_CompileConstant, b: c_int);
141
142 /// Sets the given compile constant to a number value.
143 pub fn luau_set_compile_constant_number(constant: *mut lua_CompileConstant, n: c_double);
144
145 /// Sets the given compile constant to a vector value. This function always
146 /// takes four components, but when loaded into a Luau VM the last component
147 /// will be ignored if the VM is in 3-wide mode.
148 pub fn luau_set_compile_constant_vector(
149 constant: *mut lua_CompileConstant,
150 x: c_float,
151 y: c_float,
152 z: c_float,
153 w: c_float,
154 );
155
156 /// Sets the given compile constant to a string value.
157 ///
158 /// The string is a pointer to a string of length `l`.
159 pub fn luau_set_compile_constant_string(
160 constant: *mut lua_CompileConstant,
161 s: *const c_char,
162 l: usize,
163 );
164}