Once checked out from the CVS repository, the LLVM suite source code must be +configured via the configure script. This script sets variables in +llvm/Makefile.config and llvm/include/Config/config.h. It +also populates OBJ_ROOT with the Makefiles needed to begin building +LLVM.
+ +The following environment variables are used by the configure +script to configure the build system:
+ +| Variable | +Purpose | +
|---|---|
| CC | +Tells configure which C compiler to use. By default, + configure will look for the first GCC C compiler in + PATH. Use this variable to override + configure's default behavior. | +
| CXX | +Tells configure which C++ compiler to use. By default, + configure will look for the first GCC C++ compiler in + PATH. Use this variable to override + configure's default behavior. | +
The following options can be used to set or enable LLVM specific options:
+ +-
+
- --with-llvmgccdir=LLVMGCCDIR +
-
+ Path to the location where the LLVM GCC front end binaries and
+ associated libraries were installed. This must be specified as an
+ absolute pathname.
- If you have multiple processors in your machine, you may wish to use some - of the parallel build options provided by GNU Make. For example, you could - use the command: -
- + - --enable-optimized +
-
+ Enables optimized compilation by default (debugging symbols are removed
+ and GCC optimization flags are enabled). The default is to use an
+ unoptimized build (also known as a debug build).
- gmake -j2 - +
- --enable-jit +
-
+ Compile the Just In Time (JIT) compiler functionality. This is not
+ available
+ on all platforms. The default is dependent on platform, so it is best
+ to explicitly enable it if you want it.
- There are several other targets which are useful when working with the LLVM - source code: - -
-
-
- gmake clean -
-
- Removes all files generated by the build. This includes object files,
- generated C/C++ files, libraries, and executables.
-
- -
- gmake distclean -
-
- Removes everything that gmake clean does, but also removes
- files generated by configure. It attempts to return the
- source tree to the original state in which it was shipped.
-
-
-
-
- gmake ENABLE_OPTIMIZED=1 -
-
- Perform a Release (Optimized) build.
-
- -
- gmake ENABLE_PROFILING=1 -
-
- Perform a Profiling build.
-
- -
- gmake VERBOSE=1 -
-
- Print what gmake is doing on standard output.
-
-
The Location of LLVM Object Files
- - -The LLVM build system sends most output files generated during the build - into the directory defined by the variable OBJ_ROOT in - llvm/Makefile.config, which is set by the --with-objroot - option in configure. This can be either just your normal LLVM - source tree or some other directory writable by you. You may wish to put - object files on a different filesystem either to keep them from being backed - up or to speed up local builds. - +
- --enable-spec2000
+
- --enable-spec2000=<directory> +
-
+ Enable the use of SPEC2000 when testing LLVM. This is disabled by default
+ (unless configure finds SPEC2000 installed). By specifying
+ directory, you can tell configure where to find the SPEC2000
+ benchmarks. If directory is left unspecified, configure
+ uses the default value
+ /home/vadve/shared/benchmarks/speccpu2000/benchspec.
- If OBJ_ROOT is specified, then the build system will create a - directory tree underneath it that resembles the source code's pathname - relative to your home directory (unless OBJ_ROOT is set to - ., in which case object files are placed within the LLVM source - tree). -
- + - --enable-spec95
+
- --enable-spec95=<directory> +
-
+ Enable the use of SPEC95 when testing LLVM. It is similar to the
+ --enable-spec2000 option.
- Note that - --with-objroot=. - and - --with-objroot=`pwd` - are not the same thing. The former will simply place object files within - the source tree, while the latter will set the location of object files - using the source tree's relative path from the home directory. -
- + - --enable-povray
+
- --enable-povray=<directory> +
- + Enable the use of Povray as an external test. Versions of Povray written + in C should work. This option is similar to the --enable-spec2000 + option. +
To configure LLVM, follow these steps:
+ +-
+
- Change directory into the object root directory:
+
+ cd OBJ_ROOT- For example, suppose that OBJ_ROOT is set to /tmp and the - LLVM suite source code is located in /usr/home/joe/src/llvm, where - /usr/home/joe is the home directory of a user named Joe. Then, - the object files will be placed in /tmp/src/llvm. -
+ - Run the configure script located in the LLVM source tree:
+
+ SRC_ROOT/configure- The LLVM build will place files underneath OBJ_ROOT in directories - named after the build type: -
- --
-
- Debug Builds -
-
-
-
-
- Tools -
- OBJ_ROOT/llvm/tools/Debug -
- Libraries -
- OBJ_ROOT/llvm/lib/Debug -
- -
- Release Builds -
-
-
-
-
- Tools -
- OBJ_ROOT/llvm/tools/Release -
- Libraries -
- OBJ_ROOT/llvm/lib/Release -
- -
- Profile Builds -
-
-
-
-
- Tools -
- OBJ_ROOT/llvm/tools/Profile -
- Libraries -
- OBJ_ROOT/llvm/lib/Profile -
- - - -Program Layout
-One useful source of information about the LLVM source base is the LLVM doxygen documentation, available at http://llvm.cs.uiuc.edu/doxygen/. The - following is a brief introduction to code layout:
- - - -CVS directories
- - - Every directory checked out of CVS will contain a CVS directory; - for the most part these can just be ignored. - - - -llvm/include
- - - This directory contains public header files exported from the LLVM - library. The three main subdirectories of this directory are:+
-
-
- llvm/include/llvm - This directory contains all of the LLVM - specific header files. This directory also has subdirectories for - different portions of LLVM: Analysis, CodeGen, - Reoptimizer, Target, Transforms, etc... - -
- llvm/include/Support - This directory contains generic - support libraries that are independent of LLVM, but are used by LLVM. - For example, some C++ STL utilities and a Command Line option processing - library. - -
- llvm/include/Config - This directory contains header files - configured by the configure script. They wrap "standard" UNIX - and C header files. Source code can include these header files which - automatically take care of the conditional #includes that the configure - script generates. -
llvm/lib
- - - This directory contains most of the source files of the LLVM system. In - LLVM almost all - code exists in libraries, making it very easy to share code among the - different tools.- -
-
-
- llvm/lib/VMCore/
- This directory holds the core LLVM - source files that implement core classes like Instruction and BasicBlock. - -
- llvm/lib/AsmParser/
- This directory holds the source code - for the LLVM assembly language parser library. - -
- llvm/lib/ByteCode/
- This directory holds code for reading - and write LLVM bytecode. - -
- llvm/lib/CWriter/
- This directory implements the LLVM to C - converter. - -
- llvm/lib/Analysis/
- This directory contains a variety of - different program analyses, such as Dominator Information, Call Graphs, - Induction Variables, Interval Identification, Natural Loop Identification, - etc... - -
- llvm/lib/Transforms/
- This directory contains the source - code for the LLVM to LLVM program transformations, such as Aggressive Dead - Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop - Invarient Code Motion, Dead Global Elimination, and many others... - -
- llvm/lib/Target/
- This directory contains files that
- describe various target architectures for code generation. For example,
- the llvm/lib/Target/Sparc directory holds the Sparc machine
- description.
- - - llvm/lib/CodeGen/
- This directory contains the major parts - of the code generator: Instruction Selector, Instruction Scheduling, and - Register Allocation. - -
- llvm/lib/Reoptimizer/
- This directory holds code related - to the runtime reoptimizer framework that is currently under development. - -
- llvm/lib/Support/
- This directory contains the source code - that corresponds to the header files located in - llvm/include/Support/. -
llvm/test
- - -This directory contains regression tests and source code that is used to - test the LLVM infrastructure...
- - -llvm/tools
- - -The tools directory contains the executables built out of the - libraries above, which form the main part of the user interface. You can - always get help for a tool by typing tool_name --help. The - following is a brief introduction to the most important tools.
- --
-
- as
- The assembler transforms the human readable
- LLVM assembly to LLVM bytecode.
- -
- dis
- The disassembler transforms the LLVM bytecode
- to human readable LLVM assembly. Additionally it can convert LLVM
- bytecode to C, which is enabled with the -c option.
- -
- lli
- lli is the LLVM interpreter, which
- can directly execute LLVM bytecode (although very slowly...). In addition
- to a simple interpreter, lli is also has debugger and tracing
- modes (entered by specifying -debug or -trace on the
- command line, respectively). Finally, for architectures that support it
- (currently only x86 and Sparc), by default, lli will function as
- a Just-In-Time compiler (if the functionality was compiled in), and will
- execute the code much faster than the interpreter.
- -
- llc
- llc is the LLVM backend compiler,
- which translates LLVM bytecode to a SPARC or x86 assembly file.
- -
- llvmgcc
- llvmgcc is a GCC based C frontend
- that has been retargeted to emit LLVM code as the machine code output. It
- works just like any other GCC compiler, taking the typical -c, -S, -E,
- -o options that are typically used. The source code for the
- llvmgcc tool is currently not included in the LLVM cvs tree
- because it is quite large and not very interesting.
- -
-
-
- gccas
- This tool is invoked by the
- llvmgcc frontend as the "assembler" part of the compiler. This
- tool actually assembles LLVM assembly to LLVM bytecode,
- performs a variety of optimizations,
- and outputs LLVM bytecode. Thus when you invoke llvmgcc -c x.c -o
- x.o, you are causing gccas to be run, which writes the
- x.o file (which is an LLVM bytecode file that can be
- disassembled or manipulated just like any other bytecode file). The
- command line interface to gccas is designed to be as close as
- possible to the system 'as' utility so that the gcc
- frontend itself did not have to be modified to interface to a "weird"
- assembler.
- -
- gccld
- gccld links together several LLVM
- bytecode files into one bytecode file and does some optimization. It is
- the linker invoked by the gcc frontend when multiple .o files need to be
- linked together. Like gccas the command line interface of
- gccld is designed to match the system linker, to aid
- interfacing with the GCC frontend.
-
- opt
- opt reads LLVM bytecode, applies a
- series of LLVM to LLVM transformations (which are specified on the command
- line), and then outputs the resultant bytecode. The 'opt --help'
- command is a good way to get a list of the program transformations
- available in LLVM.
+
In addition to running configure, you must set the +LLVM_LIB_SEARCH_PATH environment variable in your startup scripts. +This environment variable is used to locate "system" libraries like +"-lc" and "-lm" when linking. This variable should be set to +the absolute path of the bytecode-libs subdirectory of the GCC front +end, or LLVMGCCDIR/bytecode-libs. For example, one might set +LLVM_LIB_SEARCH_PATH to +/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs for the x86 +version of the GCC front end on our research machines.
- - - analyze
- analyze is used to run a specific
- analysis on an input LLVM bytecode file and print out the results. It is
- primarily useful for debugging analyses, or familiarizing yourself with
- what an analysis does.
- -
llvm/utils
- - - This directory contains utilities for working with LLVM sourcecode, and some - of the utilities are actually required as part of the build process because - they are code generators for parts of LLVM infrastructure. - --
-
- Burg is an instruction selector
- generator -- it builds trees on which it then performs pattern-matching to
- select instructions according to the patterns the user has specified. Burg
- is currently used in the Sparc V9 backend.
- -
- codegen-diff
- codegen-diff is a script
- that finds differences between code that LLC generates and code that LLI
- generates. This is a useful tool if you are debugging one of them,
- assuming that the other generates correct output. For the full user
- manual, run `perldoc codegen-diff'.
- -
- cvsupdate
- cvsupdate is a script that will
- update your CVS tree, but produce a much cleaner and more organized output
- than simply running `cvs up -dP' will. For example, it will group
- together all the new and updated files and modified files in separate
- sections, so you can see at a glance what has changed. If you are at the
- top of your LLVM CVS tree, running utils/cvsupdate is the
- preferred way of updating the tree.
- -
- emacs
- The emacs directory contains
- syntax-highlighting files which will work with Emacs and XEmacs editors,
- providing syntax highlighting support for LLVM assembly files and TableGen
- description files.
- -
- getsrcs.sh
- The getsrcs.sh script finds
- and outputs all non-generated source files, which is useful if one wishes
- to do a lot of development across directories and does not want to
- individually find each file. One way to use it is to run, for example:
- xemacs `utils/getsources.sh` from the top of your LLVM source
- tree.
- -
- makellvm
- The makellvm script compiles all
- files in the current directory and then compiles and links the tool that
- is the first argument. For example, assuming you are in the directory
- llvm/lib/Target/Sparc, if makellvm is in your path,
- simply running makellvm llc will make a build of the current
- directory, switch to directory llvm/tools/llc and build it,
- causing a re-linking of LLC.
- -
- NightlyTest.pl and - NightlyTestTemplate.html
- These files are used in a
- cron script to generate nightly status reports of the functionality of
- tools, and the results can be seen by following the appropriate link on
- the LLVM homepage.
- -
- TableGen
- The TableGen directory contains
- the tool used to generate register descriptions, instruction set
- descriptions, and even assemblers from common TableGen description
- files.
- -
- vim
- The vim directory contains
- syntax-highlighting files which will work with the VIM editor, providing
- syntax highlighting support for LLVM assembly files and TableGen
- description files.
- - + - -
- + + +Compiling the LLVM C Front End + ++ + + + +Once you have configured LLVM, you can build it. There are three types of +builds:
+ +-
+
- Debug Builds +
-
+ These builds are the default when one types gmake (unless the
+ --enable-optimized option was used during configuration). The
+ build system will compile the tools and libraries with debugging
+ information.
- - This step is optional if you have the C front end binary distribution for - your platform. - -
- - Now that you have the LLVM suite built, you can build the C front end. For - those of you that have built GCC before, the process is very similar. -- Be forewarned, though: the build system for the C front end is not as - polished as the rest of the LLVM code, so there will be many warnings and - errors that you will need to ignore for now: -
-
-
- Ensure that OBJ_ROOT/llvm/tools/Debug is at the
- end of your PATH environment variable. The front end
- build needs to know where to find the LLVM tools, but you want to
- ensure that these tools are not found before the system assembler and
- linker that you normally use for compilation.
+
- Release (Optimized) Builds +
- + These builds are enabled with the --enable-optimized option to + configure or by specifying ENABLE_OPTIMIZED=1 on the + gmake command line. For these builds, the build system will + compile the tools and libraries with GCC optimizations enabled and strip + debugging information from the libraries and executables it generates. +
-
- cd GCCOBJ +
- Profile Builds +
- + These builds are for use with profiling. They compile profiling + information into the code for use with programs like gprof. + Profile builds must be started by specifying ENABLE_PROFILING=1 + on the gmake command line. +
- Ensure that OBJ_ROOT/llvm/tools/Debug is at the
- end of your PATH environment variable. The front end
- build needs to know where to find the LLVM tools, but you want to
- ensure that these tools are not found before the system assembler and
- linker that you normally use for compilation.
+
Once you have LLVM configured, you can build it by entering the +OBJ_ROOT directory and issuing the following command:
+ +gmake
+ +If you have multiple processors in your machine, you may wish to use some of +the parallel build options provided by GNU Make. For example, you could use the +command:
+ +gmake -j2
+ +There are several special targets which are useful when working with the LLVM +source code:
+ +-
+
- gmake clean +
-
+ Removes all files generated by the build. This includes object files,
+ generated C/C++ files, libraries, and executables.
+
+ +
- gmake distclean +
-
+ Removes everything that gmake clean does, but also removes
+ files generated by configure. It attempts to return the
+ source tree to the original state in which it was shipped.
+
+ +
- gmake install +
-
+ Installs LLVM files into the proper location. For the most part,
+ this does nothing, but it does install bytecode libraries into the
+ GCC front end's bytecode library directory. If you need to update
+ your bytecode libraries, this is the target to use once you've built
+ them.
+
+
It is also possible to override default values from configure by +declaring variables on the command line. The following are some examples:
+ +-
+
- gmake ENABLE_OPTIMIZED=1 +
-
+ Perform a Release (Optimized) build.
+
+ +
- gmake ENABLE_PROFILING=1 +
-
+ Perform a Profiling build.
+
+ +
- gmake VERBOSE=1 +
-
+ Print what gmake is doing on standard output.
+
+
Every directory in the LLVM object tree includes a Makefile to build +it and any subdirectories that it contains. Entering any directory inside the +LLVM object tree and typing gmake should rebuild anything in or below +that directory that is out of date.
+ ++ ++ + + + +The LLVM build system is capable of sharing a single LLVM source tree among +several LLVM builds. Hence, it is possible to build LLVM for several different +platforms or configurations using the same source tree.
+ +This is accomplished in the typical autoconf manner:
+ +-
+
Change directory to where the LLVM object files should live:
+ +cd OBJ_ROOT
+
+ Run the configure script found in the LLVM source + directory:
+ +SRC_ROOT/configure
+
The LLVM build will place files underneath OBJ_ROOT in directories +named after the build type:
+ +-
+
- Debug Builds +
-
+
-
+
- Tools +
- OBJ_ROOT/tools/Debug +
- Libraries +
- OBJ_ROOT/lib/Debug +
+ +
- Release Builds +
-
+
-
+
- Tools +
- OBJ_ROOT/tools/Release +
- Libraries +
- OBJ_ROOT/lib/Release +
+ +
- Profile Builds +
-
+
-
+
- Tools +
- OBJ_ROOT/tools/Profile +
- Libraries +
- OBJ_ROOT/lib/Profile +
+ ++ + + ++If you're running on a linux system that supports the "binfmt_misc" +module, and you have root access on the system, you can set your system up to +execute LLVM bytecode files directly. To do this, use commands like this (the +first command may not be required if you are already using the module):
+ ++ $ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc + $ echo ':llvm:M::llvm::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register + $ chmod u+x hello.bc (if needed) + $ ./hello.bc +
+ ++This allows you to execute LLVM bytecode files directly. Thanks to Jack +Cummings for pointing this out! +
+ ++ Program Layout ++ + ++ ++ + +One useful source of information about the LLVM source base is the LLVM doxygen documentation available at http://llvm.cs.uiuc.edu/doxygen/. +The following is a brief introduction to code layout:
+ ++ CVS directories ++ ++ ++ + +Every directory checked out of CVS will contain a CVS directory; for +the most part these can just be ignored.
+ ++ llvm/include ++ ++ +-This directory contains public header files exported from the LLVM +library. The three main subdirectories of this directory are:
+ +-
+
- llvm/include/llvm - This directory contains all of the LLVM + specific header files. This directory also has subdirectories for + different portions of LLVM: Analysis, CodeGen, + Target, Transforms, etc... + +
- llvm/include/Support - This directory contains generic + support libraries that are independent of LLVM, but are used by LLVM. + For example, some C++ STL utilities and a Command Line option processing + library store their header files here. -
- Configure the source code:
-
-
-
- On Linux/x86, use
-
-
-
- GCCSRC/configure --prefix=LLVMGCCDIR - --enable-languages=c -
- llvm/include/Config - This directory contains header files + configured by the configure script. They wrap "standard" UNIX + and C header files. Source code can include these header files which + automatically take care of the conditional #includes that the + configure script generates. +
- On Linux/x86, use
-
- On Solaris/Sparc, use -
-
-
- GCCSRC/configure --prefix=LLVMGCCDIR - --enable-languages=c --target=sparcv9-sun-solaris2 -
- gmake + +
+ llvm/lib +-- The build will eventually fail. Don't worry; chances are good that - everything that needed to build is built. +
-+ + +- gmake -k install - +
This directory contains most of the source files of the LLVM system. In LLVM, +almost all code exists in libraries, making it very easy to share code among the +different tools.
-- Once this is done, you should have a built front end compiler in - LLVMGCCDIR. -
+-
+
- llvm/lib/VMCore/
- This directory holds the core LLVM
+ source files that implement core classes like Instruction and BasicBlock.
-
-
-
- +An Example Using the LLVM Tool Chain - - llvm/lib/AsmParser/
- This directory holds the source code
+ for the LLVM assembly language parser library.
-
-
-
- First, create a simple C file, name it 'hello.c':
+
- llvm/lib/ByteCode/
- This directory holds code for reading + and write LLVM bytecode. + +
- llvm/lib/CWriter/
- This directory implements the LLVM to C + converter. + +
- llvm/lib/Analysis/
- This directory contains a variety of + different program analyses, such as Dominator Information, Call Graphs, + Induction Variables, Interval Identification, Natural Loop Identification, + etc... + +
- llvm/lib/Transforms/
- This directory contains the source + code for the LLVM to LLVM program transformations, such as Aggressive Dead + Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop + Invariant Code Motion, Dead Global Elimination, and many others... + +
- llvm/lib/Target/
- This directory contains files that + describe various target architectures for code generation. For example, + the llvm/lib/Target/SparcV9 directory holds the Sparc machine + description.
+ +- llvm/lib/CodeGen/
- This directory contains the major parts + of the code generator: Instruction Selector, Instruction Scheduling, and + Register Allocation. + +
- llvm/lib/Support/
- This directory contains the source code + that corresponds to the header files located in + llvm/include/Support/. +
- First, create a simple C file, name it 'hello.c':
+
+ llvm/runtime ++ ++ ++ + +This directory contains libraries which are compiled into LLVM bytecode and +used when linking programs with the GCC front end. Most of these libraries are +skeleton versions of real libraries; for example, libc is a stripped down +version of glibc.
+ +Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front +end to compile.
+ ++ llvm/test ++ ++ ++ + +This directory contains regression tests and source code that is used to test +the LLVM infrastructure.
+ ++ llvm/tools ++ ++ ++ + +The tools directory contains the executables built out of the +libraries above, which form the main part of the user interface. You can +always get help for a tool by typing tool_name --help. The +following is a brief introduction to the most important tools:
+ +-
+
- analyze
- analyze is used to run a specific
+ analysis on an input LLVM bytecode file and print out the results. It is
+ primarily useful for debugging analyses, or familiarizing yourself with
+ what an analysis does.
+ +
- bugpoint
- bugpoint is used to debug
+ optimization passes or code generation backends by narrowing down the
+ given test case to the minimum number of passes and/or instructions that
+ still cause a problem, whether it is a crash or miscompilation. See HowToSubmitABug.html for more information
+ on using bugpoint.
+ +
- llvm-ar
- The archiver produces an archive containing
+ the given LLVM bytecode files, optionally with an index for faster
+ lookup.
+ +
- llvm-as
- The assembler transforms the human readable
+ LLVM assembly to LLVM bytecode.
+ +
- llvm-dis
- The disassembler transforms the LLVM
+ bytecode to human readable LLVM assembly.
+ +
- llvm-link
- llvm-link, not surprisingly,
+ links multiple LLVM modules into a single program.
+ +
- lli
- lli is the LLVM interpreter, which
+ can directly execute LLVM bytecode (although very slowly...). In addition
+ to a simple interpreter, lli also has a tracing mode (entered by
+ specifying -trace on the command line). Finally, for
+ architectures that support it (currently only x86 and Sparc), by default,
+ lli will function as a Just-In-Time compiler (if the
+ functionality was compiled in), and will execute the code much
+ faster than the interpreter.
+ +
- llc
- llc is the LLVM backend compiler, which
+ translates LLVM bytecode to a SPARC or x86 assembly file, or to C code (with
+ the -march=c option).
+ +
- llvmgcc
- llvmgcc is a GCC-based C frontend
+ that has been retargeted to emit LLVM code as the machine code output. It
+ works just like any other GCC compiler, taking the typical -c, -S, -E,
+ -o options that are typically used. The source code for the
+ llvmgcc tool is currently not included in the LLVM CVS tree
+ because it is quite large and not very interesting.
+ +
+
+ +-
+
- gccas
- This tool is invoked by the
+ llvmgcc frontend as the "assembler" part of the compiler. This
+ tool actually assembles LLVM assembly to LLVM bytecode,
+ performs a variety of optimizations, and outputs LLVM bytecode. Thus
+ when you invoke llvmgcc -c x.c -o x.o, you are causing
+ gccas to be run, which writes the x.o file (which is
+ an LLVM bytecode file that can be disassembled or manipulated just like
+ any other bytecode file). The command line interface to gccas
+ is designed to be as close as possible to the system
+ `as' utility so that the gcc frontend itself did not have to be
+ modified to interface to a "weird" assembler.
+ +
- gccld
- gccld links together several LLVM + bytecode files into one bytecode file and does some optimization. It is + the linker invoked by the GCC frontend when multiple .o files need to be + linked together. Like gccas, the command line interface of + gccld is designed to match the system linker, to aid + interfacing with the GCC frontend.
+
- opt
- opt reads LLVM bytecode, applies a + series of LLVM to LLVM transformations (which are specified on the command + line), and then outputs the resultant bytecode. The 'opt --help' + command is a good way to get a list of the program transformations + available in LLVM. + +
+ llvm/utils ++ ++ ++ + + + + +This directory contains utilities for working with LLVM source code, and some +of the utilities are actually required as part of the build process because they +are code generators for parts of LLVM infrastructure.
+ +-
+
- Burg/
- Burg is an instruction selector
+ generator -- it builds trees on which it then performs pattern-matching to
+ select instructions according to the patterns the user has specified. Burg
+ is currently used in the Sparc V9 backend.
+ +
- codegen-diff
- codegen-diff is a script
+ that finds differences between code that LLC generates and code that LLI
+ generates. This is a useful tool if you are debugging one of them,
+ assuming that the other generates correct output. For the full user
+ manual, run `perldoc codegen-diff'.
+ +
- cvsupdate
- cvsupdate is a script that will
+ update your CVS tree, but produce a much cleaner and more organized output
+ than simply running `cvs -z3 up -dP' will. For example, it will group
+ together all the new and updated files and modified files in separate
+ sections, so you can see at a glance what has changed. If you are at the
+ top of your LLVM CVS tree, running utils/cvsupdate is the
+ preferred way of updating the tree.
+ +
- emacs/
- The emacs directory contains
+ syntax-highlighting files which will work with Emacs and XEmacs editors,
+ providing syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the README file in that directory.
+ +
- getsrcs.sh
- The getsrcs.sh script finds
+ and outputs all non-generated source files, which is useful if one wishes
+ to do a lot of development across directories and does not want to
+ individually find each file. One way to use it is to run, for example:
+ xemacs `utils/getsources.sh` from the top of your LLVM source
+ tree.
+ +
- makellvm
- The makellvm script compiles all
+ files in the current directory and then compiles and links the tool that
+ is the first argument. For example, assuming you are in the directory
+ llvm/lib/Target/Sparc, if makellvm is in your path,
+ simply running makellvm llc will make a build of the current
+ directory, switch to directory llvm/tools/llc and build it,
+ causing a re-linking of LLC.
+ +
- NightlyTest.pl and + NightlyTestTemplate.html
- These files are used in a
+ cron script to generate nightly status reports of the functionality of
+ tools, and the results can be seen by following the appropriate link on
+ the LLVM homepage.
+ +
- TableGen/
- The TableGen directory contains
+ the tool used to generate register descriptions, instruction set
+ descriptions, and even assemblers from common TableGen description
+ files.
+ +
- vim/
- The vim directory contains
+ syntax-highlighting files which will work with the VIM editor, providing
+ syntax highlighting support for LLVM assembly files and TableGen
+ description files. For information on how to use the syntax files, consult
+ the README file in that directory.
+ +
+ ++ + +-
+
- First, create a simple C file, name it 'hello.c':
#include <stdio.h> int main() { printf("hello world\n"); return 0; } -- - - Next, compile the C file into a LLVM bytecode file:
+
- % llvmgcc hello.c -o hello Next, compile the C file into a LLVM bytecode file:
+% llvmgcc hello.c -o hello
- This will create two result files: hello and +This will create two result files: hello and hello.bc. The hello.bc is the LLVM bytecode that corresponds the the compiled program and the library facilities that it required. hello is a simple shell script that runs the bytecode - file with lli, making the result directly executable.
+ file with lli, making the result directly executable. Note that + all LLVM optimizations are enabled by default, so there is no need for a + "-O3" switch.
- - Run the program. To make sure the program ran, execute one of the
- following commands:
+
Run the program. To make sure the program ran, execute one of the + following commands:
- % ./hello+
% ./hello
- or- - % lli hello.bc
- -
- Use the dis utility to take a look at the LLVM assembly
- code:
- - % dis < hello.bc | less
- -
- Compile the program to native Sparc assembly using the code
- generator (assuming you are currently on a Sparc system):
- - % llc hello.bc -o hello.s
- -
- Assemble the native sparc assemble file into a program:
- - % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc
- -
- Execute the native sparc program:
- - % ./hello.sparc
- -
+
-
- - - Below are common problems and their remedies: - -Common Problems --
-
- When I run configure, it finds the wrong C compiler. -
-
- The configure script attempts to locate first gcc and
- then cc, unless it finds compiler paths set in CC and
- CXX for the C and C++ compiler, respectively.
-
- If configure finds the wrong compiler, either adjust your
- PATH environment variable or set CC and CXX
- explicitly.
-
- -
- I compile the code, and I get some error about /localhome. -
-
- There are several possible causes for this. The first is that you
- didn't set a pathname properly when using configure, and it
- defaulted to a pathname that we use on our research machines.
-
- Another possibility is that we hardcoded a path in our Makefiles. If - you see this, please email the LLVM bug mailing list with the name of - the offending Makefile and a description of what is wrong with it. - -
- The configure script finds the right C compiler, but it - uses the LLVM linker from a previous build. What do I do? -
-
- The configure script uses the PATH to find
- executables, so if it's grabbing the wrong linker/assembler/etc, there
- are two ways to fix it:
-
-
-
- Adjust your PATH environment variable so that the
- correct program appears first in the PATH. This may work,
- but may not be convenient when you want them first in your
- path for other work.
-
- -
- Run configure with an alternative PATH that
- is correct. In a Borne compatible shell, the syntax would be:
-
- PATH=
./configure ... -- This is still somewhat inconvenient, but it allows - configure to do its work without having to adjust your - PATH permanently. -
- Adjust your PATH environment variable so that the
- correct program appears first in the PATH. This may work,
- but may not be convenient when you want them first in your
- path for other work.
-
- I've upgraded to a new version of LLVM, and I get strange build - errors. -
-
- Sometimes changes to the LLVM source code alters how the build system
- works. Changes in libtool, autoconf, or header file dependencies are
- especially prone to this sort of problem.
-
- The best thing to try is to remove the old files and re-build. In most - cases, this takes care of the problem. To do this, just type make - clean and then make in the directory that fails to build. -
- -
- - -Links This document is just an introduction to how to use LLVM to do - some simple things... there are many more interesting and complicated things - that you can do that aren't documented here (but we'll gladly accept a patch - if you want to write something up!). For more information about LLVM, check - out:
+or
- - -
- - If you have any questions or run into any snags (or you have any - additions...), please send an email to - Chris Lattner. - - - -Last modified: Mon Aug 11 13:52:22 CDT 2003 - - +% lli hello.bc
+ +Use the llvm-dis utility to take a look at the LLVM assembly + code:
+ +% llvm-dis < hello.bc | less
Compile the program to native Sparc assembly using the code + generator (assuming you are currently on a Sparc system):
+ +% llc hello.bc -o hello.s
+ +Assemble the native sparc assemble file into a program:
+ +% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc
+ +Execute the native sparc program:
+ +% ./hello.sparc
+ Common Problems ++ + ++ ++ + +If you are having problems building or using LLVM, or if you have any other +general questions about LLVM, please consult the Frequently +Asked Questions page.
+ ++ Links ++ + ++ ++ + + +This document is just an introduction to how to use LLVM to do +some simple things... there are many more interesting and complicated things +that you can do that aren't documented here (but we'll gladly accept a patch +if you want to write something up!). For more information about LLVM, check +out:
+ + + +
+ ++
+ + Chris Lattner
+ The LLVM Compiler Infrastructure
+ Last modified: $Date$ + + +