Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 1 | ================================================================== |
| 2 | Getting Started with the LLVM System using Microsoft Visual Studio |
| 3 | ================================================================== |
| 4 | |
| 5 | .. contents:: |
| 6 | :local: |
| 7 | |
| 8 | |
| 9 | Overview |
| 10 | ======== |
| 11 | Welcome to LLVM on Windows! This document only covers LLVM on Windows using |
| 12 | Visual Studio, not mingw or cygwin. In order to get started, you first need to |
| 13 | know some basic information. |
| 14 | |
| 15 | There are many different projects that compose LLVM. The first is the LLVM |
| 16 | suite. This contains all of the tools, libraries, and header files needed to |
| 17 | use LLVM. It contains an assembler, disassembler, |
| 18 | bitcode analyzer and bitcode optimizer. It also contains a test suite that can |
| 19 | be used to test the LLVM tools. |
| 20 | |
| 21 | Another useful project on Windows is `Clang <http://clang.llvm.org/>`_. |
| 22 | Clang is a C family ([Objective]C/C++) compiler. Clang mostly works on |
| 23 | Windows, but does not currently understand all of the Microsoft extensions |
| 24 | to C and C++. Because of this, clang cannot parse the C++ standard library |
| 25 | included with Visual Studio, nor parts of the Windows Platform SDK. However, |
| 26 | most standard C programs do compile. Clang can be used to emit bitcode, |
| 27 | directly emit object files or even linked executables using Visual Studio's |
| 28 | ``link.exe``. |
| 29 | |
| 30 | The large LLVM test suite cannot be run on the Visual Studio port at this |
| 31 | time. |
| 32 | |
| 33 | Most of the tools build and work. ``bugpoint`` does build, but does |
| 34 | not work. |
| 35 | |
| 36 | Additional information about the LLVM directory structure and tool chain |
| 37 | can be found on the main `Getting Started <GettingStarted.html>`_ page. |
| 38 | |
| 39 | |
| 40 | Requirements |
| 41 | ============ |
| 42 | Before you begin to use the LLVM system, review the requirements given |
| 43 | below. This may save you some trouble by knowing ahead of time what hardware |
| 44 | and software you will need. |
| 45 | |
| 46 | Hardware |
| 47 | -------- |
Ahmed Bougacha | 0ac7246 | 2013-07-23 17:25:26 +0000 | [diff] [blame] | 48 | Any system that can adequately run Visual Studio 2010 is fine. The LLVM |
Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 49 | source tree and object files, libraries and executables will consume |
| 50 | approximately 3GB. |
| 51 | |
| 52 | Software |
| 53 | -------- |
Ahmed Bougacha | 0ac7246 | 2013-07-23 17:25:26 +0000 | [diff] [blame] | 54 | You will need Visual Studio 2010 or higher. Earlier versions of Visual |
Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 55 | Studio have bugs, are not completely compatible, or do not support the C++ |
| 56 | standard well enough. |
| 57 | |
| 58 | You will also need the `CMake <http://www.cmake.org/>`_ build system since it |
| 59 | generates the project files you will use to build with. |
| 60 | |
| 61 | If you would like to run the LLVM tests you will need `Python |
| 62 | <http://www.python.org/>`_. Versions 2.4-2.7 are known to work. You will need |
| 63 | `GnuWin32 <http://gnuwin32.sourceforge.net/>`_ tools, too. |
| 64 | |
| 65 | Do not install the LLVM directory tree into a path containing spaces (e.g. |
| 66 | ``C:\Documents and Settings\...``) as the configure step will fail. |
| 67 | |
| 68 | |
| 69 | Getting Started |
| 70 | =============== |
| 71 | Here's the short story for getting up and running quickly with LLVM: |
| 72 | |
| 73 | 1. Read the documentation. |
| 74 | 2. Seriously, read the documentation. |
| 75 | 3. Remember that you were warned twice about reading the documentation. |
| 76 | 4. Get the Source Code |
| 77 | |
| 78 | * With the distributed files: |
| 79 | |
| 80 | 1. ``cd <where-you-want-llvm-to-live>`` |
| 81 | 2. ``gunzip --stdout llvm-VERSION.tar.gz | tar -xvf -`` |
| 82 | (*or use WinZip*) |
| 83 | 3. ``cd llvm`` |
| 84 | |
| 85 | * With anonymous Subversion access: |
| 86 | |
| 87 | 1. ``cd <where-you-want-llvm-to-live>`` |
| 88 | 2. ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` |
| 89 | 3. ``cd llvm`` |
| 90 | |
| 91 | 5. Use `CMake <http://www.cmake.org/>`_ to generate up-to-date project files: |
| 92 | |
| 93 | * Once CMake is installed then the simplest way is to just start the |
| 94 | CMake GUI, select the directory where you have LLVM extracted to, and |
| 95 | the default options should all be fine. One option you may really |
| 96 | want to change, regardless of anything else, might be the |
| 97 | ``CMAKE_INSTALL_PREFIX`` setting to select a directory to INSTALL to |
| 98 | once compiling is complete, although installation is not mandatory for |
| 99 | using LLVM. Another important option is ``LLVM_TARGETS_TO_BUILD``, |
| 100 | which controls the LLVM target architectures that are included on the |
| 101 | build. |
| 102 | * See the `LLVM CMake guide <CMake.html>`_ for detailed information about |
| 103 | how to configure the LLVM build. |
| 104 | |
| 105 | 6. Start Visual Studio |
| 106 | |
| 107 | * In the directory you created the project files will have an ``llvm.sln`` |
| 108 | file, just double-click on that to open Visual Studio. |
| 109 | |
| 110 | 7. Build the LLVM Suite: |
| 111 | |
| 112 | * The projects may still be built individually, but to build them all do |
| 113 | not just select all of them in batch build (as some are meant as |
| 114 | configuration projects), but rather select and build just the |
| 115 | ``ALL_BUILD`` project to build everything, or the ``INSTALL`` project, |
| 116 | which first builds the ``ALL_BUILD`` project, then installs the LLVM |
| 117 | headers, libs, and other useful things to the directory set by the |
| 118 | ``CMAKE_INSTALL_PREFIX`` setting when you first configured CMake. |
| 119 | * The Fibonacci project is a sample program that uses the JIT. Modify the |
| 120 | project's debugging properties to provide a numeric command line argument |
| 121 | or run it from the command line. The program will print the |
| 122 | corresponding fibonacci value. |
| 123 | |
| 124 | 8. Test LLVM on Visual Studio: |
| 125 | |
| 126 | * If ``%PATH%`` does not contain GnuWin32, you may specify |
| 127 | ``LLVM_LIT_TOOLS_DIR`` on CMake for the path to GnuWin32. |
| 128 | * You can run LLVM tests by merely building the project "check". The test |
| 129 | results will be shown in the VS output window. |
| 130 | |
| 131 | .. FIXME: Is it up-to-date? |
| 132 | |
| 133 | 9. Test LLVM: |
| 134 | |
| 135 | * The LLVM tests can be run by changing directory to the llvm source |
| 136 | directory and running: |
| 137 | |
| 138 | .. code-block:: bat |
| 139 | |
Aaron Ballman | a7eccdc | 2013-05-01 19:13:50 +0000 | [diff] [blame] | 140 | C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test |
Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 141 | |
Aaron Ballman | a7eccdc | 2013-05-01 19:13:50 +0000 | [diff] [blame] | 142 | This example assumes that Python is in your PATH variable, you |
| 143 | have built a Win32 Debug version of llvm with a standard out of |
| 144 | line build. You should not see any unexpected failures, but will |
| 145 | see many unsupported tests and expected failures. |
Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 146 | |
| 147 | A specific test or test directory can be run with: |
| 148 | |
| 149 | .. code-block:: bat |
| 150 | |
Aaron Ballman | a7eccdc | 2013-05-01 19:13:50 +0000 | [diff] [blame] | 151 | C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test/path/to/test |
Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 152 | |
| 153 | |
| 154 | An Example Using the LLVM Tool Chain |
| 155 | ==================================== |
| 156 | |
| 157 | 1. First, create a simple C file, name it '``hello.c``': |
| 158 | |
| 159 | .. code-block:: c |
| 160 | |
| 161 | #include <stdio.h> |
| 162 | int main() { |
| 163 | printf("hello world\n"); |
| 164 | return 0; |
| 165 | } |
| 166 | |
Daniel Dunbar | 1323006 | 2013-08-16 23:30:19 +0000 | [diff] [blame] | 167 | 2. Next, compile the C file into an LLVM bitcode file: |
Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 168 | |
| 169 | .. code-block:: bat |
| 170 | |
| 171 | C:\..> clang -c hello.c -emit-llvm -o hello.bc |
| 172 | |
| 173 | This will create the result file ``hello.bc`` which is the LLVM bitcode |
Sylvestre Ledru | c8e41c5 | 2012-07-23 08:51:15 +0000 | [diff] [blame] | 174 | that corresponds the compiled program and the library facilities that |
Michael J. Spencer | 55eda32 | 2012-06-21 23:27:09 +0000 | [diff] [blame] | 175 | it required. You can execute this file directly using ``lli`` tool, |
| 176 | compile it to native assembly with the ``llc``, optimize or analyze it |
| 177 | further with the ``opt`` tool, etc. |
| 178 | |
| 179 | Alternatively you can directly output an executable with clang with: |
| 180 | |
| 181 | .. code-block:: bat |
| 182 | |
| 183 | C:\..> clang hello.c -o hello.exe |
| 184 | |
| 185 | The ``-o hello.exe`` is required because clang currently outputs ``a.out`` |
| 186 | when neither ``-o`` nor ``-c`` are given. |
| 187 | |
| 188 | 3. Run the program using the just-in-time compiler: |
| 189 | |
| 190 | .. code-block:: bat |
| 191 | |
| 192 | C:\..> lli hello.bc |
| 193 | |
| 194 | 4. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code: |
| 195 | |
| 196 | .. code-block:: bat |
| 197 | |
| 198 | C:\..> llvm-dis < hello.bc | more |
| 199 | |
| 200 | 5. Compile the program to object code using the LLC code generator: |
| 201 | |
| 202 | .. code-block:: bat |
| 203 | |
| 204 | C:\..> llc -filetype=obj hello.bc |
| 205 | |
| 206 | 6. Link to binary using Microsoft link: |
| 207 | |
| 208 | .. code-block:: bat |
| 209 | |
| 210 | C:\..> link hello.obj -defaultlib:libcmt |
| 211 | |
| 212 | 7. Execute the native code program: |
| 213 | |
| 214 | .. code-block:: bat |
| 215 | |
| 216 | C:\..> hello.exe |
| 217 | |
| 218 | |
| 219 | Common Problems |
| 220 | =============== |
| 221 | If you are having problems building or using LLVM, or if you have any other |
| 222 | general questions about LLVM, please consult the `Frequently Asked Questions |
| 223 | <FAQ.html>`_ page. |
| 224 | |
| 225 | |
| 226 | Links |
| 227 | ===== |
| 228 | This document is just an **introduction** to how to use LLVM to do some simple |
| 229 | things... there are many more interesting and complicated things that you can |
| 230 | do that aren't documented here (but we'll gladly accept a patch if you want to |
| 231 | write something up!). For more information about LLVM, check out: |
| 232 | |
| 233 | * `LLVM homepage <http://llvm.org/>`_ |
| 234 | * `LLVM doxygen tree <http://llvm.org/doxygen/>`_ |
| 235 | |