264 lines · plain
1==================================================================2Getting Started with the LLVM System using Microsoft Visual Studio3==================================================================4 5 6.. contents::7 :local:8 9 10Overview11========12Welcome to LLVM on Windows! This document only covers LLVM on Windows using13Visual Studio, not WSL, mingw or cygwin. In order to get started, you first need14to know some basic information.15 16LLVM is composed of many different projects. The first piece is the17LLVM suite. This contains all of the tools, libraries, and header files needed18to use LLVM. It contains an assembler, disassembler, bitcode analyzer, and19bitcode optimizer. It also contains basic regression tests that can be used to20test the LLVM tools and the Clang front end.21 22The second piece is the `Clang <https://clang.llvm.org/>`_ front end. This23component compiles C, C++, Objective C, and Objective C++ code into LLVM24bitcode. Clang typically uses LLVM libraries to optimize the bitcode and emit25machine code. LLVM fully supports the COFF object file format, which is26compatible with all other existing Windows toolchains.27 28This document does not discuss other LLVM projects.29 30 31Requirements32============33Before you begin to use the LLVM system, review the requirements given34below. This may save you some trouble by knowing ahead of time what hardware35and software you will need.36 37Hardware38--------39Any system that can adequately run Visual Studio 2019 is fine. The LLVM40source tree, including the git index, consumes approximately 3GB.41Object files, libraries, and executables consume approximately 5GB in42Release mode and much more in Debug mode. An SSD drive and >16GB RAM are43recommended.44 45 46Software47--------48You will need `Visual Studio <https://visualstudio.microsoft.com/>`_ 2019 or49later, with the latest Update installed. Visual Studio Community Edition50suffices.51 52You will also need the `CMake <http://www.cmake.org/>`_ build system since it53generates the project files you will use to build with. CMake is bundled with54Visual Studio 2019 so a separate installation is not required. If you do install55CMake separately, Visual Studio 2022 will require CMake Version 3.21 or later.56 57If you would like to run the LLVM tests you will need `Python58<http://www.python.org/>`_. Version 3.8 and newer are known to work. You can59install Python with Visual Studio 2019, from the Microsoft store or from60the `Python web site <http://www.python.org/>`_. We recommend the latter since it61allows you to adjust installation options.62 63You will need `Git for Windows <https://git-scm.com/>`_ with bash tools, too.64Git for Windows is also bundled with Visual Studio 2019.65 66 67Getting Started68===============69Here's the short story for getting up and running quickly with LLVM.70These instructions were tested with Visual Studio 2019 and Python 3.9.6:71 721. Download and install `Visual Studio <https://visualstudio.microsoft.com/>`_.732. In the Visual Studio installer, Workloads tab, select the74 **Desktop development with C++** workload. Under Individual components tab,75 select **Git for Windows**.763. Complete the Visual Studio installation.774. Download and install the latest `Python 3 release <http://www.python.org/>`_.785. In the first install screen, select both **Install launcher for all users**79 and **Add Python to the PATH**. This will allow installing psutil for all80 users for the regression tests and make Python available from the command81 line.826. In the second install screen, select (again) **Install for all users** and83 if you want to develop `lldb <https://lldb.llvm.org/>`_, selecting84 **Download debug binaries** is useful.857. Complete the Python installation.868. Run a "Developer Command Prompt for VS 2019" **as administrator**. This command87 prompt provides the correct path and environment variables to Visual Studio and88 the installed tools.899. In the terminal window, type the commands:90 91 .. code-block:: bat92 93 c:94 cd \95 96 You may install the llvm sources in a location other than ``c:\llvm`` but do not97 install into a path containing spaces (e.g., ``c:\Documents and Settings\...``)98 as it will fail.99 10010. Register the Microsoft Debug Interface Access (DIA) DLLs:101 102 .. code-block:: bat103 104 regsvr32 "%VSINSTALLDIR%\DIA SDK\bin\msdia140.dll"105 regsvr32 "%VSINSTALLDIR%\DIA SDK\bin\amd64\msdia140.dll"106 107 The DIA library is required for LLVM PDB tests and108 `LLDB development <https://lldb.llvm.org/resources/build.html>`_.109 11011. Install psutil and obtain the LLVM source code:111 112 .. code-block:: bat113 114 pip install psutil115 git clone https://github.com/llvm/llvm-project.git llvm116 117 Instead of ``git clone`` you may download a compressed source distribution118 from the `releases page <https://github.com/llvm/llvm-project/releases>`_.119 Select the last link: ``Source code (zip)`` and unpack the downloaded file using120 Windows Explorer built-in zip support or any other unzip tool.121 12212. Finally, configure LLVM using CMake:123 124 .. code-block:: bat125 126 cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64127 exit128 129 .. note::130 By default, the Visual Studio project files generated by CMake use the131 32-bit toolset. If you are developing on a 64-bit version of Windows and132 want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when133 generating the Visual Studio solution. This requires CMake 3.8.0 or later.134 135 For Windows on Arm the equivalent is ``-Thost=ARM64``, but this the default136 for those hosts, so you do not have to use this option.137 138 ``LLVM_ENABLE_PROJECTS`` specifies any additional LLVM projects you want to139 build while ``LLVM_TARGETS_TO_BUILD`` selects the compiler targets. If140 ``LLVM_TARGETS_TO_BUILD`` is omitted by default all targets are built141 slowing compilation and using more disk space.142 See the :doc:`LLVM CMake guide <CMake>` for detailed information about143 how to configure the LLVM build.144 145 The ``cmake`` command line tool is bundled with Visual Studio but its GUI is146 not. You may install `CMake <http://www.cmake.org/>`_ to use its GUI to change147 CMake variables or modify the above command line.148 149 * Once CMake is installed then the simplest way is to just start the150 CMake GUI, select the directory where you have LLVM extracted to, and151 the default options should all be fine. One option you may really152 want to change, regardless of anything else, might be the153 ``CMAKE_INSTALL_PREFIX`` setting to select a directory to INSTALL to154 once compiling is complete, although installation is not mandatory for155 using LLVM. Another important option is ``LLVM_TARGETS_TO_BUILD``,156 which controls the LLVM target architectures that are included on the157 build.158 * CMake generates project files for all build types. To select a specific159 build type, use the Configuration manager from the VS IDE or the160 ``/property:Configuration`` command-line option when using MSBuild.161 16213. Start Visual Studio and select configuration:163 164 In the directory you created the project files will have an ``llvm.sln``165 file, just double-click on that to open Visual Studio. The default Visual166 Studio configuration is **Debug** which is slow and generates a huge amount167 of debug information on disk. For now, we recommend selecting **Release**168 configuration for the LLVM project which will build the fastest or169 **RelWithDebInfo** which is also several time larger than Release.170 Another technique is to build all of LLVM in Release mode and change171 compiler flags, disabling optimization and enabling debug information, only172 for specific libraries or source files you actually need to debug.173 17414. Test LLVM in Visual Studio:175 176 You can run LLVM tests by merely building the project "check-all". The test177 results will be shown in the VS output window. Once the build succeeds, you178 have verified a working LLVM development environment!179 180 You should not see any unexpected failures, but you will see many unsupported181 tests and expected failures:182 183 ::184 185 114>Testing Time: 1124.66s186 114> Skipped : 39187 114> Unsupported : 21649188 114> Passed : 51615189 114> Expectedly Failed: 93190 ========== Build: 114 succeeded, 0 failed, 321 up-to-date, 0 skipped ==========``191 192Alternatives to manual installation193===================================194Instead of the steps above, to simplify the installation procedure you can use195`Chocolatey <https://chocolatey.org/>`_ as package manager.196After the `installation <https://chocolatey.org/install>`_ of Chocolatey,197run these commands in an admin shell to install the required tools:198 199.. code-block:: bat200 201 choco install -y git cmake python3202 pip3 install psutil203 204There is also a Windows205`Dockerfile <https://github.com/llvm/llvm-zorg/blob/main/buildbot/google/docker/windows-base-vscode2019/Dockerfile>`_206with the entire build toolchain. This can be used to test the build with a207toolchain different from your host installation or to create build servers.208 209Next steps210==========2111. Read the documentation.2122. Seriously, read the documentation.2133. Remember that you were warned twice about reading the documentation.214 215Test LLVM on the command line:216------------------------------217The LLVM tests can be run by changing directory to the llvm source218directory and running:219 220.. code-block:: bat221 222 c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test223 224This example assumes that Python is in your ``PATH`` variable, which would be225after **Add Python to the PATH** was selected during Python installation.226If you had opened a command window prior to Python installation, you would227have to close and reopen it to get the updated ``PATH``.228 229A specific test or test directory can be run with:230 231.. code-block:: bat232 233 c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util234 235Build the LLVM Suite:236---------------------237* The projects may still be built individually, but to build them all do238 not just select all of them in batch build (as some are meant as239 configuration projects), but rather select and build just the240 ``ALL_BUILD`` project to build everything, or the ``INSTALL`` project,241 which first builds the ``ALL_BUILD`` project, then installs the LLVM242 headers, libs, and other useful things to the directory set by the243 ``CMAKE_INSTALL_PREFIX`` setting when you first configured CMake.244* The Fibonacci project is a sample program that uses the JIT. Modify the245 project's debugging properties to provide a numeric command-line argument246 or run it from the command line. The program will print the247 corresponding Fibonacci value.248 249 250Links251=====252This document is just an **introduction** to how to use LLVM to do some simple253things... there are many more interesting and complicated things that you can254do that aren't documented here (but we'll gladly accept a patch if you want to255write something up!). For more information about LLVM, check out:256 257* `LLVM homepage <https://llvm.org/>`_258* `LLVM doxygen tree <https://llvm.org/doxygen/>`_259* Additional information about the LLVM directory structure and tool chain260 can be found on the main :doc:`GettingStarted` page.261* If you are having problems building or using LLVM, or if you have any other262 general questions about LLVM, please consult the263 :doc:`Frequently Asked Questions <FAQ>` page.264