llvm/docs/GettingStartedVS.rst

   1 ==================================================================
   2 Getting Started with the LLVM System using Microsoft Visual Studio
   3 ==================================================================
   4
   5
   6 .. contents::
   7    :local:
   8
   9
  10 Overview
  11 ========
  12 Welcome to LLVM on Windows! This document only covers LLVM on Windows using
  13 Visual Studio, not WSL, mingw or cygwin. In order to get started, you first need
  14 to know some basic information.
  15
  16 There are many different projects that compose LLVM. The first piece is the
  17 LLVM suite. This contains all of the tools, libraries, and header files needed
  18 to use LLVM. It contains an assembler, disassembler, bitcode analyzer and
  19 bitcode optimizer. It also contains basic regression tests that can be used to
  20 test the LLVM tools and the Clang front end.
  21
  22 The second piece is the `Clang <https://clang.llvm.org/>`_ front end.  This
  23 component compiles C, C++, Objective C, and Objective C++ code into LLVM
  24 bitcode. Clang typically uses LLVM libraries to optimize the bitcode and emit
  25 machine code. LLVM fully supports the COFF object file format, which is
  26 compatible with all other existing Windows toolchains.
  27
  28 There are more LLVM projects which this document does not discuss.
  29
  30
  31 Requirements
  32 ============
  33 Before you begin to use the LLVM system, review the requirements given
  34 below.  This may save you some trouble by knowing ahead of time what hardware
  35 and software you will need.
  36
  37 Hardware
  38 --------
  39 Any system that can adequately run Visual Studio 2017 is fine. The LLVM
  40 source tree including the git index consumes approximately 3GB.
  41 Object files, libraries and executables consume approximately 5GB in
  42 Release mode and much more in Debug mode. SSD drive and >16GB RAM are
  43 recommended.
  44
  45
  46 Software
  47 --------
  48 You will need `Visual Studio <https://visualstudio.microsoft.com/>`_ 2017 or
  49 higher, with the latest Update installed. Visual Studio Community Edition
  50 suffices.
  51
  52 You will also need the `CMake <http://www.cmake.org/>`_ build system since it
  53 generates the project files you will use to build with. CMake is bundled with
  54 Visual Studio 2019 so separate installation is not required.
  55
  56 If you would like to run the LLVM tests you will need `Python
  57 <http://www.python.org/>`_. Version 3.6 and newer are known to work. You can
  58 install Python with Visual Studio 2019, from the Microsoft store or from
  59 the `Python web site <http://www.python.org/>`_. We recommend the latter since it
  60 allows you to to adjust installation options.
  61
  62 You will need `Git for Windows <https://git-scm.com/>`_ with bash tools, too.
  63 Git for Windows is also bundled with Visual Studio 2019.
  64
  65
  66 Getting Started
  67 ===============
  68 Here's the short story for getting up and running quickly with LLVM.
  69 These instruction were tested with Visual Studio 2019 and Python 3.9.6:
  70
  71 1. Download and install `Visual Studio <https://visualstudio.microsoft.com/>`_.
  72 2. In the Visual Studio installer, Workloads tab, select the
  73    **Desktop development with C++** workload. Under Individual components tab,
  74    select **Git for Windows**.
  75 3. Complete the Visual Studio installation.
  76 4. Download and install the latest `Python 3 release <http://www.python.org/>`_.
  77 5. In the first install screen, select both **Install launcher for all users**
  78    and **Add Python to the PATH**. This will allow installing psutil for all
  79    users for the regression tests and make Python available from the command
  80    line.
  81 6. In the second install screen, select (again) **Install for all users** and
  82    if you want to develop `lldb <https://lldb.llvm.org/>`_, selecting
  83    **Download debug binaries** is useful.
  84 7. Complete the Python installation.
  85 8. Run a "Developer Command Prompt for VS 2019" **as administrator**. This command
  86     prompt provides correct path and environment variables to Visual Studio and
  87     the installed tools.
  88 9. In the terminal window, type the commands:
  89
  90    .. code-block:: bat
  91
  92      c:
  93      cd \
  94
  95   You may install the llvm sources in other location than ``c:\llvm`` but do not
  96   install into a path containing spaces (e.g. ``c:\Documents and Settings\...``)
  97   as it will fail.
  98
  99 10. Register the Microsoft Debug Interface Access (DIA) DLLs
 100
 101     .. code-block:: bat
 102
 103      regsvr32 "%VSINSTALLDIR%\DIA SDK\bin\msdia140.dll"
 104      regsvr32 "%VSINSTALLDIR%\DIA SDK\bin\amd64\msdia140.dll"
 105
 106  The DIA library is required for LLVM PDB tests and
 107  `LLDB development <https://lldb.llvm.org/resources/build.html>`_.
 108
 109 11. Install psutil and obtain LLVM source code:
 110
 111     .. code-block:: bat
 112
 113      pip install psutil
 114      git clone https://github.com/llvm/llvm-project.git llvm
 115
 116  Instead of ``git clone`` you may download a compressed source distribution
 117  from the `releases page <https://github.com/llvm/llvm-project/releases>`_.
 118  Select the last link: ``Source code (zip)`` and unpack the downloaded file using
 119  Windows Explorer built-in zip support or any other unzip tool.
 120
 121 12. Finally, configure LLVM using CMake:
 122
 123     .. code-block:: bat
 124
 125        cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64
 126        exit
 127
 128    ``LLVM_ENABLE_PROJECTS`` specifies any additional LLVM projects you want to
 129    build while ``LLVM_TARGETS_TO_BUILD`` selects the compiler targets. If
 130    ``LLVM_TARGETS_TO_BUILD`` is omitted by default all targets are built
 131    slowing compilation and using more disk space.
 132    See the :doc:`LLVM CMake guide <CMake>` for detailed information about
 133    how to configure the LLVM build.
 134
 135    The ``cmake`` command line tool is bundled with Visual Studio but its GUI is
 136    not. You may install `CMake <http://www.cmake.org/>`_ to use its GUI to change
 137    CMake variables or modify the above command line.
 138
 139    * Once CMake is installed then the simplest way is to just start the
 140      CMake GUI, select the directory where you have LLVM extracted to, and
 141      the default options should all be fine.  One option you may really
 142      want to change, regardless of anything else, might be the
 143      ``CMAKE_INSTALL_PREFIX`` setting to select a directory to INSTALL to
 144      once compiling is complete, although installation is not mandatory for
 145      using LLVM.  Another important option is ``LLVM_TARGETS_TO_BUILD``,
 146      which controls the LLVM target architectures that are included on the
 147      build.
 148    * CMake generates project files for all build types. To select a specific
 149      build type, use the Configuration manager from the VS IDE or the
 150      ``/property:Configuration`` command line option when using MSBuild.
 151    * By default, the Visual Studio project files generated by CMake use the
 152      32-bit toolset. If you are developing on a 64-bit version of Windows and
 153      want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when
 154      generating the Visual Studio solution. This requires CMake 3.8.0 or later.
 155
 156 13. Start Visual Studio and select configuration:
 157
 158    In the directory you created the project files will have an ``llvm.sln``
 159    file, just double-click on that to open Visual Studio. The default Visual
 160    Studio configuration is **Debug** which is slow and generates a huge amount
 161    of debug information on disk. For now, we recommend selecting **Release**
 162    configuration for the LLVM project which will build the fastest or
 163    **RelWithDebInfo** which is also several time larger than Release.
 164    Another technique is to build all of LLVM in Release mode and change
 165    compiler flags, disabling optimization and enabling debug information, only
 166    for specific librares or source files you actually need to debug.
 167
 168 14. Test LLVM in Visual Studio:
 169
 170    You can run LLVM tests by merely building the project "check-all". The test
 171    results will be shown in the VS output window. Once the build succeeds, you
 172    have verified a working LLVM development environment!
 173
 174    You should not see any unexpected failures, but will see many unsupported
 175    tests and expected failures:
 176
 177    ::
 178
 179     114>Testing Time: 1124.66s
 180     114>  Skipped          :    39
 181     114>  Unsupported      : 21649
 182     114>  Passed           : 51615
 183     114>  Expectedly Failed:    93
 184     ========== Build: 114 succeeded, 0 failed, 321 up-to-date, 0 skipped ==========``
 185
 186 Alternatives to manual installation
 187 ===================================
 188 Instead of the steps above, to simplify the installation procedure you can use
 189 `Chocolatey <https://chocolatey.org/>`_ as package manager.
 190 After the `installation <https://chocolatey.org/install>`_ of Chocolatey,
 191 run these commands in an admin shell to install the required tools:
 192
 193 .. code-block:: bat
 194
 195    choco install -y git cmake python3
 196    pip3 install psutil
 197
 198 There is also a Windows
 199 `Dockerfile <https://github.com/llvm/llvm-zorg/blob/main/buildbot/google/docker/windows-base-vscode2019/Dockerfile>`_
 200 with the entire build tool chain. This can be used to test the build with a
 201 tool chain different from your host installation or to create build servers.
 202
 203 Next steps
 204 ==========
 205 1. Read the documentation.
 206 2. Seriously, read the documentation.
 207 3. Remember that you were warned twice about reading the documentation.
 208
 209 Test LLVM on the command line:
 210 ------------------------------
 211 The LLVM tests can be run by changing directory to the llvm source
 212 directory and running:
 213
 214 .. code-block:: bat
 215
 216   c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test
 217
 218 This example assumes that Python is in your PATH variable, which would be
 219 after **Add Python to the PATH** was selected during Python installation.
 220 If you had opened a command window prior to Python installation, you would
 221 have to close and reopen it to get the updated PATH.
 222
 223 A specific test or test directory can be run with:
 224
 225 .. code-block:: bat
 226
 227   c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util
 228
 229 Build the LLVM Suite:
 230 ---------------------
 231 * The projects may still be built individually, but to build them all do
 232   not just select all of them in batch build (as some are meant as
 233   configuration projects), but rather select and build just the
 234   ``ALL_BUILD`` project to build everything, or the ``INSTALL`` project,
 235   which first builds the ``ALL_BUILD`` project, then installs the LLVM
 236   headers, libs, and other useful things to the directory set by the
 237   ``CMAKE_INSTALL_PREFIX`` setting when you first configured CMake.
 238 * The Fibonacci project is a sample program that uses the JIT. Modify the
 239   project's debugging properties to provide a numeric command line argument
 240   or run it from the command line.  The program will print the
 241   corresponding fibonacci value.
 242
 243
 244 Links
 245 =====
 246 This document is just an **introduction** to how to use LLVM to do some simple
 247 things... there are many more interesting and complicated things that you can
 248 do that aren't documented here (but we'll gladly accept a patch if you want to
 249 write something up!).  For more information about LLVM, check out:
 250
 251 * `LLVM homepage <https://llvm.org/>`_
 252 * `LLVM doxygen tree <https://llvm.org/doxygen/>`_
 253 * Additional information about the LLVM directory structure and tool chain
 254   can be found on the main :doc:`GettingStarted` page.
 255 * If you are having problems building or using LLVM, or if you have any other
 256   general questions about LLVM, please consult the
 257   :doc:`Frequently Asked Questions <FAQ>` page.