1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
.. Copyright 2014-2015 David Malcolm <dmalcolm@redhat.com>
Copyright 2014-2015 Red Hat, Inc.
This is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see
<http://www.gnu.org/licenses/>.
Compiling a context
===================
Once populated, a :py:class:`gccjit.Context` can be compiled to
machine code, either in-memory via :py:meth:`gccjit.Context.compile` or
to disk via :py:meth:`gccjit.Context.compile_to_file`.
You can compile a context multiple times (using either form of
compilation), although any errors that occur on the context will
prevent any future compilation of that context.
In-memory compilation
*********************
.. py:method:: gccjit.Context.compile(self)
:rtype: :py:class:`gccjit.Result`
This calls into GCC and builds the code, returning a
:py:class:`gccjit.Result`.
.. py:class:: gccjit.Result
A :py:class:`gccjit.Result` encapsulates the result of compiling a
:py:class:`gccjit.Context` in-memory, and the lifetimes of any
machine code functions or globals that are within the result.
.. py:method:: get_code(funcname)
Locate the given function within the built machine code.
Functions are looked up by name. For this to succeed, a function
with a name matching `funcname` must have been created on
`result`'s context (or a parent context) via a call to
:py:meth:`gccjit.Context.new_function` with `kind`
:py:data:`gccjit.FunctionKind.EXPORTED`.
.. error-handling?
The returned value is an
`int`, actually a pointer to the machine code within the
address space of the process. This will need to be wrapped up
with `ctypes` to be callable::
import ctypes
# "[int] -> int" functype:
int_int_func_type = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_int)
code = int_int_func_type(jit_result.get_code(b"square"))
assert code(5) == 25
The code has the same lifetime as the :py:class:`gccjit.Result`
instance; the pointer becomes invalid when the result instance
is cleaned up.
.. TODO: gcc_jit_result_get_global
Ahead-of-time compilation
*************************
Although libgccjit is primarily aimed at just-in-time compilation, it
can also be used for implementing more traditional ahead-of-time
compilers, via the :py:meth:`gccjit.Context.compile_to_file`
API entrypoint.
.. py:method:: gccjit.Context.compile_to_file(self, kind, path)
Compile the context to a file of the given
kind::
ctxt.compile_to_file(gccjit.OutputKind.EXECUTABLE,
'a.out')
:py:meth:`gccjit.Context.compile_to_file` ignores the suffix of
``path``, and insteads uses `kind` to decide what to do.
.. note::
This is different from the ``gcc`` program, which does make use of the
suffix of the output file when determining what to do.
The available kinds of output are:
============================================ ==============
Output kind Typical suffix
============================================ ==============
:py:data:`gccjit.OutputKind.ASSEMBLER` .s
:py:data:`gccjit.OutputKind.OBJECT_FILE` .o
:py:data:`gccjit.OutputKind.DYNAMIC_LIBRARY` .so or .dll
:py:data:`gccjit.OutputKind.EXECUTABLE` None, or .exe
============================================ ==============
.. py:class:: gccjit.OutputKind
.. py:data:: ASSEMBLER
Compile the context to an assembler file.
.. py:data:: OBJECT_FILE
Compile the context to an object file.
.. py:data:: DYNAMIC_LIBRARY
Compile the context to a dynamic library.
There is currently no support for specifying other libraries to link
against.
.. py:data:: EXECUTABLE
Compile the context to an executable.
There is currently no support for specifying libraries to link
against.
|
