Jeff Cohen | 7a4f03d | 2005-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> |
| 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> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 27 | <li><a href="#objfiles">The Location of LLVM Object Files</a> |
| 28 | </ol></li> |
| 29 | |
| 30 | <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a> |
| 31 | <li><a href="#problems">Common Problems</a> |
| 32 | <li><a href="#links">Links</a> |
| 33 | </ul> |
| 34 | |
| 35 | <div class="doc_author"> |
| 36 | <p>Written by: |
Jeff Cohen | b9a47d1 | 2005-02-01 15:59:28 +0000 | [diff] [blame] | 37 | <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 38 | </p> |
| 39 | </div> |
| 40 | |
| 41 | |
| 42 | <!-- *********************************************************************** --> |
| 43 | <div class="doc_section"> |
| 44 | <a name="overview"><b>Overview</b></a> |
| 45 | </div> |
| 46 | <!-- *********************************************************************** --> |
| 47 | |
| 48 | <div class="doc_text"> |
| 49 | |
| 50 | <p>The Visual Studio port at this time is experimental. It is suitable for |
| 51 | use only if you are writing your own compiler front end or otherwise have a |
| 52 | need to dynamically generate machine code. The JIT and interpreter are |
Jeff Cohen | ca0a909 | 2005-03-08 03:56:50 +0000 | [diff] [blame] | 53 | functional, but it is currently not possible to generate assembly code which |
| 54 | is then assembled into an executable. You can indirectly create executables |
| 55 | by using the C back end.</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 56 | |
Jeff Cohen | b9a47d1 | 2005-02-01 15:59:28 +0000 | [diff] [blame] | 57 | <p>To emphasize, there is no C/C++ front end currently available. |
| 58 | <tt>llvm-gcc</tt> is based on GCC, which cannot be bootstrapped using VC++. |
| 59 | Eventually there should be a <tt>llvm-gcc</tt> based on Cygwin or MinGW that |
Gabor Greif | 04367bf | 2007-07-06 22:07:22 +0000 | [diff] [blame] | 60 | is usable. There is also the option of generating bitcode files on Unix and |
Jeff Cohen | b9a47d1 | 2005-02-01 15:59:28 +0000 | [diff] [blame] | 61 | copying them over to Windows. But be aware the odds of linking C++ code |
| 62 | compiled with <tt>llvm-gcc</tt> with code compiled with VC++ is essentially |
| 63 | zero.</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 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> |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 89 | <li>Seriously, read the documentation.</li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 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> |
Jeff Cohen | b9a47d1 | 2005-02-01 15:59:28 +0000 | [diff] [blame] | 98 | <i> or use WinZip</i> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 99 | <li><tt>cd llvm</tt></li> |
| 100 | </ol></li> |
| 101 | |
Reid Spencer | 669ed45 | 2007-07-09 08:04:31 +0000 | [diff] [blame] | 102 | <li>With anonymous Subversion access: |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 103 | <ol> |
| 104 | <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li> |
Reid Spencer | 669ed45 | 2007-07-09 08:04:31 +0000 | [diff] [blame] | 105 | <li><tt>svn co http://llvm.org/svn/llvm-project/llvm-top/trunk llvm-top |
| 106 | </tt></li> |
| 107 | <li><tt>make checkout MODULE=llvm</tt> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 108 | <li><tt>cd llvm</tt></li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 109 | </ol></li> |
| 110 | </ul></li> |
| 111 | |
| 112 | <li>Start Visual Studio |
| 113 | <ol> |
| 114 | <li>Simply double click on the solution file <tt>llvm/win32/llvm.sln</tt>. |
| 115 | </li> |
| 116 | </ol></li> |
| 117 | |
| 118 | <li>Build the LLVM Suite: |
| 119 | <ol> |
| 120 | <li>Simply build the solution.</li> |
| 121 | <li>The Fibonacci project is a sample program that uses the JIT. Modify |
| 122 | the project's debugging properties to provide a numeric command line |
| 123 | argument. The program will print the corresponding fibonacci value.</li> |
| 124 | </ol></li> |
| 125 | |
| 126 | </ol> |
| 127 | |
Reid Spencer | 669ed45 | 2007-07-09 08:04:31 +0000 | [diff] [blame] | 128 | <p>It is strongly encouraged that you get the latest version from Subversion as |
| 129 | changes are continually making the VS support better.</p> |
Jeff Cohen | b9a47d1 | 2005-02-01 15:59:28 +0000 | [diff] [blame] | 130 | |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 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 |
Jeff Cohen | ca0a909 | 2005-03-08 03:56:50 +0000 | [diff] [blame] | 167 | beta, there are no guarantees and there is no support for it at this time. |
| 168 | It has been reported that VC++ Express also works.</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 169 | |
Jeff Cohen | a088734 | 2005-10-30 21:00:24 +0000 | [diff] [blame] | 170 | <p>If you plan to modify any .y or .l files, you will need to have bison |
| 171 | and/or flex installed where Visual Studio can find them. Otherwise, you do |
| 172 | not need them and the pre-generated files that come with the source tree |
| 173 | will be used.</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 174 | |
| 175 | </div> |
| 176 | |
| 177 | <!-- *********************************************************************** --> |
| 178 | <div class="doc_section"> |
| 179 | <a name="starting"><b>Getting Started with LLVM</b></a> |
| 180 | </div> |
| 181 | <!-- *********************************************************************** --> |
| 182 | |
| 183 | <div class="doc_text"> |
| 184 | |
| 185 | <p>The remainder of this guide is meant to get you up and running with |
| 186 | LLVM using Visual Studio and to give you some basic information about the LLVM |
| 187 | environment.</p> |
| 188 | |
| 189 | </div> |
| 190 | |
| 191 | <!-- ======================================================================= --> |
| 192 | <div class="doc_subsection"> |
| 193 | <a name="terminology">Terminology and Notation</a> |
| 194 | </div> |
| 195 | |
| 196 | <div class="doc_text"> |
| 197 | |
| 198 | <p>Throughout this manual, the following names are used to denote paths |
| 199 | specific to the local system and working environment. <i>These are not |
| 200 | environment variables you need to set but just strings used in the rest |
| 201 | of this document below</i>. In any of the examples below, simply replace |
| 202 | each of these names with the appropriate pathname on your local system. |
| 203 | All these paths are absolute:</p> |
| 204 | |
| 205 | <dl> |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 206 | <dt>SRC_ROOT</dt> |
| 207 | <dd><p>This is the top level directory of the LLVM source tree.</p></dd> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 208 | |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 209 | <dt>OBJ_ROOT</dt> |
| 210 | <dd><p>This is the top level directory of the LLVM object tree (i.e. the |
| 211 | tree where object files and compiled programs will be placed. It is |
| 212 | fixed at SRC_ROOT/win32).</p></dd> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 213 | </dl> |
| 214 | |
| 215 | </div> |
| 216 | |
| 217 | <!-- ======================================================================= --> |
| 218 | <div class="doc_subsection"> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 219 | <a name="objfiles">The Location of LLVM Object Files</a> |
| 220 | </div> |
| 221 | |
| 222 | <div class="doc_text"> |
| 223 | |
| 224 | <p>The object files are placed under <tt>OBJ_ROOT/Debug</tt> for debug builds |
| 225 | and <tt>OBJ_ROOT/Release</tt> for release (optimized) builds. These include |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 226 | both executables and libararies that your application can link against.</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 227 | |
| 228 | <p>The files that <tt>configure</tt> would create when building on Unix are |
| 229 | created by the <tt>Configure</tt> project and placed in |
| 230 | <tt>OBJ_ROOT/llvm</tt>. You application must have OBJ_ROOT in its include |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 231 | search path just before <tt>SRC_ROOT/include</tt>.</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 232 | |
| 233 | </div> |
| 234 | |
| 235 | <!-- *********************************************************************** --> |
| 236 | <div class="doc_section"> |
| 237 | <a name="tutorial">An Example Using the LLVM Tool Chain</a> |
| 238 | </div> |
| 239 | <!-- *********************************************************************** --> |
| 240 | |
| 241 | <div class="doc_text"> |
| 242 | |
| 243 | <ol> |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 244 | <li><p>First, create a simple C file, name it 'hello.c':</p> |
| 245 | |
| 246 | <div class="doc_code"> |
| 247 | <pre> |
| 248 | #include <stdio.h> |
| 249 | int main() { |
| 250 | printf("hello world\n"); |
| 251 | return 0; |
| 252 | } |
| 253 | </pre></div></li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 254 | |
Gabor Greif | 04367bf | 2007-07-06 22:07:22 +0000 | [diff] [blame] | 255 | <li><p>Next, compile the C file into a LLVM bitcode file:</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 256 | |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 257 | <div class="doc_code"> |
| 258 | <pre> |
| 259 | % llvm-gcc -c hello.c -emit-llvm -o hello.bc |
| 260 | </pre> |
| 261 | </div> |
| 262 | |
| 263 | <p>This will create the result file <tt>hello.bc</tt> which is the LLVM |
| 264 | bitcode that corresponds the the compiled program and the library |
| 265 | facilities that it required. You can execute this file directly using |
| 266 | <tt>lli</tt> tool, compile it to native assembly with the <tt>llc</tt>, |
| 267 | optimize or analyze it further with the <tt>opt</tt> tool, etc.</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 268 | |
| 269 | <p><b>Note: while you cannot do this step on Windows, you can do it on a |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 270 | Unix system and transfer <tt>hello.bc</tt> to Windows. Important: |
| 271 | transfer as a binary file!</b></p></li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 272 | |
Jeff Cohen | a088734 | 2005-10-30 21:00:24 +0000 | [diff] [blame] | 273 | <li><p>Run the program using the just-in-time compiler:</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 274 | |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 275 | <div class="doc_code"> |
| 276 | <pre> |
| 277 | % lli hello.bc |
| 278 | </pre> |
| 279 | </div> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 280 | |
Jeff Cohen | 3c8dfcd | 2007-03-28 20:27:51 +0000 | [diff] [blame] | 281 | <p>Note: this will only work for trivial C programs. Non-trivial programs |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 282 | (and any C++ program) will have dependencies on the GCC runtime that |
| 283 | won't be satisfied by the Microsoft runtime libraries.</p></li> |
Jeff Cohen | 3c8dfcd | 2007-03-28 20:27:51 +0000 | [diff] [blame] | 284 | |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 285 | <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly |
| 286 | code:</p> |
| 287 | |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 288 | <div class="doc_code"> |
| 289 | <pre> |
| 290 | % llvm-dis < hello.bc | more |
| 291 | </pre> |
| 292 | </div></li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 293 | |
Jeff Cohen | a088734 | 2005-10-30 21:00:24 +0000 | [diff] [blame] | 294 | <li><p>Compile the program to C using the LLC code generator:</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 295 | |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 296 | <div class="doc_code"> |
| 297 | <pre> |
| 298 | % llc -march=c hello.bc |
| 299 | </pre> |
| 300 | </div></li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 301 | |
Jeff Cohen | a088734 | 2005-10-30 21:00:24 +0000 | [diff] [blame] | 302 | <li><p>Compile to binary using Microsoft C:</p> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 303 | |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 304 | <div class="doc_code"> |
| 305 | <pre> |
| 306 | % cl hello.cbe.c |
| 307 | </pre> |
| 308 | </div> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 309 | |
Jeff Cohen | 3c8dfcd | 2007-03-28 20:27:51 +0000 | [diff] [blame] | 310 | <p>Note: this will only work for trivial C programs. Non-trivial programs |
| 311 | (and any C++ program) will have dependencies on the GCC runtime that |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 312 | won't be satisfied by the Microsoft runtime libraries.</p></li> |
Jeff Cohen | 3c8dfcd | 2007-03-28 20:27:51 +0000 | [diff] [blame] | 313 | |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 314 | <li><p>Execute the native code program:</p> |
| 315 | |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 316 | <div class="doc_code"> |
| 317 | <pre> |
| 318 | % hello.cbe.exe |
| 319 | </pre> |
| 320 | </div></li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 321 | </ol> |
| 322 | |
| 323 | </div> |
| 324 | |
| 325 | <!-- *********************************************************************** --> |
| 326 | <div class="doc_section"> |
| 327 | <a name="problems">Common Problems</a> |
| 328 | </div> |
| 329 | <!-- *********************************************************************** --> |
| 330 | |
| 331 | <div class="doc_text"> |
| 332 | |
| 333 | <p>If you are having problems building or using LLVM, or if you have any other |
| 334 | general questions about LLVM, please consult the <a href="FAQ.html">Frequently |
| 335 | Asked Questions</a> page.</p> |
| 336 | |
| 337 | </div> |
| 338 | |
| 339 | <!-- *********************************************************************** --> |
| 340 | <div class="doc_section"> |
| 341 | <a name="links">Links</a> |
| 342 | </div> |
| 343 | <!-- *********************************************************************** --> |
| 344 | |
| 345 | <div class="doc_text"> |
| 346 | |
| 347 | <p>This document is just an <b>introduction</b> to how to use LLVM to do |
| 348 | some simple things... there are many more interesting and complicated things |
| 349 | that you can do that aren't documented here (but we'll gladly accept a patch |
| 350 | if you want to write something up!). For more information about LLVM, check |
| 351 | out:</p> |
| 352 | |
| 353 | <ul> |
Reid Spencer | 05fe4b0 | 2006-03-14 05:39:39 +0000 | [diff] [blame] | 354 | <li><a href="http://llvm.org/">LLVM homepage</a></li> |
| 355 | <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li> |
| 356 | <li><a href="http://llvm.org/docs/Projects.html">Starting a Project |
Bill Wendling | 03c993a | 2007-09-22 09:39:19 +0000 | [diff] [blame^] | 357 | that Uses LLVM</a></li> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 358 | </ul> |
| 359 | |
| 360 | </div> |
| 361 | |
| 362 | <!-- *********************************************************************** --> |
| 363 | |
| 364 | <hr> |
| 365 | <address> |
| 366 | <a href="http://jigsaw.w3.org/css-validator/check/referer"><img |
| 367 | src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a> |
| 368 | <a href="http://validator.w3.org/check/referer"><img |
| 369 | src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a> |
| 370 | |
Jeff Cohen | b9a47d1 | 2005-02-01 15:59:28 +0000 | [diff] [blame] | 371 | <a href="mailto:jeffc@jolt-lang.org">Jeff Cohen</a><br> |
Reid Spencer | 05fe4b0 | 2006-03-14 05:39:39 +0000 | [diff] [blame] | 372 | <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br> |
Jeff Cohen | 7a4f03d | 2005-01-31 05:42:10 +0000 | [diff] [blame] | 373 | Last modified: $Date$ |
| 374 | </address> |
| 375 | </body> |
| 376 | </html> |