Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 96b5f7113a10dd34b56b5ca5f7bda49072b2fc8c / . / docs / GettingStartedVS.html
blob: 40b187737d13eaaf949539d70979104c7b1faf35 [file] [log] [blame]
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>Getting Started with LLVM System for Microsoft Visual Studio</title>
7 <link rel="stylesheet" href="llvm.css" type="text/css">
8</head>
9<body>
10
11<div class="doc_title">
12 Getting Started with the LLVM System using Microsoft Visual Studio
13</div>
14
15<ul>
16 <li><a href="#overview">Overview</a>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]17 <li><a href="#requirements">Requirements</a>
18 <ol>
19 <li><a href="#hardware">Hardware</a>
20 <li><a href="#software">Software</a>
21 </ol></li>
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]22 <li><a href="#quickstart">Getting Started</a>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]23 <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
24 <li><a href="#problems">Common Problems</a>
25 <li><a href="#links">Links</a>
26</ul>
27
28<div class="doc_author">
29 <p>Written by:
Jeff Cohenb9a47d12005-02-01 15:59:28 +0000[diff] [blame]30 <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]31 </p>
32</div>
33
34
35<!-- *********************************************************************** -->
36<div class="doc_section">
37 <a name="overview"><b>Overview</b></a>
38</div>
39<!-- *********************************************************************** -->
40
41<div class="doc_text">
42
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]43 <p>The Visual Studio port has some limitations. It is suitable for
44 use if you are writing your own compiler front end or otherwise have a
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]45 need to dynamically generate machine code. The JIT and interpreter are
Jeff Cohenca0a9092005-03-08 03:56:50 +0000[diff] [blame]46 functional, but it is currently not possible to generate assembly code which
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]47 is then assembled into an executable. You can output object files
48 in COFF format, though. You can also indirectly create executables
49 by using the C backend.</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]50
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]51 <p><tt>llvm-gcc</tt> is based on GCC, which cannot be bootstrapped
52 using VC++. There are <tt>llvm-gcc</tt> binaries based on MinGW
53 available on the
54 LLVM <a href="http://www.llvm.org/releases/download.html"> download
55 page</a>. Eventually, <a href="http://clang.llvm.org">Clang</a>
56 will be able to produce executables on Windows.</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]57
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]58 <p><tt>bugpoint</tt> does build, but does not work. The other tools
59 'should' work, but have not been fully tested.</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]60
61 <p>Additional information about the LLVM directory structure and tool chain
62 can be found on the main <a href="GettingStarted.html">Getting Started</a>
Nick Lewycky28ea4f62008-12-08 00:45:02 +0000[diff] [blame]63 page.</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]64
65</div>
66
67<!-- *********************************************************************** -->
68<div class="doc_section">
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]69 <a name="requirements"><b>Requirements</b></a>
70</div>
71<!-- *********************************************************************** -->
72
73<div class="doc_text">
74
75 <p>Before you begin to use the LLVM system, review the requirements given
76 below. This may save you some trouble by knowing ahead of time what hardware
77 and software you will need.</p>
78
79</div>
80
81<!-- ======================================================================= -->
82<div class="doc_subsection">
83 <a name="hardware"><b>Hardware</b></a>
84</div>
85
86<div class="doc_text">
87
Nick Lewycky28ea4f62008-12-08 00:45:02 +0000[diff] [blame]88 <p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine.
89 The LLVM source tree and object files, libraries and executables will consume
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]90 approximately 3GB.</p>
91
92</div>
93
94<!-- ======================================================================= -->
95<div class="doc_subsection"><a name="software"><b>Software</b></a></div>
96<div class="doc_text">
97
Nick Lewycky28ea4f62008-12-08 00:45:02 +0000[diff] [blame]98 <p>You will need Visual Studio .NET 2005 SP1 or higher. The VS2005 SP1
99 beta and the normal VS2005 still have bugs that are not completely
100 compatible. VS2003 would work except (at last check) it has a bug with
101 friend classes that you can work-around with some minor code rewriting
102 (and please submit a patch if you do). Earlier versions of Visual Studio
103 do not support the C++ standard well enough and will not work.</p>
104
105 <p>You will also need the <a href="http://www.cmake.org/">CMake</a> build
106 system since it generates the project files you will use to build with.</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]107
Chris Lattnerc2bb1232007-11-14 07:04:44 +0000[diff] [blame]108 <p>
109 Do not install the LLVM directory tree into a path containing spaces (e.g.
110 C:\Documents and Settings\...) as the configure step will fail.</p>
111
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]112</div>
113
114<!-- *********************************************************************** -->
115<div class="doc_section">
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]116 <a name="quickstart"><b>Getting Started</b></a>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]117</div>
118<!-- *********************************************************************** -->
119
120<div class="doc_text">
121
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]122<p>Here's the short story for getting up and running quickly with LLVM:</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]123
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]124<ol>
125 <li>Read the documentation.</li>
126 <li>Seriously, read the documentation.</li>
127 <li>Remember that you were warned twice about reading the documentation.</li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]128
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]129 <li>Get the Source Code
130 <ul>
131 <li>With the distributed files:
132 <ol>
133 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
134 <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
135 <i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;or use WinZip</i>
136 <li><tt>cd llvm</tt></li>
137 </ol></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]138
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]139 <li>With anonymous Subversion access:
140 <ol>
141 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
142 <li><tt>svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top
143 </tt></li>
144 <li><tt>make checkout MODULE=llvm</tt>
145 <li><tt>cd llvm</tt></li>
146 </ol></li>
147 </ul></li>
148
149 <li> Use <a href="http://www.cmake.org/">CMake</a> to generate up-to-date
150 project files:
151 <ul>
152 <li>Once CMake is installed then the most simple way is to just
153 start the CMake GUI, select the directory where you have LLVM
154 extracted to, and the default options should all be fine. One
155 option you may really want to change, regardless of anything
156 else, might be the CMAKE_INSTALL_PREFIX setting to select a
157 directory to INSTALL to once compiling is complete, although
158 installation is not mandatory for using LLVM. Another
159 important option is LLVM_TARGETS_TO_BUILD, which controls the
160 LLVM target architectures that are included on the build. If
161 you want to run the <a href="#tutorial">example described
162 below</a> you must set that variable to "X86;CBackend".</li>
163 <li>See the <a href="CMake.html">LLVM CMake guide</a> for
164 detailed information about how to configure the LLVM
165 build.</li>
166 </ul>
167 </li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]168
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]169 <li>Start Visual Studio
170 <ul>
171 <li>In the directory you created the project files will have
172 an <tt>llvm.sln</tt> file, just double-click on that to open
173 Visual Studio.</li>
174 </ul></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]175
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]176 <li>Build the LLVM Suite:
177 <ul>
178 <li>The projects may still be built individually, but
179 to build them all do not just select all of them in batch build (as some
180 are meant as configuration projects), but rather select and build just
181 the ALL_BUILD project to build everything, or the INSTALL project, which
182 first builds the ALL_BUILD project, then installs the LLVM headers, libs,
183 and other useful things to the directory set by the CMAKE_INSTALL_PREFIX
184 setting when you first configured CMake.</li>
185 <li>The Fibonacci project is a sample program that uses the JIT.
186 Modify the project's debugging properties to provide a numeric
187 command line argument or run it from the command line. The
188 program will print the corresponding fibonacci value.</li>
189 </ul></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]190
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]191</ol>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]192
193</div>
194
195<!-- *********************************************************************** -->
196<div class="doc_section">
197 <a name="tutorial">An Example Using the LLVM Tool Chain</a>
198</div>
199<!-- *********************************************************************** -->
200
201<div class="doc_text">
202
203<ol>
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]204 <li><p>First, create a simple C file, name it 'hello.c':</p>
205
206<div class="doc_code">
207<pre>
208#include &lt;stdio.h&gt;
209int main() {
210 printf("hello world\n");
211 return 0;
212}
213</pre></div></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]214
Gabor Greif04367bf2007-07-06 22:07:22 +0000[diff] [blame]215 <li><p>Next, compile the C file into a LLVM bitcode file:</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]216
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]217<div class="doc_code">
218<pre>
219% llvm-gcc -c hello.c -emit-llvm -o hello.bc
220</pre>
221</div>
222
223 <p>This will create the result file <tt>hello.bc</tt> which is the LLVM
224 bitcode that corresponds the the compiled program and the library
225 facilities that it required. You can execute this file directly using
226 <tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>,
227 optimize or analyze it further with the <tt>opt</tt> tool, etc.</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]228
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]229 <p><b>Note: you will need the llvm-gcc binaries from the
230 LLVM <a href="http://www.llvm.org/releases/download.html">
231 download page</a></b></p></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]232
Jeff Cohena0887342005-10-30 21:00:24 +0000[diff] [blame]233 <li><p>Run the program using the just-in-time compiler:</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]234
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]235<div class="doc_code">
236<pre>
237% lli hello.bc
238</pre>
239</div>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]240
Jeff Cohen3c8dfcd2007-03-28 20:27:51 +0000[diff] [blame]241 <p>Note: this will only work for trivial C programs. Non-trivial programs
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]242 (and any C++ program) will have dependencies on the GCC runtime that
243 won't be satisfied by the Microsoft runtime libraries.</p></li>
Jeff Cohen3c8dfcd2007-03-28 20:27:51 +0000[diff] [blame]244
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]245 <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
246 code:</p>
247
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]248<div class="doc_code">
249<pre>
250% llvm-dis &lt; hello.bc | more
251</pre>
252</div></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]253
Jeff Cohena0887342005-10-30 21:00:24 +0000[diff] [blame]254 <li><p>Compile the program to C using the LLC code generator:</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]255
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]256<div class="doc_code">
257<pre>
258% llc -march=c hello.bc
259</pre>
Oscar Fuentes96b5f712010-09-17 02:17:13 +0000[diff] [blame^]260
261 <p><b>Note: you need to add the C backend to the LLVM build,
262 which amounts to setting the CMake
263 variable <i>LLVM_TARGETS_TO_BUILD</i> to "X86;CBackend" when
264 you generate the VS solution files. See
265 the <a href="CMake.html">LLVM CMake guide</a> for more
266 information about how to configure the LLVM
267 build.</b></p></li>
268
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]269</div></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]270
Jeff Cohena0887342005-10-30 21:00:24 +0000[diff] [blame]271 <li><p>Compile to binary using Microsoft C:</p>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]272
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]273<div class="doc_code">
274<pre>
275% cl hello.cbe.c
276</pre>
277</div>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]278
Bill Wendlingbc14dd32009-03-28 10:24:15 +0000[diff] [blame]279 <p>Note: this will only work for trivial C programs. Non-trivial programs
280 (and any C++ program) will have dependencies on the GCC runtime that won't
281 be satisfied by the Microsoft runtime libraries.</p></li>
Jeff Cohen3c8dfcd2007-03-28 20:27:51 +0000[diff] [blame]282
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]283 <li><p>Execute the native code program:</p>
284
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]285<div class="doc_code">
286<pre>
287% hello.cbe.exe
288</pre>
289</div></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]290</ol>
291
292</div>
293
294<!-- *********************************************************************** -->
295<div class="doc_section">
296 <a name="problems">Common Problems</a>
297</div>
298<!-- *********************************************************************** -->
299
300<div class="doc_text">
301
302<p>If you are having problems building or using LLVM, or if you have any other
303general questions about LLVM, please consult the <a href="FAQ.html">Frequently
304Asked Questions</a> page.</p>
305
306</div>
307
308<!-- *********************************************************************** -->
309<div class="doc_section">
310 <a name="links">Links</a>
311</div>
312<!-- *********************************************************************** -->
313
314<div class="doc_text">
315
316<p>This document is just an <b>introduction</b> to how to use LLVM to do
317some simple things... there are many more interesting and complicated things
318that you can do that aren't documented here (but we'll gladly accept a patch
319if you want to write something up!). For more information about LLVM, check
320out:</p>
321
322<ul>
Reid Spencer05fe4b02006-03-14 05:39:39 +0000[diff] [blame]323 <li><a href="http://llvm.org/">LLVM homepage</a></li>
324 <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
325 <li><a href="http://llvm.org/docs/Projects.html">Starting a Project
Bill Wendling03c993a2007-09-22 09:39:19 +0000[diff] [blame]326 that Uses LLVM</a></li>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]327</ul>
328
329</div>
330
331<!-- *********************************************************************** -->
332
333<hr>
334<address>
335 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]336 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]337 <a href="http://validator.w3.org/check/referer"><img
Misha Brukmanf00ddb02008-12-11 18:23:24 +0000[diff] [blame]338 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]339
Jeff Cohenb9a47d12005-02-01 15:59:28 +0000[diff] [blame]340 <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a><br>
Reid Spencer05fe4b02006-03-14 05:39:39 +0000[diff] [blame]341 <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
Jeff Cohen7a4f03d2005-01-31 05:42:10 +0000[diff] [blame]342 Last modified: $Date$
343</address>
344</body>
345</html>