1 ==================================== 2 Getting Started with the LLVM System 3 ==================================== 4 5 .. contents:: 6 :local: 7 8 Overview 9 ======== 10 11 Welcome to LLVM! In order to get started, you first need to know some basic 12 information. 13 14 First, LLVM comes in three pieces. The first piece is the LLVM suite. This 15 contains all of the tools, libraries, and header files needed to use LLVM. It 16 contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It 17 also contains basic regression tests that can be used to test the LLVM tools and 18 the Clang front end. 19 20 The second piece is the `Clang <http://clang.llvm.org/>`_ front end. This 21 component compiles C, C++, Objective C, and Objective C++ code into LLVM 22 bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the 23 LLVM tools from the LLVM suite. 24 25 There is a third, optional piece called Test Suite. It is a suite of programs 26 with a testing harness that can be used to further test LLVM's functionality 27 and performance. 28 29 Getting Started Quickly (A Summary) 30 =================================== 31 32 The LLVM Getting Started documentation may be out of date. So, the `Clang 33 Getting Started <http://clang.llvm.org/get_started.html>`_ page might also be a 34 good place to start. 35 36 Here's the short story for getting up and running quickly with LLVM: 37 38 #. Read the documentation. 39 #. Read the documentation. 40 #. Remember that you were warned twice about reading the documentation. 41 #. Checkout LLVM: 42 43 * ``cd where-you-want-llvm-to-live`` 44 * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` 45 46 #. Checkout Clang: 47 48 * ``cd where-you-want-llvm-to-live`` 49 * ``cd llvm/tools`` 50 * ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang`` 51 52 #. Checkout Compiler-RT: 53 54 * ``cd where-you-want-llvm-to-live`` 55 * ``cd llvm/projects`` 56 * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt`` 57 58 #. Get the Test Suite Source Code **[Optional]** 59 60 * ``cd where-you-want-llvm-to-live`` 61 * ``cd llvm/projects`` 62 * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite`` 63 64 #. Configure and build LLVM and Clang: 65 66 * ``cd where-you-want-to-build-llvm`` 67 * ``mkdir build`` (for building without polluting the source dir) 68 * ``cd build`` 69 * ``../llvm/configure [options]`` 70 Some common options: 71 72 * ``--prefix=directory`` --- Specify for *directory* the full pathname of 73 where you want the LLVM tools and libraries to be installed (default 74 ``/usr/local``). 75 76 * ``--enable-optimized`` --- Compile with optimizations enabled (default 77 is NO). 78 79 * ``--enable-assertions`` --- Compile with assertion checks enabled 80 (default is YES). 81 82 * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run 83 simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. 84 The ``--enabled-optimized`` configure option is used to specify a Release 85 build. 86 87 * ``make check-all`` --- This run the regression tests to ensure everything 88 is in working order. 89 90 * ``make update`` --- This command is used to update all the svn repositories 91 at once, rather then having to ``cd`` into the individual repositories and 92 running ``svn update``. 93 94 * It is also possible to use CMake instead of the makefiles. With CMake it is 95 possible to generate project files for several IDEs: Xcode, Eclipse CDT4, 96 CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3. 97 98 * If you get an "internal compiler error (ICE)" or test failures, see 99 `below`. 100 101 Consult the `Getting Started with LLVM`_ section for detailed information on 102 configuring and compiling LLVM. See `Setting Up Your Environment`_ for tips 103 that simplify working with the Clang front end and LLVM tools. Go to `Program 104 Layout`_ to learn about the layout of the source code tree. 105 106 Requirements 107 ============ 108 109 Before you begin to use the LLVM system, review the requirements given below. 110 This may save you some trouble by knowing ahead of time what hardware and 111 software you will need. 112 113 Hardware 114 -------- 115 116 LLVM is known to work on the following platforms: 117 118 +-----------------+----------------------+-------------------------+ 119 |OS | Arch | Compilers | 120 +=================+======================+=========================+ 121 |AuroraUX | x86\ :sup:`1` | GCC | 122 +-----------------+----------------------+-------------------------+ 123 |Linux | x86\ :sup:`1` | GCC | 124 +-----------------+----------------------+-------------------------+ 125 |Linux | amd64 | GCC | 126 +-----------------+----------------------+-------------------------+ 127 |Linux | ARM\ :sup:`13` | GCC | 128 +-----------------+----------------------+-------------------------+ 129 |Solaris | V9 (Ultrasparc) | GCC | 130 +-----------------+----------------------+-------------------------+ 131 |FreeBSD | x86\ :sup:`1` | GCC | 132 +-----------------+----------------------+-------------------------+ 133 |FreeBSD | amd64 | GCC | 134 +-----------------+----------------------+-------------------------+ 135 |MacOS X\ :sup:`2`| PowerPC | GCC | 136 +-----------------+----------------------+-------------------------+ 137 |MacOS X\ :sup:`9`| x86 | GCC | 138 +-----------------+----------------------+-------------------------+ 139 |Cygwin/Win32 | x86\ :sup:`1, 8, 11` | GCC 3.4.X, binutils 2.20| 140 +-----------------+----------------------+-------------------------+ 141 142 LLVM has partial support for the following platforms: 143 144 +-------------------+----------------------+-------------------------------------------+ 145 |OS | Arch | Compilers | 146 +===================+======================+===========================================+ 147 | Windows | x86\ :sup:`1` | Visual Studio 2000 or higher\ :sup:`4,5` | 148 +-------------------+----------------------+-------------------------------------------+ 149 | AIX\ :sup:`3,4` | PowerPC | GCC | 150 +-------------------+----------------------+-------------------------------------------+ 151 | Linux\ :sup:`3,5` | PowerPC | GCC | 152 +-------------------+----------------------+-------------------------------------------+ 153 | Linux\ :sup:`7` | Alpha | GCC | 154 +-------------------+----------------------+-------------------------------------------+ 155 | Linux\ :sup:`7` | Itanium (IA-64) | GCC | 156 +-------------------+----------------------+-------------------------------------------+ 157 | HP-UX\ :sup:`7` | Itanium (IA-64) | HP aCC | 158 +-------------------+----------------------+-------------------------------------------+ 159 | Windows x64 | x86-64 | mingw-w64's GCC-4.5.x\ :sup:`12` | 160 +-------------------+----------------------+-------------------------------------------+ 161 162 .. note:: 163 164 #. Code generation supported for Pentium processors and up 165 #. Code generation supported for 32-bit ABI only 166 #. No native code generation 167 #. Build is not complete: one or more tools do not link or function 168 #. The GCC-based C/C++ frontend does not build 169 #. The port is done using the MSYS shell. 170 #. Native code generation exists but is not complete. 171 #. Binutils 2.20 or later is required to build the assembler generated by LLVM properly. 172 #. Xcode 2.5 and gcc 4.0.1 (Apple Build 5370) will trip internal LLVM assert 173 messages when compiled for Release at optimization levels greater than 0 174 (i.e., ``-O1`` and higher). Add ``OPTIMIZE_OPTION="-O0"`` to the build 175 command line if compiling for LLVM Release or bootstrapping the LLVM 176 toolchain. 177 #. For MSYS/MinGW on Windows, be sure to install the MSYS version of the perl 178 package, and be sure it appears in your path before any Windows-based 179 versions such as Strawberry Perl and ActivePerl, as these have 180 Windows-specifics that will cause the build to fail. 181 #. To use LLVM modules on Win32-based system, you may configure LLVM 182 with ``--enable-shared``. 183 #. To compile SPU backend, you need to add ``LDFLAGS=-Wl,--stack,16777216`` to 184 configure. 185 #. MCJIT not working well pre-v7, old JIT engine not supported any more. 186 187 Note that you will need about 1-3 GB of space for a full LLVM build in Debug 188 mode, depending on the system (it is so large because of all the debugging 189 information and the fact that the libraries are statically linked into multiple 190 tools). If you do not need many of the tools and you are space-conscious, you 191 can pass ``ONLY_TOOLS="tools you need"`` to make. The Release build requires 192 considerably less space. 193 194 The LLVM suite *may* compile on other platforms, but it is not guaranteed to do 195 so. If compilation is successful, the LLVM utilities should be able to 196 assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation 197 should work as well, although the generated native code may not work on your 198 platform. 199 200 Software 201 -------- 202 203 Compiling LLVM requires that you have several software packages installed. The 204 table below lists those required packages. The Package column is the usual name 205 for the software package that LLVM depends on. The Version column provides 206 "known to work" versions of the package. The Notes column describes how LLVM 207 uses the package and provides other details. 208 209 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 210 | Package | Version | Notes | 211 +==============================================================+=================+=============================================+ 212 | `GNU Make <http://savannah.gnu.org/projects/make>`_ | 3.79, 3.79.1 | Makefile/build processor | 213 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 214 | `GCC <http://gcc.gnu.org/>`_ | 3.4.2 | C/C++ compiler\ :sup:`1` | 215 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 216 | `TeXinfo <http://www.gnu.org/software/texinfo/>`_ | 4.5 | For building the CFE | 217 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 218 | `SVN <http://subversion.tigris.org/project_packages.html>`_ | >=1.3 | Subversion access to LLVM\ :sup:`2` | 219 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 220 | `python <http://www.python.org/>`_ | >=2.4 | Automated test suite\ :sup:`3` | 221 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 222 | `perl <http://www.perl.com/download.csp>`_ | >=5.6.0 | Utilities | 223 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 224 | `GNU M4 <http://savannah.gnu.org/projects/m4>`_ | 1.4 | Macro processor for configuration\ :sup:`4` | 225 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 226 | `GNU Autoconf <http://www.gnu.org/software/autoconf/>`_ | 2.60 | Configuration script builder\ :sup:`4` | 227 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 228 | `GNU Automake <http://www.gnu.org/software/automake/>`_ | 1.9.6 | aclocal macro generator\ :sup:`4` | 229 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 230 | `libtool <http://savannah.gnu.org/projects/libtool>`_ | 1.5.22 | Shared library manager\ :sup:`4` | 231 +--------------------------------------------------------------+-----------------+---------------------------------------------+ 232 233 .. note:: 234 235 #. Only the C and C++ languages are needed so there's no need to build the 236 other languages for LLVM's purposes. See `below` for specific version 237 info. 238 #. You only need Subversion if you intend to build from the latest LLVM 239 sources. If you're working from a release distribution, you don't need 240 Subversion. 241 #. Only needed if you want to run the automated test suite in the 242 ``llvm/test`` directory. 243 #. If you want to make changes to the configure scripts, you will need GNU 244 autoconf (2.60), and consequently, GNU M4 (version 1.4 or higher). You 245 will also need automake (1.9.6). We only use aclocal from that package. 246 247 Additionally, your compilation host is expected to have the usual plethora of 248 Unix utilities. Specifically: 249 250 * **ar** --- archive library builder 251 * **bzip2** --- bzip2 command for distribution generation 252 * **bunzip2** --- bunzip2 command for distribution checking 253 * **chmod** --- change permissions on a file 254 * **cat** --- output concatenation utility 255 * **cp** --- copy files 256 * **date** --- print the current date/time 257 * **echo** --- print to standard output 258 * **egrep** --- extended regular expression search utility 259 * **find** --- find files/dirs in a file system 260 * **grep** --- regular expression search utility 261 * **gzip** --- gzip command for distribution generation 262 * **gunzip** --- gunzip command for distribution checking 263 * **install** --- install directories/files 264 * **mkdir** --- create a directory 265 * **mv** --- move (rename) files 266 * **ranlib** --- symbol table builder for archive libraries 267 * **rm** --- remove (delete) files and directories 268 * **sed** --- stream editor for transforming output 269 * **sh** --- Bourne shell for make build scripts 270 * **tar** --- tape archive for distribution generation 271 * **test** --- test things in file system 272 * **unzip** --- unzip command for distribution checking 273 * **zip** --- zip command for distribution generation 274 275 .. _below: 276 .. _check here: 277 278 Broken versions of GCC and other tools 279 -------------------------------------- 280 281 LLVM is very demanding of the host C++ compiler, and as such tends to expose 282 bugs in the compiler. In particular, several versions of GCC crash when trying 283 to compile LLVM. We routinely use GCC 4.2 (and higher) or Clang. Other 284 versions of GCC will probably work as well. GCC versions listed here are known 285 to not work. If you are using one of these versions, please try to upgrade your 286 GCC to something more recent. If you run into a problem with a version of GCC 287 not listed here, please `let us know <mailto:llvmdev (a] cs.uiuc.edu>`_. Please use 288 the "``gcc -v``" command to find out which version of GCC you are using. 289 290 **GCC versions prior to 3.0**: GCC 2.96.x and before had several problems in the 291 STL that effectively prevent it from compiling LLVM. 292 293 **GCC 3.2.2 and 3.2.3**: These versions of GCC fails to compile LLVM with a 294 bogus template error. This was fixed in later GCCs. 295 296 **GCC 3.3.2**: This version of GCC suffered from a `serious bug 297 <http://gcc.gnu.org/PR13392>`_ which causes it to crash in the 298 "``convert_from_eh_region_ranges_1``" GCC function. 299 300 **Cygwin GCC 3.3.3**: The version of GCC 3.3.3 commonly shipped with Cygwin does 301 not work. 302 303 **SuSE GCC 3.3.3**: The version of GCC 3.3.3 shipped with SuSE 9.1 (and possibly 304 others) does not compile LLVM correctly (it appears that exception handling is 305 broken in some cases). Please download the FSF 3.3.3 or upgrade to a newer 306 version of GCC. 307 308 **GCC 3.4.0 on linux/x86 (32-bit)**: GCC miscompiles portions of the code 309 generator, causing an infinite loop in the llvm-gcc build when built with 310 optimizations enabled (i.e. a release build). 311 312 **GCC 3.4.2 on linux/x86 (32-bit)**: GCC miscompiles portions of the code 313 generator at -O3, as with 3.4.0. However gcc 3.4.2 (unlike 3.4.0) correctly 314 compiles LLVM at -O2. A work around is to build release LLVM builds with 315 "``make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ...``" 316 317 **GCC 3.4.x on X86-64/amd64**: GCC `miscompiles portions of LLVM 318 <http://llvm.org/PR1056>`__. 319 320 **GCC 3.4.4 (CodeSourcery ARM 2005q3-2)**: this compiler miscompiles LLVM when 321 building with optimizations enabled. It appears to work with "``make 322 ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1``" or build a debug build. 323 324 **IA-64 GCC 4.0.0**: The IA-64 version of GCC 4.0.0 is known to miscompile LLVM. 325 326 **Apple Xcode 2.3**: GCC crashes when compiling LLVM at -O3 (which is the 327 default with ENABLE_OPTIMIZED=1. To work around this, build with 328 "``ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2``". 329 330 **GCC 4.1.1**: GCC fails to build LLVM with template concept check errors 331 compiling some files. At the time of this writing, GCC mainline (4.2) did not 332 share the problem. 333 334 **GCC 4.1.1 on X86-64/amd64**: GCC `miscompiles portions of LLVM 335 <http://llvm.org/PR1063>`__ when compiling llvm itself into 64-bit code. LLVM 336 will appear to mostly work but will be buggy, e.g. failing portions of its 337 testsuite. 338 339 **GCC 4.1.2 on OpenSUSE**: Seg faults during libstdc++ build and on x86_64 340 platforms compiling md5.c gets a mangled constant. 341 342 **GCC 4.1.2 (20061115 (prerelease) (Debian 4.1.1-21)) on Debian**: Appears to 343 miscompile parts of LLVM 2.4. One symptom is ValueSymbolTable complaining about 344 symbols remaining in the table on destruction. 345 346 **GCC 4.1.2 20071124 (Red Hat 4.1.2-42)**: Suffers from the same symptoms as the 347 previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default). 348 349 **Cygwin GCC 4.3.2 20080827 (beta) 2**: Users `reported 350 <http://llvm.org/PR4145>`_ various problems related with link errors when using 351 this GCC version. 352 353 **Debian GCC 4.3.2 on X86**: Crashes building some files in LLVM 2.6. 354 355 **GCC 4.3.3 (Debian 4.3.3-10) on ARM**: Miscompiles parts of LLVM 2.6 when 356 optimizations are turned on. The symptom is an infinite loop in 357 ``FoldingSetImpl::RemoveNode`` while running the code generator. 358 359 **SUSE 11 GCC 4.3.4**: Miscompiles LLVM, causing crashes in ValueHandle logic. 360 361 **GCC 4.3.5 and GCC 4.4.5 on ARM**: These can miscompile ``value >> 1`` even at 362 ``-O0``. A test failure in ``test/Assembler/alignstack.ll`` is one symptom of 363 the problem. 364 365 **GCC 4.6.3 on ARM**: Miscompiles ``llvm-readobj`` at ``-O3``. A test failure 366 in ``test/Object/readobj-shared-object.test`` is one symptom of the problem. 367 368 **GNU ld 2.16.X**. Some 2.16.X versions of the ld linker will produce very long 369 warning messages complaining that some "``.gnu.linkonce.t.*``" symbol was 370 defined in a discarded section. You can safely ignore these messages as they are 371 erroneous and the linkage is correct. These messages disappear using ld 2.17. 372 373 **GNU binutils 2.17**: Binutils 2.17 contains `a bug 374 <http://sourceware.org/bugzilla/show_bug.cgi?id=3111>`__ which causes huge link 375 times (minutes instead of seconds) when building LLVM. We recommend upgrading 376 to a newer version (2.17.50.0.4 or later). 377 378 **GNU Binutils 2.19.1 Gold**: This version of Gold contained `a bug 379 <http://sourceware.org/bugzilla/show_bug.cgi?id=9836>`__ which causes 380 intermittent failures when building LLVM with position independent code. The 381 symptom is an error about cyclic dependencies. We recommend upgrading to a 382 newer version of Gold. 383 384 **Clang 3.0 with libstdc++ 4.7.x**: a few Linux distributions (Ubuntu 12.10, 385 Fedora 17) have both Clang 3.0 and libstdc++ 4.7 in their repositories. Clang 386 3.0 does not implement a few builtins that are used in this library. We 387 recommend using the system GCC to compile LLVM and Clang in this case. 388 389 **Clang 3.0 on Mageia 2**. There's a packaging issue: Clang can not find at 390 least some (``cxxabi.h``) libstdc++ headers. 391 392 .. _Getting Started with LLVM: 393 394 Getting Started with LLVM 395 ========================= 396 397 The remainder of this guide is meant to get you up and running with LLVM and to 398 give you some basic information about the LLVM environment. 399 400 The later sections of this guide describe the `general layout`_ of the LLVM 401 source tree, a `simple example`_ using the LLVM tool chain, and `links`_ to find 402 more information about LLVM or to get help via e-mail. 403 404 Terminology and Notation 405 ------------------------ 406 407 Throughout this manual, the following names are used to denote paths specific to 408 the local system and working environment. *These are not environment variables 409 you need to set but just strings used in the rest of this document below*. In 410 any of the examples below, simply replace each of these names with the 411 appropriate pathname on your local system. All these paths are absolute: 412 413 ``SRC_ROOT`` 414 415 This is the top level directory of the LLVM source tree. 416 417 ``OBJ_ROOT`` 418 419 This is the top level directory of the LLVM object tree (i.e. the tree where 420 object files and compiled programs will be placed. It can be the same as 421 SRC_ROOT). 422 423 .. _Setting Up Your Environment: 424 425 Setting Up Your Environment 426 --------------------------- 427 428 In order to compile and use LLVM, you may need to set some environment 429 variables. 430 431 ``LLVM_LIB_SEARCH_PATH=/path/to/your/bitcode/libs`` 432 433 [Optional] This environment variable helps LLVM linking tools find the 434 locations of your bitcode libraries. It is provided only as a convenience 435 since you can specify the paths using the -L options of the tools and the 436 C/C++ front-end will automatically use the bitcode files installed in its 437 ``lib`` directory. 438 439 Unpacking the LLVM Archives 440 --------------------------- 441 442 If you have the LLVM distribution, you will need to unpack it before you can 443 begin to compile it. LLVM is distributed as a set of two files: the LLVM suite 444 and the LLVM GCC front end compiled for your platform. There is an additional 445 test suite that is optional. Each file is a TAR archive that is compressed with 446 the gzip program. 447 448 The files are as follows, with *x.y* marking the version number: 449 450 ``llvm-x.y.tar.gz`` 451 452 Source release for the LLVM libraries and tools. 453 454 ``llvm-test-x.y.tar.gz`` 455 456 Source release for the LLVM test-suite. 457 458 ``llvm-gcc-4.2-x.y.source.tar.gz`` 459 460 Source release of the llvm-gcc-4.2 front end. See README.LLVM in the root 461 directory for build instructions. 462 463 ``llvm-gcc-4.2-x.y-platform.tar.gz`` 464 465 Binary release of the llvm-gcc-4.2 front end for a specific platform. 466 467 .. _checkout: 468 469 Checkout LLVM from Subversion 470 ----------------------------- 471 472 If you have access to our Subversion repository, you can get a fresh copy of the 473 entire source code. All you need to do is check it out from Subversion as 474 follows: 475 476 * ``cd where-you-want-llvm-to-live`` 477 * Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` 478 * Read-Write:``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm`` 479 480 This will create an '``llvm``' directory in the current directory and fully 481 populate it with the LLVM source code, Makefiles, test directories, and local 482 copies of documentation files. 483 484 If you want to get a specific release (as opposed to the most recent revision), 485 you can checkout it from the '``tags``' directory (instead of '``trunk``'). The 486 following releases are located in the following subdirectories of the '``tags``' 487 directory: 488 489 * Release 3.1: **RELEASE_31/final** 490 * Release 3.0: **RELEASE_30/final** 491 * Release 2.9: **RELEASE_29/final** 492 * Release 2.8: **RELEASE_28** 493 * Release 2.7: **RELEASE_27** 494 * Release 2.6: **RELEASE_26** 495 * Release 2.5: **RELEASE_25** 496 * Release 2.4: **RELEASE_24** 497 * Release 2.3: **RELEASE_23** 498 * Release 2.2: **RELEASE_22** 499 * Release 2.1: **RELEASE_21** 500 * Release 2.0: **RELEASE_20** 501 * Release 1.9: **RELEASE_19** 502 * Release 1.8: **RELEASE_18** 503 * Release 1.7: **RELEASE_17** 504 * Release 1.6: **RELEASE_16** 505 * Release 1.5: **RELEASE_15** 506 * Release 1.4: **RELEASE_14** 507 * Release 1.3: **RELEASE_13** 508 * Release 1.2: **RELEASE_12** 509 * Release 1.1: **RELEASE_11** 510 * Release 1.0: **RELEASE_1** 511 512 If you would like to get the LLVM test suite (a separate package as of 1.4), you 513 get it from the Subversion repository: 514 515 .. code-block:: console 516 517 % cd llvm/projects 518 % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite 519 520 By placing it in the ``llvm/projects``, it will be automatically configured by 521 the LLVM configure script as well as automatically updated when you run ``svn 522 update``. 523 524 GIT mirror 525 ---------- 526 527 GIT mirrors are available for a number of LLVM subprojects. These mirrors sync 528 automatically with each Subversion commit and contain all necessary git-svn 529 marks (so, you can recreate git-svn metadata locally). Note that right now 530 mirrors reflect only ``trunk`` for each project. You can do the read-only GIT 531 clone of LLVM via: 532 533 .. code-block:: console 534 535 % git clone http://llvm.org/git/llvm.git 536 537 If you want to check out clang too, run: 538 539 .. code-block:: console 540 541 % git clone http://llvm.org/git/llvm.git 542 % cd llvm/tools 543 % git clone http://llvm.org/git/clang.git 544 545 Since the upstream repository is in Subversion, you should use ``git 546 pull --rebase`` instead of ``git pull`` to avoid generating a non-linear history 547 in your clone. To configure ``git pull`` to pass ``--rebase`` by default on the 548 master branch, run the following command: 549 550 .. code-block:: console 551 552 % git config branch.master.rebase true 553 554 Sending patches with Git 555 ^^^^^^^^^^^^^^^^^^^^^^^^ 556 557 Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too. 558 559 Assume ``master`` points the upstream and ``mybranch`` points your working 560 branch, and ``mybranch`` is rebased onto ``master``. At first you may check 561 sanity of whitespaces: 562 563 .. code-block:: console 564 565 % git diff --check master..mybranch 566 567 The easiest way to generate a patch is as below: 568 569 .. code-block:: console 570 571 % git diff master..mybranch > /path/to/mybranch.diff 572 573 It is a little different from svn-generated diff. git-diff-generated diff has 574 prefixes like ``a/`` and ``b/``. Don't worry, most developers might know it 575 could be accepted with ``patch -p1 -N``. 576 577 But you may generate patchset with git-format-patch. It generates by-each-commit 578 patchset. To generate patch files to attach to your article: 579 580 .. code-block:: console 581 582 % git format-patch --no-attach master..mybranch -o /path/to/your/patchset 583 584 If you would like to send patches directly, you may use git-send-email or 585 git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts]. 586 587 .. code-block:: console 588 589 % git format-patch --attach master..mybranch --stdout | git imap-send 590 591 Then, your .git/config should have [imap] sections. 592 593 .. code-block:: ini 594 595 [imap] 596 host = imaps://imap.gmail.com 597 user = your.gmail.account (a] gmail.com 598 pass = himitsu! 599 port = 993 600 sslverify = false 601 ; in English 602 folder = "[Gmail]/Drafts" 603 ; example for Japanese, "Modified UTF-7" encoded. 604 folder = "[Gmail]/&Tgtm+DBN-" 605 ; example for Traditional Chinese 606 folder = "[Gmail]/&g0l6Pw-" 607 608 For developers to work with git-svn 609 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 610 611 To set up clone from which you can submit code using ``git-svn``, run: 612 613 .. code-block:: console 614 615 % git clone http://llvm.org/git/llvm.git 616 % cd llvm 617 % git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username> 618 % git config svn-remote.svn.fetch :refs/remotes/origin/master 619 % git svn rebase -l # -l avoids fetching ahead of the git mirror. 620 621 # If you have clang too: 622 % cd tools 623 % git clone http://llvm.org/git/clang.git 624 % cd clang 625 % git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username> 626 % git config svn-remote.svn.fetch :refs/remotes/origin/master 627 % git svn rebase -l 628 629 To update this clone without generating git-svn tags that conflict with the 630 upstream git repo, run: 631 632 .. code-block:: console 633 634 % git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees. 635 % git checkout master 636 % git svn rebase -l 637 % (cd tools/clang && 638 git checkout master && 639 git svn rebase -l) 640 641 This leaves your working directories on their master branches, so you'll need to 642 ``checkout`` each working branch individually and ``rebase`` it on top of its 643 parent branch. 644 645 For those who wish to be able to update an llvm repo in a simpler fashion, 646 consider placing the following git script in your path under the name 647 ``git-svnup``: 648 649 .. code-block:: bash 650 651 #!/bin/bash 652 653 STATUS=$(git status -s | grep -v "??") 654 655 if [ ! -z "$STATUS" ]; then 656 STASH="yes" 657 git stash >/dev/null 658 fi 659 660 git fetch 661 OLD_BRANCH=$(git rev-parse --abbrev-ref HEAD) 662 git checkout master 2> /dev/null 663 git svn rebase -l 664 git checkout $OLD_BRANCH 2> /dev/null 665 666 if [ ! -z $STASH ]; then 667 git stash pop >/dev/null 668 fi 669 670 Then to perform the aforementioned update steps go into your source directory 671 and just type ``git-svnup`` or ``git svnup`` and everything will just work. 672 673 To commit back changes via git-svn, use ``dcommit``: 674 675 .. code-block:: console 676 677 % git svn dcommit 678 679 Note that git-svn will create one SVN commit for each Git commit you have pending, 680 so squash and edit each commit before executing ``dcommit`` to make sure they all 681 conform to the coding standards and the developers' policy. 682 683 On success, ``dcommit`` will rebase against the HEAD of SVN, so to avoid conflict, 684 please make sure your current branch is up-to-date (via fetch/rebase) before 685 proceeding. 686 687 The git-svn metadata can get out of sync after you mess around with branches and 688 ``dcommit``. When that happens, ``git svn dcommit`` stops working, complaining 689 about files with uncommitted changes. The fix is to rebuild the metadata: 690 691 .. code-block:: console 692 693 % rm -rf .git/svn 694 % git svn rebase -l 695 696 Please, refer to the Git-SVN manual (``man git-svn``) for more information. 697 698 Local LLVM Configuration 699 ------------------------ 700 701 Once checked out from the Subversion repository, the LLVM suite source code must 702 be configured via the ``configure`` script. This script sets variables in the 703 various ``*.in`` files, most notably ``llvm/Makefile.config`` and 704 ``llvm/include/Config/config.h``. It also populates *OBJ_ROOT* with the 705 Makefiles needed to begin building LLVM. 706 707 The following environment variables are used by the ``configure`` script to 708 configure the build system: 709 710 +------------+-----------------------------------------------------------+ 711 | Variable | Purpose | 712 +============+===========================================================+ 713 | CC | Tells ``configure`` which C compiler to use. By default, | 714 | | ``configure`` will check ``PATH`` for ``clang`` and GCC C | 715 | | compilers (in this order). Use this variable to override | 716 | | ``configure``\'s default behavior. | 717 +------------+-----------------------------------------------------------+ 718 | CXX | Tells ``configure`` which C++ compiler to use. By | 719 | | default, ``configure`` will check ``PATH`` for | 720 | | ``clang++`` and GCC C++ compilers (in this order). Use | 721 | | this variable to override ``configure``'s default | 722 | | behavior. | 723 +------------+-----------------------------------------------------------+ 724 725 The following options can be used to set or enable LLVM specific options: 726 727 ``--enable-optimized`` 728 729 Enables optimized compilation (debugging symbols are removed and GCC 730 optimization flags are enabled). Note that this is the default setting if you 731 are using the LLVM distribution. The default behavior of an Subversion 732 checkout is to use an unoptimized build (also known as a debug build). 733 734 ``--enable-debug-runtime`` 735 736 Enables debug symbols in the runtime libraries. The default is to strip debug 737 symbols from the runtime libraries. 738 739 ``--enable-jit`` 740 741 Compile the Just In Time (JIT) compiler functionality. This is not available 742 on all platforms. The default is dependent on platform, so it is best to 743 explicitly enable it if you want it. 744 745 ``--enable-targets=target-option`` 746 747 Controls which targets will be built and linked into llc. The default value 748 for ``target_options`` is "all" which builds and links all available targets. 749 The value "host-only" can be specified to build only a native compiler (no 750 cross-compiler targets available). The "native" target is selected as the 751 target of the build host. You can also specify a comma separated list of 752 target names that you want available in llc. The target names use all lower 753 case. The current set of targets is: 754 755 ``arm, cpp, hexagon, mblaze, mips, mipsel, msp430, powerpc, ptx, sparc, spu, 756 x86, x86_64, xcore``. 757 758 ``--enable-doxygen`` 759 760 Look for the doxygen program and enable construction of doxygen based 761 documentation from the source code. This is disabled by default because 762 generating the documentation can take a long time and producess 100s of 763 megabytes of output. 764 765 ``--with-udis86`` 766 767 LLVM can use external disassembler library for various purposes (now it's used 768 only for examining code produced by JIT). This option will enable usage of 769 `udis86 <http://udis86.sourceforge.net/>`_ x86 (both 32 and 64 bits) 770 disassembler library. 771 772 To configure LLVM, follow these steps: 773 774 #. Change directory into the object root directory: 775 776 .. code-block:: console 777 778 % cd OBJ_ROOT 779 780 #. Run the ``configure`` script located in the LLVM source tree: 781 782 .. code-block:: console 783 784 % SRC_ROOT/configure --prefix=/install/path [other options] 785 786 Compiling the LLVM Suite Source Code 787 ------------------------------------ 788 789 Once you have configured LLVM, you can build it. There are three types of 790 builds: 791 792 Debug Builds 793 794 These builds are the default when one is using an Subversion checkout and 795 types ``gmake`` (unless the ``--enable-optimized`` option was used during 796 configuration). The build system will compile the tools and libraries with 797 debugging information. To get a Debug Build using the LLVM distribution the 798 ``--disable-optimized`` option must be passed to ``configure``. 799 800 Release (Optimized) Builds 801 802 These builds are enabled with the ``--enable-optimized`` option to 803 ``configure`` or by specifying ``ENABLE_OPTIMIZED=1`` on the ``gmake`` command 804 line. For these builds, the build system will compile the tools and libraries 805 with GCC optimizations enabled and strip debugging information from the 806 libraries and executables it generates. Note that Release Builds are default 807 when using an LLVM distribution. 808 809 Profile Builds 810 811 These builds are for use with profiling. They compile profiling information 812 into the code for use with programs like ``gprof``. Profile builds must be 813 started by specifying ``ENABLE_PROFILING=1`` on the ``gmake`` command line. 814 815 Once you have LLVM configured, you can build it by entering the *OBJ_ROOT* 816 directory and issuing the following command: 817 818 .. code-block:: console 819 820 % gmake 821 822 If the build fails, please `check here`_ to see if you are using a version of 823 GCC that is known not to compile LLVM. 824 825 If you have multiple processors in your machine, you may wish to use some of the 826 parallel build options provided by GNU Make. For example, you could use the 827 command: 828 829 .. code-block:: console 830 831 % gmake -j2 832 833 There are several special targets which are useful when working with the LLVM 834 source code: 835 836 ``gmake clean`` 837 838 Removes all files generated by the build. This includes object files, 839 generated C/C++ files, libraries, and executables. 840 841 ``gmake dist-clean`` 842 843 Removes everything that ``gmake clean`` does, but also removes files generated 844 by ``configure``. It attempts to return the source tree to the original state 845 in which it was shipped. 846 847 ``gmake install`` 848 849 Installs LLVM header files, libraries, tools, and documentation in a hierarchy 850 under ``$PREFIX``, specified with ``./configure --prefix=[dir]``, which 851 defaults to ``/usr/local``. 852 853 ``gmake -C runtime install-bytecode`` 854 855 Assuming you built LLVM into $OBJDIR, when this command is run, it will 856 install bitcode libraries into the GCC front end's bitcode library directory. 857 If you need to update your bitcode libraries, this is the target to use once 858 you've built them. 859 860 Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on 861 these ``make`` targets and descriptions of other targets available. 862 863 It is also possible to override default values from ``configure`` by declaring 864 variables on the command line. The following are some examples: 865 866 ``gmake ENABLE_OPTIMIZED=1`` 867 868 Perform a Release (Optimized) build. 869 870 ``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1`` 871 872 Perform a Release (Optimized) build without assertions enabled. 873 874 ``gmake ENABLE_OPTIMIZED=0`` 875 876 Perform a Debug build. 877 878 ``gmake ENABLE_PROFILING=1`` 879 880 Perform a Profiling build. 881 882 ``gmake VERBOSE=1`` 883 884 Print what ``gmake`` is doing on standard output. 885 886 ``gmake TOOL_VERBOSE=1`` 887 888 Ask each tool invoked by the makefiles to print out what it is doing on 889 the standard output. This also implies ``VERBOSE=1``. 890 891 Every directory in the LLVM object tree includes a ``Makefile`` to build it and 892 any subdirectories that it contains. Entering any directory inside the LLVM 893 object tree and typing ``gmake`` should rebuild anything in or below that 894 directory that is out of date. 895 896 This does not apply to building the documentation. 897 LLVM's (non-Doxygen) documentation is produced with the 898 `Sphinx <http://sphinx-doc.org/>`_ documentation generation system. 899 There are some HTML documents that have not yet been converted to the new 900 system (which uses the easy-to-read and easy-to-write 901 `reStructuredText <http://sphinx-doc.org/rest.html>`_ plaintext markup 902 language). 903 The generated documentation is built in the ``SRC_ROOT/docs`` directory using 904 a special makefile. 905 For instructions on how to install Sphinx, see 906 `Sphinx Introduction for LLVM Developers 907 <http://lld.llvm.org/sphinx_intro.html>`_. 908 After following the instructions there for installing Sphinx, build the LLVM 909 HTML documentation by doing the following: 910 911 .. code-block:: console 912 913 $ cd SRC_ROOT/docs 914 $ make -f Makefile.sphinx 915 916 This creates a ``_build/html`` sub-directory with all of the HTML files, not 917 just the generated ones. 918 This directory corresponds to ``llvm.org/docs``. 919 For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to 920 ``llvm.org/docs/SphinxQuickstartTemplate.html``. 921 The :doc:`SphinxQuickstartTemplate` is useful when creating a new document. 922 923 Cross-Compiling LLVM 924 -------------------- 925 926 It is possible to cross-compile LLVM itself. That is, you can create LLVM 927 executables and libraries to be hosted on a platform different from the platform 928 where they are built (a Canadian Cross build). To configure a cross-compile, 929 supply the configure script with ``--build`` and ``--host`` options that are 930 different. The values of these options must be legal target triples that your 931 GCC compiler supports. 932 933 The result of such a build is executables that are not runnable on on the build 934 host (--build option) but can be executed on the compile host (--host option). 935 936 The Location of LLVM Object Files 937 --------------------------------- 938 939 The LLVM build system is capable of sharing a single LLVM source tree among 940 several LLVM builds. Hence, it is possible to build LLVM for several different 941 platforms or configurations using the same source tree. 942 943 This is accomplished in the typical autoconf manner: 944 945 * Change directory to where the LLVM object files should live: 946 947 .. code-block:: console 948 949 % cd OBJ_ROOT 950 951 * Run the ``configure`` script found in the LLVM source directory: 952 953 .. code-block:: console 954 955 % SRC_ROOT/configure 956 957 The LLVM build will place files underneath *OBJ_ROOT* in directories named after 958 the build type: 959 960 Debug Builds with assertions enabled (the default) 961 962 Tools 963 964 ``OBJ_ROOT/Debug+Asserts/bin`` 965 966 Libraries 967 968 ``OBJ_ROOT/Debug+Asserts/lib`` 969 970 Release Builds 971 972 Tools 973 974 ``OBJ_ROOT/Release/bin`` 975 976 Libraries 977 978 ``OBJ_ROOT/Release/lib`` 979 980 Profile Builds 981 982 Tools 983 984 ``OBJ_ROOT/Profile/bin`` 985 986 Libraries 987 988 ``OBJ_ROOT/Profile/lib`` 989 990 Optional Configuration Items 991 ---------------------------- 992 993 If you're running on a Linux system that supports the `binfmt_misc 994 <http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html>`_ 995 module, and you have root access on the system, you can set your system up to 996 execute LLVM bitcode files directly. To do this, use commands like this (the 997 first command may not be required if you are already using the module): 998 999 .. code-block:: console 1000 1001 % mount -t binfmt_misc none /proc/sys/fs/binfmt_misc 1002 % echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register 1003 % chmod u+x hello.bc (if needed) 1004 % ./hello.bc 1005 1006 This allows you to execute LLVM bitcode files directly. On Debian, you can also 1007 use this command instead of the 'echo' command above: 1008 1009 .. code-block:: console 1010 1011 % sudo update-binfmts --install llvm /path/to/lli --magic 'BC' 1012 1013 .. _Program Layout: 1014 .. _general layout: 1015 1016 Program Layout 1017 ============== 1018 1019 One useful source of information about the LLVM source base is the LLVM `doxygen 1020 <http://www.doxygen.org/>`_ documentation available at 1021 `<http://llvm.org/doxygen/>`_. The following is a brief introduction to code 1022 layout: 1023 1024 ``llvm/examples`` 1025 ----------------- 1026 1027 This directory contains some simple examples of how to use the LLVM IR and JIT. 1028 1029 ``llvm/include`` 1030 ---------------- 1031 1032 This directory contains public header files exported from the LLVM library. The 1033 three main subdirectories of this directory are: 1034 1035 ``llvm/include/llvm`` 1036 1037 This directory contains all of the LLVM specific header files. This directory 1038 also has subdirectories for different portions of LLVM: ``Analysis``, 1039 ``CodeGen``, ``Target``, ``Transforms``, etc... 1040 1041 ``llvm/include/llvm/Support`` 1042 1043 This directory contains generic support libraries that are provided with LLVM 1044 but not necessarily specific to LLVM. For example, some C++ STL utilities and 1045 a Command Line option processing library store their header files here. 1046 1047 ``llvm/include/llvm/Config`` 1048 1049 This directory contains header files configured by the ``configure`` script. 1050 They wrap "standard" UNIX and C header files. Source code can include these 1051 header files which automatically take care of the conditional #includes that 1052 the ``configure`` script generates. 1053 1054 ``llvm/lib`` 1055 ------------ 1056 1057 This directory contains most of the source files of the LLVM system. In LLVM, 1058 almost all code exists in libraries, making it very easy to share code among the 1059 different `tools`_. 1060 1061 ``llvm/lib/VMCore/`` 1062 1063 This directory holds the core LLVM source files that implement core classes 1064 like Instruction and BasicBlock. 1065 1066 ``llvm/lib/AsmParser/`` 1067 1068 This directory holds the source code for the LLVM assembly language parser 1069 library. 1070 1071 ``llvm/lib/BitCode/`` 1072 1073 This directory holds code for reading and write LLVM bitcode. 1074 1075 ``llvm/lib/Analysis/`` 1076 1077 This directory contains a variety of different program analyses, such as 1078 Dominator Information, Call Graphs, Induction Variables, Interval 1079 Identification, Natural Loop Identification, etc. 1080 1081 ``llvm/lib/Transforms/`` 1082 1083 This directory contains the source code for the LLVM to LLVM program 1084 transformations, such as Aggressive Dead Code Elimination, Sparse Conditional 1085 Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global 1086 Elimination, and many others. 1087 1088 ``llvm/lib/Target/`` 1089 1090 This directory contains files that describe various target architectures for 1091 code generation. For example, the ``llvm/lib/Target/X86`` directory holds the 1092 X86 machine description while ``llvm/lib/Target/ARM`` implements the ARM 1093 backend. 1094 1095 ``llvm/lib/CodeGen/`` 1096 1097 This directory contains the major parts of the code generator: Instruction 1098 Selector, Instruction Scheduling, and Register Allocation. 1099 1100 ``llvm/lib/MC/`` 1101 1102 (FIXME: T.B.D.) 1103 1104 ``llvm/lib/Debugger/`` 1105 1106 This directory contains the source level debugger library that makes it 1107 possible to instrument LLVM programs so that a debugger could identify source 1108 code locations at which the program is executing. 1109 1110 ``llvm/lib/ExecutionEngine/`` 1111 1112 This directory contains libraries for executing LLVM bitcode directly at 1113 runtime in both interpreted and JIT compiled fashions. 1114 1115 ``llvm/lib/Support/`` 1116 1117 This directory contains the source code that corresponds to the header files 1118 located in ``llvm/include/ADT/`` and ``llvm/include/Support/``. 1119 1120 ``llvm/projects`` 1121 ----------------- 1122 1123 This directory contains projects that are not strictly part of LLVM but are 1124 shipped with LLVM. This is also the directory where you should create your own 1125 LLVM-based projects. See ``llvm/projects/sample`` for an example of how to set 1126 up your own project. 1127 1128 ``llvm/runtime`` 1129 ---------------- 1130 1131 This directory contains libraries which are compiled into LLVM bitcode and used 1132 when linking programs with the Clang front end. Most of these libraries are 1133 skeleton versions of real libraries; for example, libc is a stripped down 1134 version of glibc. 1135 1136 Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end 1137 to compile. 1138 1139 ``llvm/test`` 1140 ------------- 1141 1142 This directory contains feature and regression tests and other basic sanity 1143 checks on the LLVM infrastructure. These are intended to run quickly and cover a 1144 lot of territory without being exhaustive. 1145 1146 ``test-suite`` 1147 -------------- 1148 1149 This is not a directory in the normal llvm module; it is a separate Subversion 1150 module that must be checked out (usually to ``projects/test-suite``). This 1151 module contains a comprehensive correctness, performance, and benchmarking test 1152 suite for LLVM. It is a separate Subversion module because not every LLVM user 1153 is interested in downloading or building such a comprehensive test suite. For 1154 further details on this test suite, please see the :doc:`Testing Guide 1155 <TestingGuide>` document. 1156 1157 .. _tools: 1158 1159 ``llvm/tools`` 1160 -------------- 1161 1162 The **tools** directory contains the executables built out of the libraries 1163 above, which form the main part of the user interface. You can always get help 1164 for a tool by typing ``tool_name -help``. The following is a brief introduction 1165 to the most important tools. More detailed information is in 1166 the `Command Guide <CommandGuide/index.html>`_. 1167 1168 ``bugpoint`` 1169 1170 ``bugpoint`` is used to debug optimization passes or code generation backends 1171 by narrowing down the given test case to the minimum number of passes and/or 1172 instructions that still cause a problem, whether it is a crash or 1173 miscompilation. See `<HowToSubmitABug.html>`_ for more information on using 1174 ``bugpoint``. 1175 1176 ``llvm-ar`` 1177 1178 The archiver produces an archive containing the given LLVM bitcode files, 1179 optionally with an index for faster lookup. 1180 1181 ``llvm-as`` 1182 1183 The assembler transforms the human readable LLVM assembly to LLVM bitcode. 1184 1185 ``llvm-dis`` 1186 1187 The disassembler transforms the LLVM bitcode to human readable LLVM assembly. 1188 1189 ``llvm-link`` 1190 1191 ``llvm-link``, not surprisingly, links multiple LLVM modules into a single 1192 program. 1193 1194 ``lli`` 1195 1196 ``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode 1197 (although very slowly...). For architectures that support it (currently x86, 1198 Sparc, and PowerPC), by default, ``lli`` will function as a Just-In-Time 1199 compiler (if the functionality was compiled in), and will execute the code 1200 *much* faster than the interpreter. 1201 1202 ``llc`` 1203 1204 ``llc`` is the LLVM backend compiler, which translates LLVM bitcode to a 1205 native code assembly file or to C code (with the ``-march=c`` option). 1206 1207 ``opt`` 1208 1209 ``opt`` reads LLVM bitcode, applies a series of LLVM to LLVM transformations 1210 (which are specified on the command line), and then outputs the resultant 1211 bitcode. The '``opt -help``' command is a good way to get a list of the 1212 program transformations available in LLVM. 1213 1214 ``opt`` can also be used to run a specific analysis on an input LLVM bitcode 1215 file and print out the results. It is primarily useful for debugging 1216 analyses, or familiarizing yourself with what an analysis does. 1217 1218 ``llvm/utils`` 1219 -------------- 1220 1221 This directory contains utilities for working with LLVM source code, and some of 1222 the utilities are actually required as part of the build process because they 1223 are code generators for parts of LLVM infrastructure. 1224 1225 1226 ``codegen-diff`` 1227 1228 ``codegen-diff`` is a script that finds differences between code that LLC 1229 generates and code that LLI generates. This is a useful tool if you are 1230 debugging one of them, assuming that the other generates correct output. For 1231 the full user manual, run ```perldoc codegen-diff'``. 1232 1233 ``emacs/`` 1234 1235 The ``emacs`` directory contains syntax-highlighting files which will work 1236 with Emacs and XEmacs editors, providing syntax highlighting support for LLVM 1237 assembly files and TableGen description files. For information on how to use 1238 the syntax files, consult the ``README`` file in that directory. 1239 1240 ``getsrcs.sh`` 1241 1242 The ``getsrcs.sh`` script finds and outputs all non-generated source files, 1243 which is useful if one wishes to do a lot of development across directories 1244 and does not want to individually find each file. One way to use it is to run, 1245 for example: ``xemacs `utils/getsources.sh``` from the top of your LLVM source 1246 tree. 1247 1248 ``llvmgrep`` 1249 1250 This little tool performs an ``egrep -H -n`` on each source file in LLVM and 1251 passes to it a regular expression provided on ``llvmgrep``'s command 1252 line. This is a very efficient way of searching the source base for a 1253 particular regular expression. 1254 1255 ``makellvm`` 1256 1257 The ``makellvm`` script compiles all files in the current directory and then 1258 compiles and links the tool that is the first argument. For example, assuming 1259 you are in the directory ``llvm/lib/Target/Sparc``, if ``makellvm`` is in your 1260 path, simply running ``makellvm llc`` will make a build of the current 1261 directory, switch to directory ``llvm/tools/llc`` and build it, causing a 1262 re-linking of LLC. 1263 1264 ``TableGen/`` 1265 1266 The ``TableGen`` directory contains the tool used to generate register 1267 descriptions, instruction set descriptions, and even assemblers from common 1268 TableGen description files. 1269 1270 ``vim/`` 1271 1272 The ``vim`` directory contains syntax-highlighting files which will work with 1273 the VIM editor, providing syntax highlighting support for LLVM assembly files 1274 and TableGen description files. For information on how to use the syntax 1275 files, consult the ``README`` file in that directory. 1276 1277 .. _simple example: 1278 1279 An Example Using the LLVM Tool Chain 1280 ==================================== 1281 1282 This section gives an example of using LLVM with the Clang front end. 1283 1284 Example with clang 1285 ------------------ 1286 1287 #. First, create a simple C file, name it 'hello.c': 1288 1289 .. code-block:: c 1290 1291 #include <stdio.h> 1292 1293 int main() { 1294 printf("hello world\n"); 1295 return 0; 1296 } 1297 1298 #. Next, compile the C file into a native executable: 1299 1300 .. code-block:: console 1301 1302 % clang hello.c -o hello 1303 1304 .. note:: 1305 1306 Clang works just like GCC by default. The standard -S and -c arguments 1307 work as usual (producing a native .s or .o file, respectively). 1308 1309 #. Next, compile the C file into a LLVM bitcode file: 1310 1311 .. code-block:: console 1312 1313 % clang -O3 -emit-llvm hello.c -c -o hello.bc 1314 1315 The -emit-llvm option can be used with the -S or -c options to emit an LLVM 1316 ``.ll`` or ``.bc`` file (respectively) for the code. This allows you to use 1317 the `standard LLVM tools <CommandGuide/index.html>`_ on the bitcode file. 1318 1319 #. Run the program in both forms. To run the program, use: 1320 1321 .. code-block:: console 1322 1323 % ./hello 1324 1325 and 1326 1327 .. code-block:: console 1328 1329 % lli hello.bc 1330 1331 The second examples shows how to invoke the LLVM JIT, :doc:`lli 1332 <CommandGuide/lli>`. 1333 1334 #. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code: 1335 1336 .. code-block:: console 1337 1338 % llvm-dis < hello.bc | less 1339 1340 #. Compile the program to native assembly using the LLC code generator: 1341 1342 .. code-block:: console 1343 1344 % llc hello.bc -o hello.s 1345 1346 #. Assemble the native assembly language file into a program: 1347 1348 .. code-block:: console 1349 1350 % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native # On Solaris 1351 1352 % gcc hello.s -o hello.native # On others 1353 1354 #. Execute the native code program: 1355 1356 .. code-block:: console 1357 1358 % ./hello.native 1359 1360 Note that using clang to compile directly to native code (i.e. when the 1361 ``-emit-llvm`` option is not present) does steps 6/7/8 for you. 1362 1363 Common Problems 1364 =============== 1365 1366 If you are having problems building or using LLVM, or if you have any other 1367 general questions about LLVM, please consult the `Frequently Asked 1368 Questions <FAQ.html>`_ page. 1369 1370 .. _links: 1371 1372 Links 1373 ===== 1374 1375 This document is just an **introduction** on how to use LLVM to do some simple 1376 things... there are many more interesting and complicated things that you can do 1377 that aren't documented here (but we'll gladly accept a patch if you want to 1378 write something up!). For more information about LLVM, check out: 1379 1380 * `LLVM Homepage <http://llvm.org/>`_ 1381 * `LLVM Doxygen Tree <http://llvm.org/doxygen/>`_ 1382 * `Starting a Project that Uses LLVM <http://llvm.org/docs/Projects.html>`_ 1383
