docs/GettingStartedVS.html

   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>
  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:
  30     <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a>
  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
  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
  45   need to dynamically generate machine code.  The JIT and interpreter are
  46   functional, but it is currently not possible to generate assembly code which
  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>
  50
  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>
  57
  58   <p><tt>bugpoint</tt> does build, but does not work.  The other tools
  59   'should' work, but have not been fully tested.</p>
  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>
  63   page.</p>
  64
  65 </div>
  66
  67 <!-- *********************************************************************** -->
  68 <div class="doc_section">
  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
  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
  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
  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>
 107
 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
 112 </div>
 113
 114 <!-- *********************************************************************** -->
 115 <div class="doc_section">
 116   <a name="quickstart"><b>Getting Started</b></a>
 117 </div>
 118 <!-- *********************************************************************** -->
 119
 120 <div class="doc_text">
 121
 122 <p>Here's the short story for getting up and running quickly with LLVM:</p>
 123
 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>
 128
 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>
 138
 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>
 168
 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>
 175
 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>
 190
 191 </ol>
 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>
 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;
 209 int main() {
 210   printf("hello world\n");
 211   return 0;
 212 }
 213 </pre></div></li>
 214
 215   <li><p>Next, compile the C file into a LLVM bitcode file:</p>
 216
 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>
 228
 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>
 232
 233   <li><p>Run the program using the just-in-time compiler:</p>
 234
 235 <div class="doc_code">
 236 <pre>
 237 % lli hello.bc
 238 </pre>
 239 </div>
 240
 241       <p>Note: this will only work for trivial C programs.  Non-trivial programs
 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>
 244
 245   <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
 246       code:</p>
 247
 248 <div class="doc_code">
 249 <pre>
 250 % llvm-dis &lt; hello.bc | more
 251 </pre>
 252 </div></li>
 253
 254   <li><p>Compile the program to C using the LLC code generator:</p>
 255
 256 <div class="doc_code">
 257 <pre>
 258 % llc -march=c hello.bc
 259 </pre>
 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
 269 </div></li>
 270
 271   <li><p>Compile to binary using Microsoft C:</p>
 272
 273 <div class="doc_code">
 274 <pre>
 275 % cl hello.cbe.c
 276 </pre>
 277 </div>
 278
 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>
 282
 283   <li><p>Execute the native code program:</p>
 284
 285 <div class="doc_code">
 286 <pre>
 287 % hello.cbe.exe
 288 </pre>
 289 </div></li>
 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
 303 general questions about LLVM, please consult the <a href="FAQ.html">Frequently
 304 Asked 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
 317 some simple things... there are many more interesting and complicated things
 318 that you can do that aren't documented here (but we'll gladly accept a patch
 319 if you want to write something up!).  For more information about LLVM, check
 320 out:</p>
 321
 322 <ul>
 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
 326       that Uses LLVM</a></li>
 327 </ul>
 328
 329 </div>
 330
 331 <!-- *********************************************************************** -->
 332
 333 <hr>
 334 <address>
 335   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 336   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
 337   <a href="http://validator.w3.org/check/referer"><img
 338   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
 339
 340   <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a><br>
 341   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
 342   Last modified: $Date$
 343 </address>
 344 </body>
 345 </html>