1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
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">
12 Getting Started with the LLVM System using Microsoft Visual Studio
16 <li><a href="#overview">Overview</a>
17 <li><a href="#requirements">Requirements</a>
19 <li><a href="#hardware">Hardware</a>
20 <li><a href="#software">Software</a>
22 <li><a href="#quickstart">Getting Started</a>
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>
28 <div class="doc_author">
29 <p>Written by: <a href="http://llvm.org/">The LLVM Team</a></p>
33 <!-- *********************************************************************** -->
35 <a name="overview"><b>Overview</b></a>
37 <!-- *********************************************************************** -->
41 <p>Welcome to LLVM on Windows! This document only covers LLVM on Windows using
42 Visual Studio, not mingw or cygwin. In order to get started, you first need to
43 know some basic information.</p>
45 <p>There are many different projects that compose LLVM. The first is the LLVM
46 suite. This contains all of the tools, libraries, and header files needed to
47 use the low level virtual machine. It contains an assembler, disassembler,
48 bitcode analyzer and bitcode optimizer. It also contains a test suite that can
49 be used to test the LLVM tools.</p>
51 <p>Another useful project on Windows is
52 <a href="http://clang.llvm.org/">clang</a>. Clang is a C family
53 ([Objective]C/C++) compiler. Clang mostly works on Windows, but does not
54 currently understand all of the Microsoft extensions to C and C++. Because of
55 this, clang cannot parse the C++ standard library included with Visual Studio,
56 nor parts of the Windows Platform SDK. However, most standard C programs do
57 compile. Clang can be used to emit bitcode, directly emit object files or
58 even linked executables using Visual Studio's <tt>link.exe</tt></p>
60 <p>The large LLVM test suite cannot be run on the Visual Studio port at this
63 <p>Most of the tools build and work. <tt>bugpoint</tt> does build, but does
66 <p>Additional information about the LLVM directory structure and tool chain
67 can be found on the main <a href="GettingStarted.html">Getting Started</a>
72 <!-- *********************************************************************** -->
74 <a name="requirements"><b>Requirements</b></a>
76 <!-- *********************************************************************** -->
80 <p>Before you begin to use the LLVM system, review the requirements given
81 below. This may save you some trouble by knowing ahead of time what hardware
82 and software you will need.</p>
84 <!-- ======================================================================= -->
86 <a name="hardware"><b>Hardware</b></a>
91 <p>Any system that can adequately run Visual Studio 2008 is fine. The LLVM
92 source tree and object files, libraries and executables will consume
93 approximately 3GB.</p>
97 <!-- ======================================================================= -->
98 <h3><a name="software"><b>Software</b></a></h3>
101 <p>You will need Visual Studio 2008 or higher. Earlier versions of Visual
102 Studio have bugs, are not completely compatible, or do not support the C++
103 standard well enough.</p>
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>
108 <p>If you would like to run the LLVM tests you will need
109 <a href="http://www.python.org/">Python</a>. Versions 2.4-2.7 are known to
110 work. You will need <a href="http://gnuwin32.sourceforge.net/">"GnuWin32"</a>
113 <p>Do not install the LLVM directory tree into a path containing spaces (e.g.
114 C:\Documents and Settings\...) as the configure step will fail.</p>
120 <!-- *********************************************************************** -->
122 <a name="quickstart"><b>Getting Started</b></a>
124 <!-- *********************************************************************** -->
128 <p>Here's the short story for getting up and running quickly with LLVM:</p>
131 <li>Read the documentation.</li>
132 <li>Seriously, read the documentation.</li>
133 <li>Remember that you were warned twice about reading the documentation.</li>
135 <li>Get the Source Code
137 <li>With the distributed files:
139 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
140 <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
141 <i> or use WinZip</i>
142 <li><tt>cd llvm</tt></li>
145 <li>With anonymous Subversion access:
147 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
148 <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
149 <li><tt>cd llvm</tt></li>
153 <li> Use <a href="http://www.cmake.org/">CMake</a> to generate up-to-date
156 <li>Once CMake is installed then the simplest way is to just start the
157 CMake GUI, select the directory where you have LLVM extracted to, and the
158 default options should all be fine. One option you may really want to
159 change, regardless of anything else, might be the CMAKE_INSTALL_PREFIX
160 setting to select a directory to INSTALL to once compiling is complete,
161 although installation is not mandatory for using LLVM. Another important
162 option is LLVM_TARGETS_TO_BUILD, which controls the LLVM target
163 architectures that are included on the build.
164 <li>See the <a href="CMake.html">LLVM CMake guide</a> for
165 detailed information about how to configure the LLVM
170 <li>Start Visual Studio
172 <li>In the directory you created the project files will have
173 an <tt>llvm.sln</tt> file, just double-click on that to open
177 <li>Build the LLVM Suite:
179 <li>The projects may still be built individually, but
180 to build them all do not just select all of them in batch build (as some
181 are meant as configuration projects), but rather select and build just
182 the ALL_BUILD project to build everything, or the INSTALL project, which
183 first builds the ALL_BUILD project, then installs the LLVM headers, libs,
184 and other useful things to the directory set by the CMAKE_INSTALL_PREFIX
185 setting when you first configured CMake.</li>
186 <li>The Fibonacci project is a sample program that uses the JIT.
187 Modify the project's debugging properties to provide a numeric
188 command line argument or run it from the command line. The
189 program will print the corresponding fibonacci value.</li>
192 <li>Test LLVM on Visual Studio:
194 <li>If %PATH% does not contain GnuWin32, you may specify LLVM_LIT_TOOLS_DIR
195 on CMake for the path to GnuWin32.</li>
196 <li>You can run LLVM tests by merely building the project
197 "check". The test results will be shown in the VS output
202 <!-- FIXME: Is it up-to-date? -->
205 <li>The LLVM tests can be run by <tt>cd</tt>ing to the llvm source directory
208 <div class="doc_code">
214 <p>Note that quite a few of these test will fail.</p>
217 <li>A specific test or test directory can be run with:
219 <div class="doc_code">
221 % llvm-lit test/path/to/test
230 <!-- *********************************************************************** -->
232 <a name="tutorial">An Example Using the LLVM Tool Chain</a>
234 <!-- *********************************************************************** -->
239 <li><p>First, create a simple C file, name it 'hello.c':</p>
241 <div class="doc_code">
243 #include <stdio.h>
245 printf("hello world\n");
250 <li><p>Next, compile the C file into a LLVM bitcode file:</p>
252 <div class="doc_code">
254 % clang -c hello.c -emit-llvm -o hello.bc
258 <p>This will create the result file <tt>hello.bc</tt> which is the LLVM
259 bitcode that corresponds the the compiled program and the library
260 facilities that it required. You can execute this file directly using
261 <tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>,
262 optimize or analyze it further with the <tt>opt</tt> tool, etc.</p>
264 <p>Alternatively you can directly output an executable with clang with:
267 <div class="doc_code">
269 % clang hello.c -o hello.exe
273 <p>The <tt>-o hello.exe</tt> is required because clang currently outputs
274 <tt>a.out</tt> when neither <tt>-o</tt> nor <tt>-c</tt> are given.</p>
276 <li><p>Run the program using the just-in-time compiler:</p>
278 <div class="doc_code">
284 <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
287 <div class="doc_code">
289 % llvm-dis < hello.bc | more
293 <li><p>Compile the program to object code using the LLC code generator:</p>
295 <div class="doc_code">
297 % llc -filetype=obj hello.bc
301 <li><p>Link to binary using Microsoft link:</p>
303 <div class="doc_code">
305 % link hello.obj -defaultlib:libcmt
309 <li><p>Execute the native code program:</p>
311 <div class="doc_code">
320 <!-- *********************************************************************** -->
322 <a name="problems">Common Problems</a>
324 <!-- *********************************************************************** -->
328 <p>If you are having problems building or using LLVM, or if you have any other
329 general questions about LLVM, please consult the <a href="FAQ.html">Frequently
330 Asked Questions</a> page.</p>
334 <!-- *********************************************************************** -->
336 <a name="links">Links</a>
338 <!-- *********************************************************************** -->
342 <p>This document is just an <b>introduction</b> to how to use LLVM to do
343 some simple things... there are many more interesting and complicated things
344 that you can do that aren't documented here (but we'll gladly accept a patch
345 if you want to write something up!). For more information about LLVM, check
349 <li><a href="http://llvm.org/">LLVM homepage</a></li>
350 <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
355 <!-- *********************************************************************** -->
359 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
360 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
361 <a href="http://validator.w3.org/check/referer"><img
362 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
364 <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
365 Last modified: $Date$