Playing with LLVM on Windows

This repository gathers LLVM code examples coming from various websites and books.
It also includes several build scripts (batch files, Make scripts) for experimenting with the LLVM infrastructure on a Windows machine.

Ada, Akka, C++, Dart, Deno, Docker, Flix, Golang, GraalVM, Haskell, Kafka, Kotlin, Node.js, Rust, Scala 3, Spark, Spring, TruffleSqueak and WiX Toolset are other trending topics we are continuously monitoring.

Project dependencies

This project depends on the following external software for the Microsoft Windows platform:

Optionally one may also install the following software:

Cppcheck 2.11 ³ (changelog)
Doxygen 1.9 (changelog)
LLVM 14 Windows binaries ¹ (release notes)
MSYS2 ⁴
Ninja 1.11 (release notes)

For instance our development environment looks as follows (October 2023) ⁵:

C:\opt\cmake-3.27.7-windows-x86_64\  ( 106 MB)
C:\opt\doxygen-1.9.8\                ( 117 MB)
C:\opt\Git\                          ( 358 MB)
C:\opt\LLVM-8.0.1\                   (1.1  GB)
C:\opt\LLVM-9.0.1\                   (1.3  GB)
C:\opt\LLVM-10.0.1\                  (1.5 resp 2.6 GB)
C:\opt\LLVM-11.1.0\                  (1.5 resp 3.0 GB)
C:\opt\LLVM-12.0.1\                  (1.5 resp 3.7 GB)
C:\opt\LLVM-14.0.6\                  (2.1 resp 3.1 GB)
C:\opt\LLVM-15.0.7\                  (3.1 GB)
C:\opt\LLVM-16.0.6\                  (2.5 GB)
C:\opt\msys64\                       (2.85 GB)
C:\opt\ninja-1.11.1\                 ( 0.5 MB)
C:\Program Files\Cppcheck\           (  48 MB)
C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\  (2.98 GB)
C:\opt\Python-3.11.1\                (  61 MB)

☛ Installation policy
When possible we install software from a Zip archive rather than via a Windows installer. In our case we defined C:\opt\ as the installation directory for optional software tools (in reference to the /opt/ directory on Unix).

Directory structure ▴

This project is organized as follows:

bin\pelook.exe  (changelist)
bin\vswhere.exe
bin\llvm\build.bat
docs\
examples\{README.md, hello, JITTutorial1, etc.}
llvm-12.0.1.src\    (extracted from file llvm-12.0.1.src.tar.xz)
llvm-13.0.1.src\    (extracted from file llvm-13.0.1.src.tar.xz)
llvm-14.0.6.src\    (extracted from file llvm-14.0.6.src.tar.xz)
llvm-15.0.7.src\    (extracted from file llvm-15.0.7.src.tar.xz)
llvm-16.0.6.src\    (extracted from file llvm-16.0.6.src.tar.xz)
llvm-essentials{README.md, 1_2_Getting_familiar_with_LLVM_IR, etc.}
BUILD.md
README.md
RESOURCES.md
setenv.bat

where

directory bin\ contains a batch file and the tools vswhere and pelook.
directory docs\ contains several LLVM related papers/articles.
directory examples\ contains LLVM code examples (see examples\README.md).
directory llvm-12.0.1.src\ contains the LLVM 12 source code distribution.
directory llvm-13.0.1.src\ contains the LLVM 13 source code distribution.
directory llvm-14.0.6.src\ contains the LLVM 14 source code distribution.
directory llvm-15.0.7.src\ contains the LLVM 15 source code distribution.
directory llvm-16.0.6.src\ contains the LLVM 16 source code distribution.
file BUILD.md describes the build from the source distribution.
file README.md is the Markdown document for this page.
file RESOURCES.md is the Markdown document presenting external resources.
file setenv.bat is the batch script for setting up our environment.

We also define a virtual drive – e.g. drive L: – in our working environment in order to reduce/hide the real path of our project directory (see article "Windows command prompt limitation" from Microsoft Support).

🔎 We use the Windows external command subst to create virtual drives; for instance:
> subst L: %USERPROFILE%\workspace\llvm-examples

In the next section we give a brief description of the batch files present in this project.

Batch commands ▴

We distinguish different sets of batch commands:

setenv.bat - This batch command makes external tools such as clang.exe and git.exe directly available from the command prompt (see section Project dependencies).

> setenv help
Usage: setenv { <option> | <subcommand> }
 
  Options::
    -bash          start Git bash shell instead of Windows command prompt
    -debug         print commands executed by this script
    -llvm:<8..15>  select version of LLVM installation
    -verbose       print progress messages
 
  Subcommands:
    help           print this help message

bin\llvm\build.bat - This batch command generates/installs additional files such as executables, header files, library files, CMake modules not available in LLVM installation directory (in our case C:\opt\LLVM-15.0.7\).

> build help
Usage: build { <option> | <subcommand> }
 
  Options:
    -debug      print commands executed by this script
    -timer      print total execution time
    -verbose    print progress messages
 
  Subcommands:
    clean       delete generated files
    compile     generate executable
    help        print this help message
    install     install files generated in directory build
    run         run executable

Usage examples ▴

`setenv.bat`

Command setenv.bat is executed once to setup our development environment; it makes external tools such as clang.exe, opt.exe and git.exe directly available from the command prompt:

> setenv
Tool versions:
   clang 15.0.7, lli 15.0.7, opt 15.0.7, doxygen 1.9.8, pelook v1.73,
   cmake 3.27.7, cppcheck 2.10, make 4.3, gcc 13.2.0, python 3.11.1,
   git 2.42.0.windows.1, diff 3.10, bash 5.2.15(1)-release

> where clang git
C:\opt\LLVM-15.0.7\bin\clang.exe
C:\opt\Git\bin\git.exe
C:\opt\Git\mingw64\bin\git.exe

☛ Important note
Command setenv.bat does not add MSVS CMake and GNU Cmake to the PATH environment variable because of name conflict. We write either %MSVS_CMAKE_HOME%\bin\cmake.exe or %CMAKE_HOME%\bin\cmake.exe.

Command setenv.bat with option -verbose displays additional information:

the tool paths (which may not contain the version suffix, i.e. C:\opt\Git\bin\git.exe in some installations),
the environment variables defined locally within this session,
and the path associations (i.e. F:\ in this case, but other drive names may be displayed as path associations are globally defined).

> setenv -verbose
Tool versions:
   clang 15.0.7, lli 15.0.7, opt 15.0.7, doxygen 1.9.8, pelook v1.73,
   cmake 3.27.7, cppcheck 2.10, make 4.3, gcc 13.2.0, python 3.11.1,
   git 2.42.0.windows.1, diff 3.10, bash 5.2.15(1)-release
Tool paths:
   C:\opt\LLVM-15.0.7\bin\clang.exe
   C:\opt\LLVM-15.0.7\bin\lli.exe
   C:\opt\LLVM-15.0.7\bin\opt.exe
   C:\opt\cmake-3.27.7\bin\cmake.exe
   C:\opt\msys64\usr\bin\make.exe
   C:\opt\msys64\mingw64\bin\gcc.exe
   C:\opt\Python-3.11.1\python.exe
   C:\opt\msys64\usr\bin\python.exe
   C:\opt\msys64\mingw64\bin\python.exe
   C:\opt\msys64\usr\bin\diff.exe
   C:\opt\Git\usr\bin\diff.exe
   C:\opt\Git\bin\git.exe
   C:\opt\Git\mingw64\bin\git.exe
   C:\opt\Git\bin\bash.exe
Environment variables:
   "CMAKE_HOME=C:\opt\cmake-3.27.7-win64-x64"
   "CPPCHECK_HOME=C:\Program Files\Cppcheck"
   "DOXYGEN_HOME=C:\opt\doxygen-1.9.8"
   "LLVM_HOME=C:\opt\LLVM-15.0.7"
   "MSVC_HOME=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC"
   "MSVS_HOME=C:\Program Files (x86)\Microsoft Visual Studio\2019"
   "MSVS_CMAKE_HOME=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\..\Cmake"
   "MSYS_HOME=C:\opt\msys64"
   "PYTHON_HOME=C:\opt\Python-3.11.1"
Path associations:
   L:\: => C:\Users\michelou\workspace-perso\llvm-examples

`llvm-X.Y.Z.src\build.bat`

We wrote the batch file build.bat to generate additional Windows binaries not available in the LLVM binary distribution.

🔎 For instance, LLVM tools such as llvm-as.exe (assembler), llvm-dis.exe (disassembler), opt.exe (optimizer), llc.exe (static compiler) and lli.exe (bitcode interpreter) are not part of the LLVM binary distribution (e.g. LLVM-15.0.7-win64.exe).

It provides the following options and subcommands:

> build
Usage: build { <option> | <subcommand> }
 
  Options:
    -debug      print commands executed by this script
    -timer      print total execution time
    -verbose    print progress messages
 
  Subcommands:
    clean       delete generated files
    compile     generate executable
    help        print this help message
    install     install files generated in directory build
    run         run the generated executable

See document BUILD.md for more details.

`examples\JITTutorial1\build.bat`

See document examples\README.md.

Resources

See document RESOURCES.md for LLVM related resources.

Footnotes▴

[1] LLVM version ↩

We support LLVM versions 8 up to 15. Command setenv searches for version 15 per default; use command setenv -llvm:8 to work with LLVM 8 (and so on).

[2] Visual Studio version ↩

Version 16.5 or newer of Visual Studio 2019 is required to build LLVM 10 while version 16.4 is fine to build LLVM 8 and 9.

> build -verbose compile Toolset: MSVC/MSBuild, Project: LLVM ********************************************************************** ** Visual Studio 2019 Developer Command Prompt v16.4.0 ** Copyright (c) 2019 Microsoft Corporation ********************************************************************** [vcvarsall.bat] Environment initialized for: 'x64' [...] Configuration: Debug, Platform: x64 Generate configuration files into directory "build" CMake Error at cmake/modules/CheckCompilerVersion.cmake:62 (message): Host Visual Studio version 16.4 is known to miscompile part of LLVM, please use clang-cl or upgrade to 16.5 or above (use -DLLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN=ON to ignore) Call Stack (most recent call first): cmake/config-ix.cmake:13 (include) CMakeLists.txt:623 (include)

Error: Generation of build configuration failed

[3] Cppcheck installation ↩

The Cppcheck static analysis tool can be installed in two ways on MS Windows, namely:

MS Windows installer cppcheck-2.9-x64-Setup.msi from the Windows desktop.
MSYS2 package mingw-w64-x86_64-cppcheck.

Below we execute the command pacman -S mingw-w64-x86_64-cppcheck and then check the cppcheck installation :

$ pacman -S mingw-w64-x86_64-cppcheck
resolving dependencies...
looking for conflicting packages...
 
Packages (1) mingw-w64-x86_64-cppcheck-2.10.2-1
 
Total Download Size:    3.43 MiB
Total Installed Size:  13.39 MiB
 
:: Proceed with installation? [Y/n] y
:: Retrieving packages...
 mingw-w64-x86_64-cppcheck-2.10.2-1-any    3.4 MiB   255 KiB/s 00:14 [#############################] 100%
(1/1) checking keys in keyring                                      [#############################] 100%
(1/1) checking package integrity                                    [#############################] 100%
(1/1) loading package files                                         [#############################] 100%
(1/1) checking for file conflicts                                   [#############################] 100%
(1/1) checking available disk space                                 [#############################] 100%
:: Processing package changes...
(1/1) installing mingw-w64-x86_64-cppcheck                          [#############################] 100%
Optional dependencies for mingw-w64-x86_64-cppcheck
    mingw-w64-x86_64-qt5: cppcheck-gui
    mingw-w64-x86_64-python-pygments: cppcheck-htmlreport
 
$ which cppcheck
/mingw64/bin/cppcheck
 
$ cppcheck --version
Cppcheck 2.10.2

[4] MSYS2 versus MinGW ↩

We give here three differences between MSYS64 and MingGW-w64:

Criteria	MSYS64	MingGW-w64
Installation size	4.74 GB	614 MB
Version/architecture	`gcc 13.2.0`	`gcc 8.1`
Update tool	`pacman -Syu` ⁽¹⁾	`mingw-get upgrade` ⁽²⁾

⁽¹⁾ pacman -Syu does nothing
⁽²⁾ Minimalist GNU for Windows

1. MSYS64 tools:

> c:\opt\msys64\usr\bin\pacman.exe -Syu
:: Synchronizing package databases...
[...]
:: Running post-transaction hooks...
(1/3) Compiling GSettings XML schema files...
(2/3) Updating icon theme caches...
(3/3) Updating the info directory file...
 
> where /r c:\opt\msys64 gcc.exe make.exe pacman.exe
c:\opt\msys64\mingw64\bin\gcc.exe
c:\opt\msys64\usr\bin\make.exe
c:\opt\msys64\usr\bin\pacman.exe
 
> c:\opt\msys64\mingw64\bin\gcc.exe --version | findstr gcc
gcc (Rev3, Built by MSYS2 project) 13.2.0
 
> c:\opt\msys64\usr\bin\make.exe --version | findstr Make
GNU Make 4.4

☛ Key "XXX" is unknown
One may encounter the MSYS error key "XXX" is unkown when running pacman -Syu from the Windows prompt. Simply run the command once from the MingW64 shell (command %MSYS_HOME%\mingw64.exe) to solve the issue.

> c:\opt\msys64\usr\bin\pacman.exe -Syu
error: msys: key "4A6129F4E4B84AE46ED7F635628F528CF3053E04" is unknown
:: Import PGP key 4A6129F4E4B84AE46ED7F635628F528CF3053E04? [Y/n] y
    error: key "4A6129F4E4B84AE46ED7F635628F528CF3053E04" could not be looked up remotely
:: Synchronizing package databases...
 mingw32                607.7 KiB  39.0 KiB/s 00:16   [###############################] 100%
 mingw32.sig            438.0   B  0.00   B/s 00:00   [###############################] 100%
 error: mingw32: key "4A6129F4E4B84AE46ED7F635628F528CF3053E04" is unknown
:: Import PGP key 4A6129F4E4B84AE46ED7F635628F528CF3053E04? [Y/n] y
    error: key "4A6129F4E4B84AE46ED7F635628F528CF3053E04" could not be looked up remotely
[..]

2. MinGW-w64 tools:

> where /r . gcc mingw-get mingw32-make
c:\opt\mingw-w64\mingw64\bin\gcc.exe
c:\opt\mingw-w64\mingw64\bin\mingw-get.exe
c:\opt\mingw-w64\mingw64\bin\mingw32-make.exe
 
> gcc --version | findstr gcc
gcc (x86_64-posix-seh-rev0, Built by MinGW-W64 project) 8.1.0
 
> mingw32-make --version | findstr Make
GNU Make 4.2.1

[5] Downloads ↩

In our case we downloaded the following installation files (see section 1):

cmake-3.27.7-windows-x86_x64.zip  ( 37 MB)
doxygen-1.9.8.windows.x64.bin.zip ( 22 MB)
PortableGit-2.42.0-64-bit.7z.exe  ( 41 MB)
LLVM-8.0.1-win64.exe              (131 MB)
LLVM-10.0.0-win64.exe             (150 MB)
LLVM-11.1.0-win64.exe             (172 MB)
LLVM-12.0.1-win64.exe             (182 MB)
LLVM-13.0.1-win64.exe             (228 MB)
LLVM-14.0.6-win64.exe             (263 MB)
LLVM-15.0.7-win64.exe             (263 MB)
llvm-8.0.1.src.tar.xz             ( 29 MB)
llvm-10.0.1.src.tar.xz            ( 31 MB)
llvm-11.1.0.src.tar.xz            ( 37 MB)
llvm-12.0.1.src.tar.xz            ( 41 MB)
llvm-13.0.1.src.tar.xz            ( 43 MB)
llvm-14.0.6.src.tar.xz            ( 47 MB)
llvm-15.0.7.src.tar.xz            ( 47 MB)
msys2-x86_64-20190524.exe         ( 86 MB)
ninja-win.zip                     (0.2 MB)
python-3.11.1-amd64.exe           ( 27 MB)
vs_2019_community.exe             (1.7 GB)

Microsoft does not provide an offline installer for VS 2019 but we can follow the following instructions to create a local installer (so called layout cache) for later (re-)installation.

mics/October 2023 ▲

michelou / llvm-examples