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