]>
Commit | Line | Data |
---|---|---|
179ed8f5 | 1 | .. Copyright (C) 2014-2015 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 | |
16 | <http://www.gnu.org/licenses/>. | |
17 | ||
18 | .. default-domain:: c | |
19 | ||
fdce7209 | 20 | Compiling a context |
35485da9 DM |
21 | =================== |
22 | ||
fdce7209 DM |
23 | Once populated, a :c:type:`gcc_jit_context *` can be compiled to |
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 | ||
791cfef8 DM |
40 | If this is non-NULL, the caller becomes responsible for |
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 | |
791cfef8 | 83 | :type:`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 | ||
101 | This is a *pointer* to the global, so e.g. for an :c:type:`int` this is | |
102 | an :c:type:`int *`. | |
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 | |
128 | :type:`gcc_jit_result *`; attempting to use it after that may lead | |
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 | ||
149 | .. function:: void \ | |
150 | gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, \ | |
151 | enum gcc_jit_output_kind output_kind,\ | |
152 | const char *output_path) | |
153 | ||
154 | Compile the :c:type:`gcc_jit_context *` to a file of the given | |
155 | kind. | |
156 | ||
157 | :c:func:`gcc_jit_context_compile_to_file` ignores the suffix of | |
158 | ``output_path``, and insteads uses the given | |
159 | :c:type:`enum gcc_jit_output_kind` to decide what to do. | |
160 | ||
161 | .. note:: | |
162 | ||
163 | This is different from the ``gcc`` program, which does make use of the | |
164 | suffix of the output file when determining what to do. | |
165 | ||
166 | .. type:: enum gcc_jit_output_kind | |
167 | ||
168 | The available kinds of output are: | |
169 | ||
170 | ============================================== ============== | |
171 | Output kind Typical suffix | |
172 | ============================================== ============== | |
173 | :c:macro:`GCC_JIT_OUTPUT_KIND_ASSEMBLER` .s | |
174 | :c:macro:`GCC_JIT_OUTPUT_KIND_OBJECT_FILE` .o | |
175 | :c:macro:`GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY` .so or .dll | |
176 | :c:macro:`GCC_JIT_OUTPUT_KIND_EXECUTABLE` None, or .exe | |
177 | ============================================== ============== | |
178 | ||
179 | .. c:macro:: GCC_JIT_OUTPUT_KIND_ASSEMBLER | |
180 | ||
181 | Compile the context to an assembler file. | |
182 | ||
183 | .. c:macro:: GCC_JIT_OUTPUT_KIND_OBJECT_FILE | |
184 | ||
185 | Compile the context to an object file. | |
186 | ||
187 | .. c:macro:: GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY | |
188 | ||
189 | Compile the context to a dynamic library. | |
190 | ||
191 | There is currently no support for specifying other libraries to link | |
192 | against. | |
193 | ||
194 | .. c:macro:: GCC_JIT_OUTPUT_KIND_EXECUTABLE | |
195 | ||
196 | Compile the context to an executable. | |
197 | ||
198 | There is currently no support for specifying libraries to link | |
199 | against. |