Home | History | Annotate | Download | only in docs
      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 <h1>
     12   Getting Started with the LLVM System using Microsoft Visual Studio
     13 </h1>
     14 
     15 <ul>
     16   <li><a href="#overview">Overview</a>
     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>
     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>
     26 </ul>
     27 
     28 <div class="doc_author">
     29   <p>Written by: <a href="http://llvm.org/">The LLVM Team</a></p>
     30 </div>
     31 
     32 
     33 <!-- *********************************************************************** -->
     34 <h2>
     35   <a name="overview"><b>Overview</b></a>
     36 </h2>
     37 <!-- *********************************************************************** -->
     38 
     39 <div>
     40 
     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>
     44 
     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>
     50 
     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>
     59 
     60   <p>The large LLVM test suite cannot be run on the Visual Studio port at this
     61   time.</p>
     62 
     63   <p>Most of the tools build and work.  <tt>bugpoint</tt> does build, but does
     64   not work.</p>
     65 
     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>
     68   page.</p>
     69 
     70 </div>
     71 
     72 <!-- *********************************************************************** -->
     73 <h2>
     74   <a name="requirements"><b>Requirements</b></a>
     75 </h2>
     76 <!-- *********************************************************************** -->
     77 
     78 <div>
     79 
     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>
     83 
     84 <!-- ======================================================================= -->
     85 <h3>
     86   <a name="hardware"><b>Hardware</b></a>
     87 </h3>
     88 
     89 <div>
     90 
     91   <p>Any system that can adequately run Visual Studio .NET 2005 SP1 is fine.
     92   The LLVM source tree and object files, libraries and executables will consume
     93   approximately 3GB.</p>
     94 
     95 </div>
     96 
     97 <!-- ======================================================================= -->
     98 <h3><a name="software"><b>Software</b></a></h3>
     99 <div>
    100 
    101   <p>You will need Visual Studio .NET 2005 SP1 or higher.  The VS2005 SP1
    102   beta and the normal VS2005 still have bugs that are not completely
    103   compatible.  Earlier versions of Visual Studio do not support the C++ standard
    104   well enough and will not work.</p>
    105 
    106   <p>You will also need the <a href="http://www.cmake.org/">CMake</a> build
    107   system since it generates the project files you will use to build with.</p>
    108 
    109   <p>If you would like to run the LLVM tests you will need
    110   <a href="http://www.python.org/">Python</a>. Versions 2.4-2.7 are known to
    111   work. You will need <a href="http://gnuwin32.sourceforge.net/">"GnuWin32"</a>
    112   tools, too.</p>
    113 
    114   <p>Do not install the LLVM directory tree into a path containing spaces (e.g.
    115   C:\Documents and Settings\...) as the configure step will fail.</p>
    116 
    117 </div>
    118 
    119 </div>
    120 
    121 <!-- *********************************************************************** -->
    122 <h2>
    123   <a name="quickstart"><b>Getting Started</b></a>
    124 </h2>
    125 <!-- *********************************************************************** -->
    126 
    127 <div>
    128 
    129 <p>Here's the short story for getting up and running quickly with LLVM:</p>
    130 
    131 <ol>
    132   <li>Read the documentation.</li>
    133   <li>Seriously, read the documentation.</li>
    134   <li>Remember that you were warned twice about reading the documentation.</li>
    135 
    136   <li>Get the Source Code
    137   <ul>
    138     <li>With the distributed files:
    139     <ol>
    140       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
    141       <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
    142       <i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;or use WinZip</i>
    143       <li><tt>cd llvm</tt></li>
    144     </ol></li>
    145 
    146     <li>With anonymous Subversion access:
    147     <ol>
    148       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
    149       <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
    150       <li><tt>cd llvm</tt></li>
    151     </ol></li>
    152   </ul></li>
    153 
    154   <li> Use <a href="http://www.cmake.org/">CMake</a> to generate up-to-date
    155     project files:
    156     <ul>
    157       <li>Once CMake is installed then the simplest way is to just start the
    158         CMake GUI, select the directory where you have LLVM extracted to, and the
    159         default options should all be fine.  One option you may really want to
    160         change, regardless of anything else, might be the CMAKE_INSTALL_PREFIX
    161         setting to select a directory to INSTALL to once compiling is complete,
    162         although installation is not mandatory for using LLVM.  Another important
    163         option is LLVM_TARGETS_TO_BUILD, which controls the LLVM target
    164         architectures that are included on the build.
    165       <li>See the <a href="CMake.html">LLVM CMake guide</a> for
    166         detailed information about how to configure the LLVM
    167         build.</li>
    168     </ul>
    169   </li>
    170 
    171   <li>Start Visual Studio
    172   <ul>
    173     <li>In the directory you created the project files will have
    174     an <tt>llvm.sln</tt> file, just double-click on that to open
    175     Visual Studio.</li>
    176   </ul></li>
    177 
    178   <li>Build the LLVM Suite:
    179   <ul>
    180     <li>The projects may still be built individually, but
    181     to build them all do not just select all of them in batch build (as some
    182     are meant as configuration projects), but rather select and build just
    183     the ALL_BUILD project to build everything, or the INSTALL project, which
    184     first builds the ALL_BUILD project, then installs the LLVM headers, libs,
    185     and other useful things to the directory set by the CMAKE_INSTALL_PREFIX
    186     setting when you first configured CMake.</li>
    187     <li>The Fibonacci project is a sample program that uses the JIT.
    188     Modify the project's debugging properties to provide a numeric
    189     command line argument or run it from the command line.  The
    190     program will print the corresponding fibonacci value.</li>
    191   </ul></li>
    192 
    193   <li>Test LLVM on Visual Studio:
    194   <ul>
    195     <li>If %PATH% does not contain GnuWin32, you may specify LLVM_LIT_TOOLS_DIR
    196     on CMake for the path to GnuWin32.</li>
    197     <li>You can run LLVM tests by merely building the project
    198       "check". The test results will be shown in the VS output
    199       window.</li>
    200   </ul>
    201   </li>
    202 
    203   <!-- FIXME: Is it up-to-date? -->
    204   <li>Test LLVM:
    205   <ul>
    206     <li>The LLVM tests can be run by <tt>cd</tt>ing to the llvm source directory
    207         and running:
    208 
    209 <div class="doc_code">
    210 <pre>
    211 % llvm-lit test
    212 </pre>
    213 </div>
    214 
    215     <p>Note that quite a few of these test will fail.</p>
    216     </li>
    217 
    218     <li>A specific test or test directory can be run with:
    219 
    220 <div class="doc_code">
    221 <pre>
    222 % llvm-lit test/path/to/test
    223 </pre>
    224 </div>
    225     </li>
    226   </ul>
    227 </ol>
    228 
    229 </div>
    230 
    231 <!-- *********************************************************************** -->
    232 <h2>
    233   <a name="tutorial">An Example Using the LLVM Tool Chain</a>
    234 </h2>
    235 <!-- *********************************************************************** -->
    236 
    237 <div>
    238 
    239 <ol>
    240   <li><p>First, create a simple C file, name it 'hello.c':</p>
    241 
    242 <div class="doc_code">
    243 <pre>
    244 #include &lt;stdio.h&gt;
    245 int main() {
    246   printf("hello world\n");
    247   return 0;
    248 }
    249 </pre></div></li>
    250 
    251   <li><p>Next, compile the C file into a LLVM bitcode file:</p>
    252 
    253 <div class="doc_code">
    254 <pre>
    255 % clang -c hello.c -emit-llvm -o hello.bc
    256 </pre>
    257 </div>
    258 
    259       <p>This will create the result file <tt>hello.bc</tt> which is the LLVM
    260          bitcode that corresponds the the compiled program and the library
    261          facilities that it required.  You can execute this file directly using
    262          <tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>,
    263          optimize or analyze it further with the <tt>opt</tt> tool, etc.</p>
    264 
    265       <p>Alternatively you can directly output an executable with clang with:
    266       </p>
    267 
    268 <div class="doc_code">
    269 <pre>
    270 % clang hello.c -o hello.exe
    271 </pre>
    272 </div>
    273 
    274   <p>The <tt>-o hello.exe</tt> is required because clang currently outputs
    275   <tt>a.out</tt> when neither <tt>-o</tt> nor <tt>-c</tt> are given.</p>
    276 
    277   <li><p>Run the program using the just-in-time compiler:</p>
    278 
    279 <div class="doc_code">
    280 <pre>
    281 % lli hello.bc
    282 </pre>
    283 </div>
    284 
    285   <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
    286       code:</p>
    287 
    288 <div class="doc_code">
    289 <pre>
    290 % llvm-dis &lt; hello.bc | more
    291 </pre>
    292 </div></li>
    293 
    294   <li><p>Compile the program to object code using the LLC code generator:</p>
    295 
    296 <div class="doc_code">
    297 <pre>
    298 % llc -filetype=obj hello.bc
    299 </pre>
    300 </div></li>
    301 
    302   <li><p>Link to binary using Microsoft link:</p>
    303 
    304 <div class="doc_code">
    305 <pre>
    306 % link hello.obj -defaultlib:libcmt
    307 </pre>
    308 </div>
    309 
    310   <li><p>Execute the native code program:</p>
    311 
    312 <div class="doc_code">
    313 <pre>
    314 % hello.exe
    315 </pre>
    316 </div></li>
    317 </ol>
    318 
    319 </div>
    320 
    321 <!-- *********************************************************************** -->
    322 <h2>
    323   <a name="problems">Common Problems</a>
    324 </h2>
    325 <!-- *********************************************************************** -->
    326 
    327 <div>
    328 
    329 <p>If you are having problems building or using LLVM, or if you have any other
    330 general questions about LLVM, please consult the <a href="FAQ.html">Frequently
    331 Asked Questions</a> page.</p>
    332 
    333 </div>
    334 
    335 <!-- *********************************************************************** -->
    336 <h2>
    337   <a name="links">Links</a>
    338 </h2>
    339 <!-- *********************************************************************** -->
    340 
    341 <div>
    342 
    343 <p>This document is just an <b>introduction</b> to how to use LLVM to do
    344 some simple things... there are many more interesting and complicated things
    345 that you can do that aren't documented here (but we'll gladly accept a patch
    346 if you want to write something up!).  For more information about LLVM, check
    347 out:</p>
    348 
    349 <ul>
    350   <li><a href="http://llvm.org/">LLVM homepage</a></li>
    351   <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
    352 </ul>
    353 
    354 </div>
    355 
    356 <!-- *********************************************************************** -->
    357 
    358 <hr>
    359 <address>
    360   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
    361   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
    362   <a href="http://validator.w3.org/check/referer"><img
    363   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
    364 
    365   <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
    366   Last modified: $Date: 2011-04-22 20:30:22 -0400 (Fri, 22 Apr 2011) $
    367 </address>
    368 </body>
    369 </html>
    370