Getting Started with the LLVM System using Microsoft Visual Studio¶
Welcome to LLVM on Windows! This document only covers LLVM on Windows using Visual Studio, not WSL, mingw or cygwin. In order to get started, you first need to know some basic information.
There are many different projects that compose LLVM. The first piece is the LLVM suite. This contains all of the tools, libraries, and header files needed to use LLVM. It contains an assembler, disassembler, bitcode analyzer and bitcode optimizer. It also contains basic regression tests that can be used to test the LLVM tools and the Clang front end.
The second piece is the Clang front end. This component compiles C, C++, Objective C, and Objective C++ code into LLVM bitcode. Clang typically uses LLVM libraries to optimize the bitcode and emit machine code. LLVM fully supports the COFF object file format, which is compatible with all other existing Windows toolchains.
There are more LLVM projects which this document does not discuss.
Before you begin to use the LLVM system, review the requirements given below. This may save you some trouble by knowing ahead of time what hardware and software you will need.
Any system that can adequately run Visual Studio 2019 is fine. The LLVM source tree including the git index consumes approximately 3GB. Object files, libraries and executables consume approximately 5GB in Release mode and much more in Debug mode. SSD drive and >16GB RAM are recommended.
You will need Visual Studio 2019 or later, with the latest Update installed. Visual Studio Community Edition suffices.
You will also need the CMake build system since it generates the project files you will use to build with. CMake is bundled with Visual Studio 2019 so separate installation is not required. If you do install CMake separately, Visual Studio 2022 will require CMake Version 3.21 or later.
If you would like to run the LLVM tests you will need Python. Version 3.6 and newer are known to work. You can install Python with Visual Studio 2019, from the Microsoft store or from the Python web site. We recommend the latter since it allows you to adjust installation options.
You will need Git for Windows with bash tools, too. Git for Windows is also bundled with Visual Studio 2019.
Here’s the short story for getting up and running quickly with LLVM. These instruction were tested with Visual Studio 2019 and Python 3.9.6:
Download and install Visual Studio.
In the Visual Studio installer, Workloads tab, select the Desktop development with C++ workload. Under Individual components tab, select Git for Windows.
Complete the Visual Studio installation.
Download and install the latest Python 3 release.
In the first install screen, select both Install launcher for all users and Add Python to the PATH. This will allow installing psutil for all users for the regression tests and make Python available from the command line.
In the second install screen, select (again) Install for all users and if you want to develop lldb, selecting Download debug binaries is useful.
Complete the Python installation.
- Run a “Developer Command Prompt for VS 2019” as administrator. This command
prompt provides correct path and environment variables to Visual Studio and the installed tools.
In the terminal window, type the commands:
c: cd \
You may install the llvm sources in other location than
c:\llvmbut do not install into a path containing spaces (e.g.
c:\Documents and Settings\...) as it will fail.
Register the Microsoft Debug Interface Access (DIA) DLLs
regsvr32 "%VSINSTALLDIR%\DIA SDK\bin\msdia140.dll" regsvr32 "%VSINSTALLDIR%\DIA SDK\bin\amd64\msdia140.dll"
The DIA library is required for LLVM PDB tests and LLDB development.
Install psutil and obtain LLVM source code:
pip install psutil git clone https://github.com/llvm/llvm-project.git llvm
git cloneyou may download a compressed source distribution from the releases page. Select the last link:
Source code (zip)and unpack the downloaded file using Windows Explorer built-in zip support or any other unzip tool.
Finally, configure LLVM using CMake:
cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64 exit
LLVM_ENABLE_PROJECTSspecifies any additional LLVM projects you want to build while
LLVM_TARGETS_TO_BUILDselects the compiler targets. If
LLVM_TARGETS_TO_BUILDis omitted by default all targets are built slowing compilation and using more disk space. See the LLVM CMake guide for detailed information about how to configure the LLVM build.
cmakecommand line tool is bundled with Visual Studio but its GUI is not. You may install CMake to use its GUI to change CMake variables or modify the above command line.
Once CMake is installed then the simplest way is to just start the CMake GUI, select the directory where you have LLVM extracted to, and the default options should all be fine. One option you may really want to change, regardless of anything else, might be the
CMAKE_INSTALL_PREFIXsetting to select a directory to INSTALL to once compiling is complete, although installation is not mandatory for using LLVM. Another important option is
LLVM_TARGETS_TO_BUILD, which controls the LLVM target architectures that are included on the build.
CMake generates project files for all build types. To select a specific build type, use the Configuration manager from the VS IDE or the
/property:Configurationcommand line option when using MSBuild.
By default, the Visual Studio project files generated by CMake use the 32-bit toolset. If you are developing on a 64-bit version of Windows and want to use the 64-bit toolset, pass the
-Thost=x64flag when generating the Visual Studio solution. This requires CMake 3.8.0 or later.
Start Visual Studio and select configuration:
In the directory you created the project files will have an
llvm.slnfile, just double-click on that to open Visual Studio. The default Visual Studio configuration is Debug which is slow and generates a huge amount of debug information on disk. For now, we recommend selecting Release configuration for the LLVM project which will build the fastest or RelWithDebInfo which is also several time larger than Release. Another technique is to build all of LLVM in Release mode and change compiler flags, disabling optimization and enabling debug information, only for specific libraries or source files you actually need to debug.
Test LLVM in Visual Studio:
You can run LLVM tests by merely building the project “check-all”. The test results will be shown in the VS output window. Once the build succeeds, you have verified a working LLVM development environment!
You should not see any unexpected failures, but will see many unsupported tests and expected failures:114>Testing Time: 1124.66s 114> Skipped : 39 114> Unsupported : 21649 114> Passed : 51615 114> Expectedly Failed: 93 ========== Build: 114 succeeded, 0 failed, 321 up-to-date, 0 skipped ==========``
Instead of the steps above, to simplify the installation procedure you can use Chocolatey as package manager. After the installation of Chocolatey, run these commands in an admin shell to install the required tools:
choco install -y git cmake python3
pip3 install psutil
There is also a Windows Dockerfile with the entire build tool chain. This can be used to test the build with a tool chain different from your host installation or to create build servers.
Read the documentation.
Seriously, read the documentation.
Remember that you were warned twice about reading the documentation.
The LLVM tests can be run by changing directory to the llvm source directory and running:
c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test
This example assumes that Python is in your PATH variable, which would be after Add Python to the PATH was selected during Python installation. If you had opened a command window prior to Python installation, you would have to close and reopen it to get the updated PATH.
A specific test or test directory can be run with:
c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util
The projects may still be built individually, but to build them all do not just select all of them in batch build (as some are meant as configuration projects), but rather select and build just the
ALL_BUILDproject to build everything, or the
INSTALLproject, which first builds the
ALL_BUILDproject, then installs the LLVM headers, libs, and other useful things to the directory set by the
CMAKE_INSTALL_PREFIXsetting when you first configured CMake.
The Fibonacci project is a sample program that uses the JIT. Modify the project’s debugging properties to provide a numeric command line argument or run it from the command line. The program will print the corresponding fibonacci value.