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="#quickstart">Getting Started Quickly (A Summary)</a>
  18   <li><a href="#requirements">Requirements</a>
  19     <ol>
  20       <li><a href="#hardware">Hardware</a>
  21       <li><a href="#software">Software</a>
  22     </ol></li>
  23
  24   <li><a href="#starting">Getting Started with LLVM</a>
  25     <ol>
  26       <li><a href="#terminology">Terminology and Notation</a>
  27       <li><a href="#unpack">Unpacking the LLVM Archives</a>
  28       <li><a href="#checkout">Checkout LLVM from CVS</a>
  29       <li><a href="#objfiles">The Location of LLVM Object Files</a>
  30     </ol></li>
  31
  32   <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
  33   <li><a href="#problems">Common Problems</a>
  34   <li><a href="#links">Links</a>
  35 </ul>
  36
  37 <div class="doc_author">
  38   <p>Written by:
  39     <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a>,
  40   </p>
  41 </div>
  42
  43
  44 <!-- *********************************************************************** -->
  45 <div class="doc_section">
  46   <a name="overview"><b>Overview</b></a>
  47 </div>
  48 <!-- *********************************************************************** -->
  49
  50 <div class="doc_text">
  51
  52   <p>The Visual Studio port at this time is experimental.  It is suitable for
  53   use only if you are writing your own compiler front end or otherwise have a
  54   need to dynamically generate machine code.  The JIT and interpreter are
  55   functional, but it is currently not possible to directly generate an
  56   executable file.  You can do so indirectly by using the C back end.</p>
  57
  58   <p>To emphasize, there is no C/C++ front end currently available.  llvm-gcc
  59   is based on GCC, which cannot be bootstrapped using VC++.  Eventually there
  60   should be a llvm-gcc based on Cygwin or Mingw that is usable.  There is also
  61   the option of generating bytecode files on Unix and copying them over to
  62   Windows.  But be aware the odds of linking C++ code compiled with llvm-gcc
  63   with code compiled with VC++ is essentially zero.</p>
  64
  65   <p>The LLVM test suite cannot be run on the Visual Studio port at this
  66   time.</p>
  67
  68   <p>Most of the tools build and work.  <tt>llvm-db</tt> does not build at this
  69   time.  <tt>bugpoint</tt> does build, but does not work.
  70
  71   <p>Additional information about the LLVM directory structure and tool chain
  72   can be found on the main <a href="GettingStarted.html">Getting Started</a>
  73   page.</P>
  74
  75 </div>
  76
  77 <!-- *********************************************************************** -->
  78 <div class="doc_section">
  79   <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a>
  80 </div>
  81 <!-- *********************************************************************** -->
  82
  83 <div class="doc_text">
  84
  85 <p>Here's the short story for getting up and running quickly with LLVM:</p>
  86
  87 <ol>
  88   <li>Read the documentation.</li>
  89   <li>Read the documentation.</li>
  90   <li>Remember that you were warned twice about reading the documentation.</li>
  91
  92   <li>Get the Source Code
  93   <ul>
  94     <li>With the distributed files:
  95     <ol>
  96       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
  97       <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
  98       <i>or use WinZip</i>
  99       <li><tt>cd llvm</tt></li>
 100     </ol></li>
 101
 102     <li>With anonymous CVS access (or use a <a href="#mirror">mirror</a>):
 103     <ol>
 104       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
 105       <li><tt>cvs -d
 106           :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt></li>
 107       <li>Hit the return key when prompted for the password.
 108       <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm
 109           co llvm</tt></li>
 110       <li><tt>cd llvm</tt></li>
 111       <li><tt>cvs up -P -d</tt></li>
 112     </ol></li>
 113   </ul></li>
 114
 115   <li>Start Visual Studio
 116   <ol>
 117     <li>Simply double click on the solution file <tt>llvm/win32/llvm.sln</tt>.
 118     </li>
 119   </ol></li>
 120
 121   <li>Build the LLVM Suite:
 122   <ol>
 123     <li>Simply build the solution.</li>
 124     <li>The Fibonacci project is a sample program that uses the JIT.  Modify
 125     the project's debugging properties to provide a numeric command line
 126     argument.  The program will print the corresponding fibonacci value.</li>
 127   </ol></li>
 128
 129 </ol>
 130
 131 </div>
 132
 133 <!-- *********************************************************************** -->
 134 <div class="doc_section">
 135   <a name="requirements"><b>Requirements</b></a>
 136 </div>
 137 <!-- *********************************************************************** -->
 138
 139 <div class="doc_text">
 140
 141   <p>Before you begin to use the LLVM system, review the requirements given
 142   below.  This may save you some trouble by knowing ahead of time what hardware
 143   and software you will need.</p>
 144
 145 </div>
 146
 147 <!-- ======================================================================= -->
 148 <div class="doc_subsection">
 149   <a name="hardware"><b>Hardware</b></a>
 150 </div>
 151
 152 <div class="doc_text">
 153
 154   <p>Any system that can adequately run Visual Studio .NET 2003 is fine.  The
 155   LLVM source tree and object files, libraries and executables will consume
 156   approximately 3GB.</p>
 157
 158 </div>
 159
 160 <!-- ======================================================================= -->
 161 <div class="doc_subsection"><a name="software"><b>Software</b></a></div>
 162 <div class="doc_text">
 163
 164   <p>You will need Visual Studio .NET 2003.  Earlier versions cannot open the
 165   solution/project files.  The VS 2005 beta can, but will migrate these files
 166   to its own format in the process.  While it should work with the VS 2005
 167   beta, there are no guarantees and there is no support for it at this time.</p>
 168
 169   <p>You will also need several open source packages:  bison, flex, and sed.
 170   These must be installed in <tt>llvm/win32/tools</tt>.  These can be found at
 171   <a href="http://gnuwin32.sourceforge.net/">http://gnuwin32.sourceforge.net/
 172   </a>.  Bison prefers that m4 be in the path.  You must add it to the Visual
 173   Studio configuration under the menu Options -&gt; Projects -&gt; VC++
 174   Directories.  Alternatively, you can set the environment variable <tt>M4</tt>
 175   to point to <tt>m4</tt> executable.</p>
 176
 177 </div>
 178
 179 <!-- *********************************************************************** -->
 180 <div class="doc_section">
 181   <a name="starting"><b>Getting Started with LLVM</b></a>
 182 </div>
 183 <!-- *********************************************************************** -->
 184
 185 <div class="doc_text">
 186
 187 <p>The remainder of this guide is meant to get you up and running with
 188 LLVM using Visual Studio and to give you some basic information about the LLVM
 189 environment.</p>
 190
 191 </div>
 192
 193 <!-- ======================================================================= -->
 194 <div class="doc_subsection">
 195   <a name="terminology">Terminology and Notation</a>
 196 </div>
 197
 198 <div class="doc_text">
 199
 200 <p>Throughout this manual, the following names are used to denote paths
 201 specific to the local system and working environment.  <i>These are not
 202 environment variables you need to set but just strings used in the rest
 203 of this document below</i>.  In any of the examples below, simply replace
 204 each of these names with the appropriate pathname on your local system.
 205 All these paths are absolute:</p>
 206
 207 <dl>
 208     <dt>SRC_ROOT
 209     <dd>
 210     This is the top level directory of the LLVM source tree.
 211     <p>
 212
 213     <dt>OBJ_ROOT
 214     <dd>
 215     This is the top level directory of the LLVM object tree (i.e. the
 216     tree where object files and compiled programs will be placed.  It
 217     is fixed at SRC_ROOT/win32).
 218     <p>
 219 </dl>
 220
 221 </div>
 222
 223 <!-- ======================================================================= -->
 224 <div class="doc_subsection">
 225   <a name="unpack">Unpacking the LLVM Archives</a>
 226 </div>
 227
 228 <div class="doc_text">
 229
 230 <p>
 231 If you have the LLVM distribution, you will need to unpack it before you
 232 can begin to compile it.  LLVM is distributed as a set of two files: the LLVM
 233 suite and the LLVM GCC front end compiled for your platform.  There is an
 234 additional test suite that is optional.  Each file is a TAR archive that is
 235 compressed with the gzip program.  The WinZip program can also unpack this
 236 archive.  Only the LLVM suite is usable with Visual Studio.
 237 </p>
 238
 239 <p> The files are as follows:
 240 <dl>
 241   <dt><tt>llvm-1.4.tar.gz</tt></dt>
 242   <dd>This is the source code for the LLVM libraries and tools.<br/></dd>
 243 </dl>
 244
 245 </div>
 246
 247 <!-- ======================================================================= -->
 248 <div class="doc_subsection">
 249   <a name="checkout">Checkout LLVM from CVS</a>
 250 </div>
 251
 252 <div class="doc_text">
 253
 254 <p>If you have access to our CVS repository, you can get a fresh copy of
 255 the entire source code.  Note that significant progress has been made on the
 256 Visual Studio port since 1.4 was released.  All you need to do is check it out
 257 from CVS as follows:</p>
 258
 259 <ul>
 260 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
 261   <li><tt>cvs -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt>
 262   <li>Hit the return key when prompted for the password.
 263   <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
 264       llvm</tt>
 265 </ul>
 266
 267 <p>This will create an '<tt>llvm</tt>' directory in the current
 268 directory and fully populate it with the LLVM source code, Makefiles,
 269 test directories, and local copies of documentation files.</p>
 270
 271 <p>If you want to get a specific release (as opposed to the most recent
 272 revision), you can specify a label.  The following releases have the following
 273 label:</p>
 274
 275 <ul>
 276 <li>Release 1.4: <b>RELEASE_14</b></li>
 277 <li>Release 1.3: <b>RELEASE_13</b></li>
 278 <li>Release 1.2: <b>RELEASE_12</b></li>
 279 <li>Release 1.1: <b>RELEASE_11</b></li>
 280 <li>Release 1.0: <b>RELEASE_1</b></li>
 281 </ul>
 282
 283 </div>
 284
 285 <!-- ======================================================================= -->
 286 <div class="doc_subsubsection">
 287   <a name="mirrors">LLVM CVS Mirrors</a>
 288 </div>
 289
 290 <div class="doc_text">
 291
 292 <p>If the main CVS server is overloaded or inaccessible, you can try one of
 293 these user-hosted mirrors:</p>
 294
 295 <ul>
 296 <li><a href="http://llvm.x10sys.com/">Mirror hosted by eXtensible Systems
 297 Inc.</a></li>
 298 </ul>
 299 </div>
 300
 301 <!-- ======================================================================= -->
 302 <div class="doc_subsection">
 303   <a name="objfiles">The Location of LLVM Object Files</a>
 304 </div>
 305
 306 <div class="doc_text">
 307
 308   <p>The object files are placed under <tt>OBJ_ROOT/Debug</tt> for debug builds
 309   and <tt>OBJ_ROOT/Release</tt> for release (optimized) builds.  These include
 310   both executables and libararies that your application can link against.
 311
 312   <p>The files that <tt>configure</tt> would create when building on Unix are
 313   created by the <tt>Configure</tt> project and placed in
 314   <tt>OBJ_ROOT/llvm</tt>.  You application must have OBJ_ROOT in its include
 315   search path just before <tt>SRC_ROOT/include</tt>.
 316
 317 </div>
 318
 319 <!-- *********************************************************************** -->
 320 <div class="doc_section">
 321   <a name="tutorial">An Example Using the LLVM Tool Chain</a>
 322 </div>
 323 <!-- *********************************************************************** -->
 324
 325 <div class="doc_text">
 326
 327 <ol>
 328   <li>First, create a simple C file, name it 'hello.c':
 329        <pre>
 330    #include &lt;stdio.h&gt;
 331    int main() {
 332      printf("hello world\n");
 333      return 0;
 334    }
 335        </pre></li>
 336
 337   <li><p>Next, compile the C file into a LLVM bytecode file:</p>
 338       <p><tt>% llvm-gcc hello.c -o hello</tt></p>
 339
 340       <p>Note that you should have already built the tools and they have to be
 341       in your path, at least <tt>gccas</tt> and <tt>gccld</tt>.</p>
 342
 343       <p>This will create two result files: <tt>hello</tt> and
 344       <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
 345       corresponds the the compiled program and the library facilities that it
 346       required.  <tt>hello</tt> is a simple shell script that runs the bytecode
 347       file with <tt>lli</tt>, making the result directly executable.  Note that
 348       all LLVM optimizations are enabled by default, so there is no need for a
 349       "-O3" switch.</p>
 350
 351       <p><b>Note: while you cannot do this step on Windows, you can do it on a
 352         Unix system and transfer <tt>hello.bc</tt> to Windows.</b></p></li>
 353
 354   <li><p>Run the program. To make sure the program ran, execute the
 355       following command:</p>
 356
 357       <p><tt>% lli hello.bc</tt></p></li>
 358
 359   <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
 360       code:</p>
 361
 362       <p><tt>% llvm-dis &lt; hello.bc | less</tt><p></li>
 363
 364   <li><p>Compile the program to native assembly using the LLC code
 365       generator:</p>
 366
 367       <p><tt>% llc hello.bc -o hello.s</tt></p>
 368
 369   <li><p>Assemble the native assembly language file into a program:</p>
 370
 371   <p><b>Not currently possible, but eventually will use <tt>NASMW</tt>.</b></p>
 372
 373   <li><p>Execute the native code program:</p>
 374
 375       <p><tt>% ./hello.native</tt></p></li>
 376
 377 </ol>
 378
 379 </div>
 380
 381 <!-- *********************************************************************** -->
 382 <div class="doc_section">
 383   <a name="problems">Common Problems</a>
 384 </div>
 385 <!-- *********************************************************************** -->
 386
 387 <div class="doc_text">
 388
 389 <p>If you are having problems building or using LLVM, or if you have any other
 390 general questions about LLVM, please consult the <a href="FAQ.html">Frequently
 391 Asked Questions</a> page.</p>
 392
 393 </div>
 394
 395 <!-- *********************************************************************** -->
 396 <div class="doc_section">
 397   <a name="links">Links</a>
 398 </div>
 399 <!-- *********************************************************************** -->
 400
 401 <div class="doc_text">
 402
 403 <p>This document is just an <b>introduction</b> to how to use LLVM to do
 404 some simple things... there are many more interesting and complicated things
 405 that you can do that aren't documented here (but we'll gladly accept a patch
 406 if you want to write something up!).  For more information about LLVM, check
 407 out:</p>
 408
 409 <ul>
 410   <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
 411   <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
 412   <li><a href="http://llvm.cs.uiuc.edu/docs/Projects.html">Starting a Project
 413   that Uses LLVM</a></li>
 414 </ul>
 415
 416 </div>
 417
 418 <!-- *********************************************************************** -->
 419
 420 <hr>
 421 <address>
 422   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 423   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 424   <a href="http://validator.w3.org/check/referer"><img
 425   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
 426
 427   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
 428   <a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br>
 429   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
 430   Last modified: $Date$
 431 </address>
 432 </body>
 433 </html>