]>
Commit | Line | Data |
---|---|---|
a945c346 | 1 | .. Copyright (C) 2014-2024 Free Software Foundation, Inc. |
35485da9 DM |
2 | Originally contributed by David Malcolm <dmalcolm@redhat.com> |
3 | ||
4 | This is free software: you can redistribute it and/or modify it | |
5 | under the terms of the GNU General Public License as published by | |
6 | the Free Software Foundation, either version 3 of the License, or | |
7 | (at your option) any later version. | |
8 | ||
9 | This program is distributed in the hope that it will be useful, but | |
10 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
12 | General Public License for more details. | |
13 | ||
14 | You should have received a copy of the GNU General Public License | |
15 | along with this program. If not, see | |
786973ce | 16 | <https://www.gnu.org/licenses/>. |
35485da9 DM |
17 | |
18 | .. default-domain:: c | |
19 | ||
fdce7209 | 20 | Compiling a context |
35485da9 DM |
21 | =================== |
22 | ||
85c943f3 | 23 | Once populated, a :c:expr:`gcc_jit_context *` can be compiled to |
fdce7209 DM |
24 | machine code, either in-memory via :c:func:`gcc_jit_context_compile` or |
25 | to disk via :c:func:`gcc_jit_context_compile_to_file`. | |
26 | ||
27 | You can compile a context multiple times (using either form of | |
28 | compilation), although any errors that occur on the context will | |
29 | prevent any future compilation of that context. | |
35485da9 | 30 | |
fdce7209 DM |
31 | In-memory compilation |
32 | ********************* | |
35485da9 DM |
33 | |
34 | .. function:: gcc_jit_result *\ | |
35 | gcc_jit_context_compile (gcc_jit_context *ctxt) | |
36 | ||
37 | This calls into GCC and builds the code, returning a | |
38 | `gcc_jit_result *`. | |
39 | ||
7ef96183 | 40 | If the result is non-NULL, the caller becomes responsible for |
791cfef8 DM |
41 | calling :func:`gcc_jit_result_release` on it once they're done |
42 | with it. | |
35485da9 | 43 | |
fdce7209 DM |
44 | .. type:: gcc_jit_result |
45 | ||
46 | A `gcc_jit_result` encapsulates the result of compiling a context | |
47 | in-memory, and the lifetimes of any machine code functions or globals | |
dc44ee3a | 48 | that are within the result. |
fdce7209 | 49 | |
35485da9 DM |
50 | .. function:: void *\ |
51 | gcc_jit_result_get_code (gcc_jit_result *result,\ | |
52 | const char *funcname) | |
53 | ||
54 | Locate a given function within the built machine code. | |
81ba15f1 DM |
55 | |
56 | Functions are looked up by name. For this to succeed, a function | |
57 | with a name matching `funcname` must have been created on | |
58 | `result`'s context (or a parent context) via a call to | |
59 | :func:`gcc_jit_context_new_function` with `kind` | |
60 | :macro:`GCC_JIT_FUNCTION_EXPORTED`: | |
61 | ||
62 | .. code-block:: c | |
63 | ||
64 | gcc_jit_context_new_function (ctxt, | |
65 | any_location, /* or NULL */ | |
66 | /* Required for func to be visible to | |
67 | gcc_jit_result_get_code: */ | |
68 | GCC_JIT_FUNCTION_EXPORTED, | |
69 | any_return_type, | |
70 | /* Must string-compare equal: */ | |
71 | funcname, | |
72 | /* etc */); | |
73 | ||
74 | If such a function is not found (or `result` or `funcname` are | |
75 | ``NULL``), an error message will be emitted on stderr and | |
76 | ``NULL`` will be returned. | |
77 | ||
78 | If the function is found, the result will need to be cast to a | |
79 | function pointer of the correct type before it can be called. | |
80 | ||
81 | Note that the resulting machine code becomes invalid after | |
82 | :func:`gcc_jit_result_release` is called on the | |
85c943f3 | 83 | :expr:`gcc_jit_result *`; attempting to call it after that may lead |
81ba15f1 | 84 | to a segmentation fault. |
35485da9 | 85 | |
791cfef8 DM |
86 | .. function:: void *\ |
87 | gcc_jit_result_get_global (gcc_jit_result *result,\ | |
88 | const char *name) | |
89 | ||
90 | Locate a given global within the built machine code. | |
91 | ||
92 | Globals are looked up by name. For this to succeed, a global | |
93 | with a name matching `name` must have been created on | |
94 | `result`'s context (or a parent context) via a call to | |
95 | :func:`gcc_jit_context_new_global` with `kind` | |
96 | :macro:`GCC_JIT_GLOBAL_EXPORTED`. | |
97 | ||
98 | If the global is found, the result will need to be cast to a | |
99 | pointer of the correct type before it can be called. | |
100 | ||
68c994f9 | 101 | This is a *pointer* to the global, so e.g. for an :expr:`int` this is |
102 | an :expr:`int *`. | |
791cfef8 DM |
103 | |
104 | For example, given an ``int foo;`` created this way: | |
105 | ||
106 | .. code-block:: c | |
107 | ||
108 | gcc_jit_lvalue *exported_global = | |
109 | gcc_jit_context_new_global (ctxt, | |
110 | any_location, /* or NULL */ | |
111 | GCC_JIT_GLOBAL_EXPORTED, | |
112 | int_type, | |
113 | "foo"); | |
114 | ||
115 | we can access it like this: | |
116 | ||
117 | .. code-block:: c | |
118 | ||
119 | int *ptr_to_foo = | |
120 | (int *)gcc_jit_result_get_global (result, "foo"); | |
121 | ||
122 | If such a global is not found (or `result` or `name` are | |
123 | ``NULL``), an error message will be emitted on stderr and | |
124 | ``NULL`` will be returned. | |
125 | ||
126 | Note that the resulting address becomes invalid after | |
127 | :func:`gcc_jit_result_release` is called on the | |
85c943f3 | 128 | :expr:`gcc_jit_result *`; attempting to use it after that may lead |
791cfef8 | 129 | to a segmentation fault. |
35485da9 DM |
130 | |
131 | .. function:: void\ | |
132 | gcc_jit_result_release (gcc_jit_result *result) | |
133 | ||
134 | Once we're done with the code, this unloads the built .so file. | |
135 | This cleans up the result; after calling this, it's no longer | |
791cfef8 DM |
136 | valid to use the result, or any code or globals that were obtained |
137 | by calling :func:`gcc_jit_result_get_code` or | |
138 | :func:`gcc_jit_result_get_global` on it. | |
fdce7209 DM |
139 | |
140 | ||
141 | Ahead-of-time compilation | |
142 | ************************* | |
143 | ||
144 | Although libgccjit is primarily aimed at just-in-time compilation, it | |
145 | can also be used for implementing more traditional ahead-of-time | |
146 | compilers, via the :c:func:`gcc_jit_context_compile_to_file` | |
147 | API entrypoint. | |
148 | ||
aed0f014 PT |
149 | For linking in object files, use :c:func:`gcc_jit_context_add_driver_option`. |
150 | ||
fdce7209 DM |
151 | .. function:: void \ |
152 | gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, \ | |
153 | enum gcc_jit_output_kind output_kind,\ | |
154 | const char *output_path) | |
155 | ||
85c943f3 | 156 | Compile the :c:expr:`gcc_jit_context *` to a file of the given |
fdce7209 DM |
157 | kind. |
158 | ||
159 | :c:func:`gcc_jit_context_compile_to_file` ignores the suffix of | |
160 | ``output_path``, and insteads uses the given | |
ea1a4694 | 161 | :c:enum:`gcc_jit_output_kind` to decide what to do. |
fdce7209 DM |
162 | |
163 | .. note:: | |
164 | ||
165 | This is different from the ``gcc`` program, which does make use of the | |
166 | suffix of the output file when determining what to do. | |
167 | ||
ea1a4694 | 168 | .. enum:: gcc_jit_output_kind |
fdce7209 DM |
169 | |
170 | The available kinds of output are: | |
171 | ||
85cf5a23 | 172 | .. list-table:: |
173 | :header-rows: 1 | |
174 | ||
175 | * - Output kind | |
176 | - Typical suffix | |
177 | ||
178 | * - :c:macro:`GCC_JIT_OUTPUT_KIND_ASSEMBLER` | |
179 | - .s | |
180 | * - :c:macro:`GCC_JIT_OUTPUT_KIND_OBJECT_FILE` | |
181 | - .o | |
182 | * - :c:macro:`GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY` | |
183 | - .so or .dll | |
184 | * - :c:macro:`GCC_JIT_OUTPUT_KIND_EXECUTABLE` | |
185 | - None, or .exe | |
fdce7209 DM |
186 | |
187 | .. c:macro:: GCC_JIT_OUTPUT_KIND_ASSEMBLER | |
188 | ||
189 | Compile the context to an assembler file. | |
190 | ||
191 | .. c:macro:: GCC_JIT_OUTPUT_KIND_OBJECT_FILE | |
192 | ||
193 | Compile the context to an object file. | |
194 | ||
195 | .. c:macro:: GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY | |
196 | ||
197 | Compile the context to a dynamic library. | |
198 | ||
fdce7209 DM |
199 | .. c:macro:: GCC_JIT_OUTPUT_KIND_EXECUTABLE |
200 | ||
201 | Compile the context to an executable. |