1.. Copyright (C) 2014-2020 Free Software Foundation, Inc.
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
20Compiling a context
21===================
22
23Once populated, a :c:type:`gcc_jit_context *` can be compiled to
24machine code, either in-memory via :c:func:`gcc_jit_context_compile` or
25to disk via :c:func:`gcc_jit_context_compile_to_file`.
26
27You can compile a context multiple times (using either form of
28compilation), although any errors that occur on the context will
29prevent any future compilation of that context.
30
31In-memory compilation
32*********************
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
40   If the result is non-NULL, the caller becomes responsible for
41   calling :func:`gcc_jit_result_release` on it once they're done
42   with it.
43
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
48  that are within the result.
49
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.
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
83   :type:`gcc_jit_result *`; attempting to call it after that may lead
84   to a segmentation fault.
85
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.
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
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.
139
140
141Ahead-of-time compilation
142*************************
143
144Although libgccjit is primarily aimed at just-in-time compilation, it
145can also be used for implementing more traditional ahead-of-time
146compilers, via the :c:func:`gcc_jit_context_compile_to_file`
147API 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
168The available kinds of output are:
169
170==============================================  ==============
171Output 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.
200