llvm.org GIT mirror llvm / 20d2d3e
Re-did some of the text wrapping (sorry). Made the "Getting Started Quickly" material its own section. I think this makes the document easier to read. Added bars after every major section heading (to distinguish them more easily from sub-section headings). Renamed C front end to GCC front end, as we now support C and C++. Updated material to reflect the new autoconf-style object root. Added material about the llvm/runtime directory and the fact that you need to install the GCC front end before building LLVM (before, it was optional). git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@9003 91177308-0d34-0410-b5e6-96231b3b80d8 John Criswell 16 years ago
1 changed file(s) with 184 addition(s) and 160 deletion(s). Raw diff Collapse all Expand all
2525
  • Software
  • 2626
    2727
    28
  • Getting Started Quickly (A Summary)
  • 2829
  • Getting started with LLVM
  • 2930
    30
  • Getting Started Quickly (A Summary)
  • 3131
  • Terminology and Notation
  • 3232
  • Setting Up Your Environment
  • 3333
  • Unpacking the LLVM Archives
  • 4646
  • llvm/tools
  • 4747
  • llvm/utils
  • 4848
    49
  • Compiling the LLVM C Front End
  • 49
  • Compiling the LLVM GCC Front End
  • 5050
  • An Example Using the LLVM Tool Chain
  • 5151
  • Common Problems
  • 5252
  • Links
  • 5757
    5858

    Overview

    5959
    60
    6061
    6162
    6263 Welcome to LLVM! In order to get started, you first need to know some
    6667 First, LLVM comes in two pieces. The first piece is the LLVM suite. This
    6768 contains all of the tools, libraries, and header files needed to use the
    6869 low level virtual machine. It also contains a test suite that can be used
    69 to test the LLVM tools and the C front end.
    70

    71 The second piece is the C front end. This component provides a version
    72 of GCC that compiles C code into LLVM bytecode. Currently, the C front end
    73 is a modified version of GCC 3.4 (we track the GCC 3.4 development).
    74 Once compiled into LLVM bytecode, a program can be manipulated with the
    75 LLVM tools from the LLVM suite.
    70 to test the LLVM tools and the GCC front end.
    71

    72 The second piece is the GCC front end. This component provides a version
    73 of GCC that compiles C and C++ code into LLVM bytecode. Currently, the
    74 GCC front end is a modified version of GCC 3.4 (we track the GCC 3.4
    75 development). Once compiled into LLVM bytecode, a program can be
    76 manipulated with the LLVM tools from the LLVM suite.
    7677
    7778
    7879

    Requirements

    9394
    9495
  • Source code: 30 MB
  • 9596
  • Object code: 670 MB
  • 96
  • C front end: 60 MB
  • 97
  • GCC front end: 60 MB
  • 9798
    9899
    99100
    105106
    106107
  • Source code: 30 MB
  • 107108
  • Object code: 1000 MB
  • 108
  • C front end: 210 MB
  • 109
  • GCC front end: 210 MB
  • 109110
    110111
    111112
    112113
    113114

    114 If you want to compile your own version of the C front end, you will need
    115 If you want to compile your own version of the GCC front end, you will need
    115116 additional disk space:
    116117

    117118
    209210
    210211
    211212
    212

    The next section of this guide is meant to get

    213 you up and running with LLVM and to give you some basic information about
    214 the LLVM environment. The first subsection gives
    215 a short summary for those who are already familiar with the system and
    216 want to get started as quickly as possible.
    213

    The remainder of this guide is meant to get you up and running with

    214 LLVM and to give you some basic information about the LLVM environment.
    215 The next section gives a short summary for those
    216 who are already familiar with the system and want to get started as quickly
    217 as possible. A more complete description is provided after that.
    217218
    218219

    The later sections of this guide describe the

    219220 href="#layout">general layout of the the LLVM source-tree, a
    223224
    224225
    225226
    226

    Getting Started with LLVM

    227

    Getting Started Quickly (A Summary)

    227228
    228
    229
    230
    231 3>Getting Started Quickly (A Summary)>
    229 r>
    232230
    233231
    234232 Here's the short story for getting up and running quickly with LLVM:
    235233
    236
  • Install the C front end:
  • 234
  • Install the GCC front end:
  • 237235
    238236
  • cd where-you-want-the-C-front-end-to-live
  • 239237
  • gunzip --stdout cfrontend.platform.tar.gz | tar -xvf
  • 248246
    249247
  • cd where-you-want-llvm-to-live
  • 250248
  • gunzip --stdout llvm.tar.gz | tar -xvf -
  • 251
  • gunzip --stdout cfrontend.platform.tar.gz | tar
  • 252 -xvf -
    253249
  • cd llvm
  • 254250
    255251
    270266
    271267
  • Configure the LLVM Build Environment
  • 272268
    273
  • Run configure to configure the Makefiles and header
  • 274 files for the default platform.
    269
  • Change directory to where you want to store the LLVM object
  • 270 files and run configure to configure the Makefiles and
    271 header files for the default platform.
    275272 Useful options include:
    276273
    277
  • --with-objroot=directory
  • 278
    279 Specify where object files should be placed during the
    280 build.
    281
    282274
  • --with-llvmgccdir=directory
  • 283275
    284 Specify where the LLVM C frontend is going to be installed.
    276 Specify where the LLVM GCC frontend is installed.
    285277
    286278
    287279
    300292
    301293

    See Setting Up Your Environment on tips to

    302294 simplify working with the LLVM front-end and compiled tools. See the
    303 other sub-sections below for other useful details in working with LLVM,
    295 next section for other useful details in working with LLVM,
    304296 or go straight to Program Layout to learn about the
    305 layout of the source code tree. For information on building the C front
    306 end yourself, see Compiling the LLVM C Front End for
    297 layout of the source code tree. For information on building the GCC front
    298 end yourself, see Compiling the LLVM GCC Front End for
    307299 information.
    300
    301
    302
    303

    Getting Started with LLVM

    304
    305
    306
    308307
    309308
    310309

    Terminology and Notation

    324323 give you this path.
    325324

    326325
    326
    SRC_ROOT
    327
    328 This is the top level directory of the LLVM source tree.
    329

    330
    327331
    OBJ_ROOT
    328332
    329 This is the top level directory for where the LLVM suite object files
    330 will be placed during the build.
    333 This is the top level directory of the LLVM object tree (i.e. the
    334 tree where object files and compiled programs will be placed. It
    335 can be the same as SRC_ROOT).
    331336

    332337
    333338
    LLVMGCCDIR
    334339
    335 This is the pathname to the location where the LLVM C Front End will
    336 be installed. Note that the C front end does not need to be installed
    337 during the LLVM suite build; you will just need to know where it will
    338 go for configuring the build system and running the test suite later.
    339

    340 For the pre-built C front end binaries, the LLVMGCCDIR is
    340 This is the where the LLVM GCC Front End is installed.
    341

    342 For the pre-built GCC front end binaries, the LLVMGCCDIR is the
    341343 cfrontend/platform/llvm-gcc.
    342344
    343345
    GCCSRC
    344346
    345 This is the pathname of the directory where the LLVM C front end source
    346 code can be found.
    347 This is the location of the LLVM GCC front end source code (used
    348 only if the LLVM GCC front end is being compiled).
    347349

    348350
    349351
    GCCOBJ
    350352
    351 This is the pathname of the directory where the LLVM C front end object
    352 code will be placed during the build. It can be safely removed once
    353 the build is complete.
    353 This is the location of the LLVM GCC front end object code (used
    354 only if the LLVM GCC front end is being compiled). It can be
    355 safely removed once the LLVM GCC front end is built and installed.
    354356
    355357
    356358
    366368
    367369
    LLVM_LIB_SEARCH_PATH=LLVMGCCDIR/llvm-gcc/bytecode-libs
    368370
    369 This environment variable helps the LLVM C front end find bytecode
    371 This environment variable helps the LLVM GCC front end find bytecode
    370372 libraries that it will need for compilation.
    371373

    372374
    373375
    alias llvmgcc LLVMGCCDIR/bin/llvm-gcc
    374
    375 This alias allows you to use the LLVM C front end without putting it in
    376 your PATH or typing in its complete pathname.
    376
    alias llvmg++ LLVMGCCDIR/bin/llvm-g++
    377
    378 This alias allows you to use the LLVM C and C++ front ends without putting
    379 them in your PATH or typing in their complete pathnames.
    377380
    378381
    379382
    393396

    394397
    395398
    cfrontend.sparc.tar.gz
    396
    This is the binary release of the C front end for Solaris/Sparc.
    399
    This is the binary release of the GCC front end for Solaris/Sparc.
    397400

    398401
    399402
    cfrontend.x86.tar.gz
    400
    This is the binary release of the C front end for Linux/x86.
    403
    This is the binary release of the GCC front end for Linux/x86.
    401404

    402405
    403406
    cfrontend-src.tar.gz
    404
    This is the source code release of the C front end.
    407
    This is the source code release of the GCC front end.
    405408

    406409
    407410
    422425 test directories, and local copies of documentation files.

    423426
    424427

    425 Note that the C front end is not included in the CVS repository. You
    428 Note that the GCC front end is not included in the CVS repository. You
    426429 should have either downloaded the source, or better yet, downloaded the
    427430 binary distribution for your platform.
    428431

    429432
    430433
    431

    Install the C Front End

    432
    433
    434

    435 Before configuring and compiling the LLVM suite, it is best to extract the
    436 LLVM C front end. While not used in building, the C front end is used by
    437 the LLVM test suite, and its location must be given to the
    438 configure script before the LLVM suite can be built.
    439

    440
    441

    442 To install the C front end, do the following:
    434

    Install the GCC Front End

    435
    436
    437

    438 Before configuring and compiling the LLVM suite, you need to extract the
    439 LLVM GCC front end from the binary distribution. It is used for building the
    440 bytecode libraries later used by the GCC front end for linking programs, and
    441 its location must be specified when the LLVM suite is configured.
    442

    443
    444

    445 To install the GCC front end, do the following:
    443446
    444447
  • cd where-you-want-the-front-end-to-live
  • 445448
  • gunzip --stdout cfrontend.platform.tar.gz | tar -xvf
  • 453456

    Once checked out from the CVS repository, the LLVM suite source code

    454457 must be configured via the configure script. This script sets
    455458 variables in llvm/Makefile.config and
    456 llvm/include/Config/config.h.
    459 llvm/include/Config/config.h. It also populates OBJ_ROOT with
    460 the Makefiles needed to build LLVM.
    457461
    458462

    459463 The following environment variables are used by the configure
    494498

    495499
    496500
    497
    --with-objroot=OBJ_ROOT
    498
    499 Path to the directory where
    500 object files, libraries, and executables should be placed.
    501 If this is set to ., then the object files will be placed
    502 within the source code tree. If left unspecified, the default value is
    503 the following:
    504
    505
  • 506 If the USER environment variable is specified and the directory
    507 /localhome/$USER exists, then the default value is
    508 /localhome/$USER.
    509
    510
  • 511 Otherwise, the default value is ..
    512
    513 (See the Section on
    514 The Location of LLVM Object Files
    515 for more information.)
    516

    517501
    --with-llvmgccdir=LLVMGCCDIR
    518502
    519503 Path to the location where the LLVM C front end binaries and
    521505

    522506
    --enable-optimized
    523507
    524 Enables optimized compilation (debugging symbols are removed and GCC
    525 optimization flags are enabled). The default is to use an unoptimized
    526 build (also known as a debug build).
    508 Enables optimized compilation by defaulat (debugging symbols are removed
    509 and GCC optimization flags are enabled). The default is to use an
    510 unoptimized build (also known as a debug build).
    527511

    528512
    --enable-jit
    529513
    530514 Compile the Just In Time (JIT) functionality. This is not available
    531515 on all platforms. The default is dependent on platform, so it is best
    532516 to explicitly enable it if you want it.
    533 >
    517 >
    518
    --enable-spec2000
    519
    --enable-spec2000=<directory>
    520
    521 Enable the use of SPEC2000 when testing LLVM. This is disabled by default
    522 (unless configure find SPEC2000 installed). By specifying
    523 directory, you can tell configure where to find the SPEC2000
    524 benchmarks. If directory is left unspecified, it
    525 configure uses a default value for our internal
    526 installation of SPEC2000.
    527
    528
    529

    530 To configure LLVM, follow these steps:
    531
    532
  • Change directory into the object root directory:
  • 533
    534 cd OBJ_ROOT
    535

    536
    537
  • Run the script located in the LLVM source tree:
  • 538
    539 SRC_ROOT/configure
    540

    541
    542

    534543
    535544 In addition to running configure, you must set the
    536545 LLVM_LIB_SEARCH_PATH environment variable in your startup scripts.
    537546 This environment variable is used to locate "system" libraries like
    538547 "-lc" and "-lm" when linking. This variable should be set
    539 to the absolute path for the bytecode-libs subdirectory of the C front-end
    548 to the absolute path for the bytecode-libs subdirectory of the GCC front end
    540549 install, or LLVMGCCDIR/llvm-gcc/bytecode-libs. For example, one might
    541550 set LLVM_LIB_SEARCH_PATH to
    542551 /home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs for the X86
    552561
    553562
    Debug Builds
    554563
    555 These builds are the default. They compile the tools and libraries
    556 with debugging information.
    564 These builds are the default when one types gmake (unless the
    565 --enable-optimized option was used during configuration). They
    566 compile the tools and libraries with debugging information.
    557567

    558568
    559569
    Release (Optimized) Builds
    560570
    561571 These builds are enabled with the --enable-optimized option to
    562 configure. They compile the tools and libraries with GCC
    572 configure or by specifying ENABLE_OPTIMIZED=1 on the
    573 gmake command line. They compile the tools and libraries with GCC
    563574 optimizer flags on and strip debugging information from the libraries
    564575 and executables it generates.
    565576

    568579
    569580 These builds are for use with profiling. They compile profiling
    570581 information into the code for use with programs like gprof.
    571 Profile builds must be started by setting variables on the
    572 gmake command line.
    573
    574
    575 Once you have LLVM configured, you can build it by entering the top level
    576 llvm directory and issuing the following command:
    582 Profile builds must be started by specifying ENABLE_PROFILING=1
    583 on the gmake command line.
    584
    585
    586 Once you have LLVM configured, you can build it by entering the OBJ_ROOT
    587 directory and issuing the following command:
    577588

    578589 gmake
    579590
    587598 gmake -j2
    588599
    589600

    590 There are several other targets which are useful when working with the LLVM
    601 There are several special targets which are useful when working with the LLVM
    591602 source code:
    592603
    593604
    603614 files generated by configure. It attempts to return the
    604615 source tree to the original state in which it was shipped.
    605616

    617
    618
    gmake install
    619
    620 Installs LLVM files into the proper location. For the most part,
    621 this does nothing, but it does install bytecode libraries into the
    622 GCC front end's bytecode library directory. If you need to update
    623 your bytecode libraries, this is the target to use once you've built
    624 them.
    625

    626
    606627
    607628
    608629 It is also possible to override default values from configure by
    625646

    626647
    627648
    628 Every directory in the LLVM source tree includes a Makefile to
    649 Every directory in the LLVM object tree includes a Makefile to
    629650 build it and any subdirectories that it contains. Entering any directory
    630 inside the LLVM source tree and typing gmake should rebuild
    651 inside the LLVM object tree and typing gmake should rebuild
    631652 anything in or below that directory that is out of date.
    632653
    633654
    634655

    The Location of LLVM Object Files

    635656
    636657
    637

    The LLVM build system sends most output files generated during the build

    638 into the directory defined by the variable OBJ_ROOT in
    639 llvm/Makefile.config, which is set by the --with-objroot
    640 option in configure. This can be either just your normal LLVM
    641 source tree or some other directory writable by you. You may wish to put
    642 object files on a different filesystem either to keep them from being backed
    643 up or to speed up local builds.
    644
    645

    646 If OBJ_ROOT is specified, then the build system will create a
    647 directory tree underneath it that resembles the source code's pathname
    648 relative to your home directory (unless OBJ_ROOT is set to
    649 ., in which case object files are placed within the LLVM source
    650 tree).
    651

    652
    653

    654 Note that
    655 --with-objroot=.
    656 and
    657 --with-objroot=`pwd`
    658 are not the same thing. The former will simply place object files within
    659 the source tree, while the latter will set the location of object files
    660 using the source tree's relative path from the home directory.
    661

    662
    663

    664 For example, suppose that OBJ_ROOT is set to /tmp and the
    665 LLVM suite source code is located in /usr/home/joe/src/llvm, where
    666 /usr/home/joe is the home directory of a user named Joe. Then,
    667 the object files will be placed in /tmp/src/llvm.
    668 </p>
    658 <p>
    659 The LLVM build system is capable of sharing a single LLVM source tree among
    660 several LLVM builds. Hence, it is possible to build LLVM for several
    661 different platforms or configurations using the same source tree.
    662

    663 This is accomplished in the typical autoconf manner:
    664
    665
  • Change directory to where the LLVM object files should live:
  • 666

    667 cd OBJ_ROOT
    668
    669
  • Run the configure script found in the LLVM source directory:
  • 670

    671 SRC_ROOT/configure
    672
    669673
    670674

    671675 The LLVM build will place files underneath OBJ_ROOT in directories
    677681
    678682
    679683
    Tools
    680
    OBJ_ROOT/llvm/tools/Debug
    684
    OBJ_ROOT/tools/Debug
    681685
    Libraries
    682
    OBJ_ROOT/llvm/lib/Debug
    686
    OBJ_ROOT/lib/Debug
    683687
    684688

    685689
    687691
    688692
    689693
    Tools
    690
    OBJ_ROOT/llvm/tools/Release
    694
    OBJ_ROOT/tools/Release
    691695
    Libraries
    692
    OBJ_ROOT/llvm/lib/Release
    696
    OBJ_ROOT/lib/Release
    693697
    694698

    695699
    697701
    698702
    699703
    Tools
    700
    OBJ_ROOT/llvm/tools/Profile
    704
    OBJ_ROOT/tools/Profile
    701705
    Libraries
    702
    OBJ_ROOT/llvm/lib/Profile
    706
    OBJ_ROOT/lib/Profile
    703707
    704708
    705709
    707711
    708712

    Program Layout

    709713
    710
    711
    712 <p>One useful source of information about the LLVM source base is the LLVM
    714 <hr>
    715
    716
    717

    718 One useful source of information about the LLVM source base is the LLVM
    713719 href="http://www.doxygen.org">doxygen documentation, available at
    714 href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/. The
    715 following is a brief introduction to code layout:

    716
    720 href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/.
    721 The following is a brief introduction to code layout:
    722

    717723
    718724
    719725

    CVS directories

    734740
  • llvm/include/llvm - This directory contains all of the LLVM
  • 735741 specific header files. This directory also has subdirectories for
    736742 different portions of LLVM: Analysis, CodeGen,
    737 Reoptimizer, Target, Transforms, etc...
    743 Target, Transforms, etc...
    738744
    739745
  • llvm/include/Support - This directory contains generic
  • 740746 support libraries that are independent of LLVM, but are used by LLVM.
    789795 of the code generator: Instruction Selector, Instruction Scheduling, and
    790796 Register Allocation.
    791797
    792
    llvm/lib/Reoptimizer/
    This directory holds code related
    793 to the runtime reoptimizer framework that is currently under development.
    794
    795798
    llvm/lib/Support/
    This directory contains the source code
    796799 that corresponds to the header files located in
    797800 llvm/include/Support/.
    798801
    799802
    800803
    804

    llvm/runtime

    805
    806
    807

    808 This directory contains libraries which are compiled into LLVM bytecode and
    809 used when linking programs with the GCC front end. Most of these libraries
    810 are skeleton versions of real libraries; for example, libc is a stripped down
    811 version of glibc.
    812

    813
    814

    815 Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end
    816 to compile.
    817

    818
    819
    801820

    llvm/test

    802821
    803822
    804823

    This directory contains regression tests and source code that is used to

    805 test the LLVM infrastructure...

    824 test the LLVM infrastructure.
    825

    806826
    807827
    808828

    llvm/tools

    959979
    960980
    961981
    962

    Compiling the LLVM C Front End

    982

    Compiling the LLVM GCC Front End

    983
    963984
    964985
    965986

    966987
    967 This step is optional if you have the C front end binary distribution for
    988 This step is optional if you have the GCC front end binary distribution for
    968989 your platform.
    969990
    970991

    971992
    972 Now that you have the LLVM suite built, you can build the C front end. For
    993 Now that you have the LLVM suite built, you can build the GCC front end. For
    973994 those of you that have built GCC before, the process is very similar.
    974995

    975 Be forewarned, though: the build system for the C front end is not as
    996 Be forewarned, though: the build system for the GCC front end is not as
    976997 polished as the rest of the LLVM code, so there will be many warnings and
    977998 errors that you will need to ignore for now:
    978999
    10171038

    10181039
    An Example Using the LLVM Tool Chain
    10191040
    1041
    10201042
    10211043
    10221044
    10731095

    10741096
    Common Problems
    10751097
    1098
    10761099
    10771100
    10781101 Below are common problems and their remedies:
    11381161
    11391162
    11401163

    Links

    1164
    11411165
    11421166
    11431167

    This document is just an introduction to how to use LLVM to do