|
150
|
1 ========================================
|
|
|
2 Kaleidoscope: Compiling to Object Code
|
|
|
3 ========================================
|
|
|
4
|
|
|
5 .. contents::
|
|
|
6 :local:
|
|
|
7
|
|
|
8 Chapter 8 Introduction
|
|
|
9 ======================
|
|
|
10
|
|
|
11 Welcome to Chapter 8 of the "`Implementing a language with LLVM
|
|
|
12 <index.html>`_" tutorial. This chapter describes how to compile our
|
|
|
13 language down to object files.
|
|
|
14
|
|
|
15 Choosing a target
|
|
|
16 =================
|
|
|
17
|
|
|
18 LLVM has native support for cross-compilation. You can compile to the
|
|
|
19 architecture of your current machine, or just as easily compile for
|
|
|
20 other architectures. In this tutorial, we'll target the current
|
|
|
21 machine.
|
|
|
22
|
|
|
23 To specify the architecture that you want to target, we use a string
|
|
|
24 called a "target triple". This takes the form
|
|
|
25 ``<arch><sub>-<vendor>-<sys>-<abi>`` (see the `cross compilation docs
|
|
173
|
26 <https://clang.llvm.org/docs/CrossCompilation.html#target-triple>`_).
|
|
150
|
27
|
|
|
28 As an example, we can see what clang thinks is our current target
|
|
|
29 triple:
|
|
|
30
|
|
|
31 ::
|
|
|
32
|
|
|
33 $ clang --version | grep Target
|
|
|
34 Target: x86_64-unknown-linux-gnu
|
|
|
35
|
|
|
36 Running this command may show something different on your machine as
|
|
|
37 you might be using a different architecture or operating system to me.
|
|
|
38
|
|
|
39 Fortunately, we don't need to hard-code a target triple to target the
|
|
|
40 current machine. LLVM provides ``sys::getDefaultTargetTriple``, which
|
|
|
41 returns the target triple of the current machine.
|
|
|
42
|
|
|
43 .. code-block:: c++
|
|
|
44
|
|
|
45 auto TargetTriple = sys::getDefaultTargetTriple();
|
|
|
46
|
|
|
47 LLVM doesn't require us to link in all the target
|
|
|
48 functionality. For example, if we're just using the JIT, we don't need
|
|
|
49 the assembly printers. Similarly, if we're only targeting certain
|
|
|
50 architectures, we can only link in the functionality for those
|
|
|
51 architectures.
|
|
|
52
|
|
|
53 For this example, we'll initialize all the targets for emitting object
|
|
|
54 code.
|
|
|
55
|
|
|
56 .. code-block:: c++
|
|
|
57
|
|
|
58 InitializeAllTargetInfos();
|
|
|
59 InitializeAllTargets();
|
|
|
60 InitializeAllTargetMCs();
|
|
|
61 InitializeAllAsmParsers();
|
|
|
62 InitializeAllAsmPrinters();
|
|
|
63
|
|
|
64 We can now use our target triple to get a ``Target``:
|
|
|
65
|
|
|
66 .. code-block:: c++
|
|
|
67
|
|
|
68 std::string Error;
|
|
|
69 auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
|
|
|
70
|
|
|
71 // Print an error and exit if we couldn't find the requested target.
|
|
|
72 // This generally occurs if we've forgotten to initialise the
|
|
|
73 // TargetRegistry or we have a bogus target triple.
|
|
|
74 if (!Target) {
|
|
|
75 errs() << Error;
|
|
|
76 return 1;
|
|
|
77 }
|
|
|
78
|
|
|
79 Target Machine
|
|
|
80 ==============
|
|
|
81
|
|
|
82 We will also need a ``TargetMachine``. This class provides a complete
|
|
|
83 machine description of the machine we're targeting. If we want to
|
|
|
84 target a specific feature (such as SSE) or a specific CPU (such as
|
|
|
85 Intel's Sandylake), we do so now.
|
|
|
86
|
|
|
87 To see which features and CPUs that LLVM knows about, we can use
|
|
|
88 ``llc``. For example, let's look at x86:
|
|
|
89
|
|
|
90 ::
|
|
|
91
|
|
|
92 $ llvm-as < /dev/null | llc -march=x86 -mattr=help
|
|
|
93 Available CPUs for this target:
|
|
|
94
|
|
|
95 amdfam10 - Select the amdfam10 processor.
|
|
|
96 athlon - Select the athlon processor.
|
|
|
97 athlon-4 - Select the athlon-4 processor.
|
|
|
98 ...
|
|
|
99
|
|
|
100 Available features for this target:
|
|
|
101
|
|
|
102 16bit-mode - 16-bit mode (i8086).
|
|
|
103 32bit-mode - 32-bit mode (80386).
|
|
|
104 3dnow - Enable 3DNow! instructions.
|
|
|
105 3dnowa - Enable 3DNow! Athlon instructions.
|
|
|
106 ...
|
|
|
107
|
|
|
108 For our example, we'll use the generic CPU without any additional
|
|
|
109 features, options or relocation model.
|
|
|
110
|
|
|
111 .. code-block:: c++
|
|
|
112
|
|
|
113 auto CPU = "generic";
|
|
|
114 auto Features = "";
|
|
|
115
|
|
|
116 TargetOptions opt;
|
|
252
|
117 auto RM = std::optional<Reloc::Model>();
|
|
150
|
118 auto TargetMachine = Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
|
|
|
119
|
|
|
120
|
|
|
121 Configuring the Module
|
|
|
122 ======================
|
|
|
123
|
|
|
124 We're now ready to configure our module, to specify the target and
|
|
|
125 data layout. This isn't strictly necessary, but the `frontend
|
|
|
126 performance guide <../Frontend/PerformanceTips.html>`_ recommends
|
|
|
127 this. Optimizations benefit from knowing about the target and data
|
|
|
128 layout.
|
|
|
129
|
|
|
130 .. code-block:: c++
|
|
|
131
|
|
|
132 TheModule->setDataLayout(TargetMachine->createDataLayout());
|
|
236
|
133 TheModule->setTargetTriple(TargetTriple);
|
|
|
134
|
|
150
|
135 Emit Object Code
|
|
|
136 ================
|
|
|
137
|
|
|
138 We're ready to emit object code! Let's define where we want to write
|
|
|
139 our file to:
|
|
|
140
|
|
|
141 .. code-block:: c++
|
|
|
142
|
|
|
143 auto Filename = "output.o";
|
|
|
144 std::error_code EC;
|
|
|
145 raw_fd_ostream dest(Filename, EC, sys::fs::OF_None);
|
|
|
146
|
|
|
147 if (EC) {
|
|
|
148 errs() << "Could not open file: " << EC.message();
|
|
|
149 return 1;
|
|
|
150 }
|
|
|
151
|
|
|
152 Finally, we define a pass that emits object code, then we run that
|
|
|
153 pass:
|
|
|
154
|
|
|
155 .. code-block:: c++
|
|
|
156
|
|
|
157 legacy::PassManager pass;
|
|
|
158 auto FileType = CGFT_ObjectFile;
|
|
|
159
|
|
|
160 if (TargetMachine->addPassesToEmitFile(pass, dest, nullptr, FileType)) {
|
|
|
161 errs() << "TargetMachine can't emit a file of this type";
|
|
|
162 return 1;
|
|
|
163 }
|
|
|
164
|
|
|
165 pass.run(*TheModule);
|
|
|
166 dest.flush();
|
|
|
167
|
|
|
168 Putting It All Together
|
|
|
169 =======================
|
|
|
170
|
|
|
171 Does it work? Let's give it a try. We need to compile our code, but
|
|
|
172 note that the arguments to ``llvm-config`` are different to the previous chapters.
|
|
|
173
|
|
|
174 ::
|
|
|
175
|
|
|
176 $ clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs all` -o toy
|
|
|
177
|
|
|
178 Let's run it, and define a simple ``average`` function. Press Ctrl-D
|
|
|
179 when you're done.
|
|
|
180
|
|
|
181 ::
|
|
236
|
182
|
|
150
|
183 $ ./toy
|
|
|
184 ready> def average(x y) (x + y) * 0.5;
|
|
|
185 ^D
|
|
|
186 Wrote output.o
|
|
|
187
|
|
|
188 We have an object file! To test it, let's write a simple program and
|
|
|
189 link it with our output. Here's the source code:
|
|
|
190
|
|
|
191 .. code-block:: c++
|
|
|
192
|
|
|
193 #include <iostream>
|
|
|
194
|
|
|
195 extern "C" {
|
|
|
196 double average(double, double);
|
|
|
197 }
|
|
|
198
|
|
|
199 int main() {
|
|
|
200 std::cout << "average of 3.0 and 4.0: " << average(3.0, 4.0) << std::endl;
|
|
|
201 }
|
|
|
202
|
|
|
203 We link our program to output.o and check the result is what we
|
|
|
204 expected:
|
|
|
205
|
|
|
206 ::
|
|
|
207
|
|
|
208 $ clang++ main.cpp output.o -o main
|
|
|
209 $ ./main
|
|
|
210 average of 3.0 and 4.0: 3.5
|
|
|
211
|
|
|
212 Full Code Listing
|
|
|
213 =================
|
|
|
214
|
|
|
215 .. literalinclude:: ../../../examples/Kaleidoscope/Chapter8/toy.cpp
|
|
|
216 :language: c++
|
|
|
217
|
|
|
218 `Next: Adding Debug Information <LangImpl09.html>`_
|
