diff --git a/llvm/docs/GettingStartedVS.rst b/llvm/docs/GettingStartedVS.rst --- a/llvm/docs/GettingStartedVS.rst +++ b/llvm/docs/GettingStartedVS.rst @@ -2,6 +2,7 @@ Getting Started with the LLVM System using Microsoft Visual Studio ================================================================== + .. contents:: :local: @@ -9,8 +10,8 @@ Overview ======== Welcome to LLVM on Windows! This document only covers LLVM on Windows using -Visual Studio, not mingw or cygwin. In order to get started, you first need to -know some basic information. +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 @@ -24,11 +25,7 @@ machine code. LLVM fully supports the COFF object file format, which is compatible with all other existing Windows toolchains. -The last major part of LLVM, the execution Test Suite, does not run on Windows, -and this document does not discuss it. - -Additional information about the LLVM directory structure and tool chain -can be found on the main :doc:`GettingStarted` page. +There are more LLVM projects which this document does not discuss. Requirements @@ -40,63 +37,94 @@ Hardware -------- Any system that can adequately run Visual Studio 2017 is fine. The LLVM -source tree and object files, libraries and executables will consume -approximately 3GB. +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. + Software -------- -You will need Visual Studio 2017 or higher, with the latest Update installed. +You will need `Visual Studio `_ 2017 or +higher, 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. +generates the project files you will use to build with. CMake is bundled with +Visual Studio 2019 so seperate installation is not required. If you would like to run the LLVM tests you will need `Python -`_. Version 3.6 and newer are known to work. You will -need `GnuWin32 `_ tools, too. +`_. 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 to adjust installation options. -Do not install the LLVM directory tree into a path containing spaces (e.g. -``C:\Documents and Settings\...``) as the configure step will fail. +You will need `Git for Windows `_ with bash tools, too. +Git for Windows is also bundled with Visual Studio 2019. -To simplify the installation procedure, you can also use -`Chocolatey `_ as package manager. After the -`installation `_ of Chocolatey, run these -commands in an admin shell to install the required tools: -.. code-block:: bat +Getting Started +=============== +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: + +1. Download and install `Visual Studio `_. +2. In the Visual Studio installer, Workloads tab, select the + **Desktop development with C++** workload. Under Individual components tab, + select **Git for Windows**. +3. Complete the Visual Studio installation. +4. Download and install the latest `Python 3 release `_. +5. 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. +6. In the second install screen, select (again) **Install for all users** and + if you want to develop `lldb `_, selecting + **Download debug binaries** is useful. +7. Complete the Python installation. +8. 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. +9. In the terminal window, type the commands: - choco install -y ninja git cmake gnuwin python3 - pip3 install psutil + .. code-block:: bat -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. + c: + cd \ -Getting Started -=============== -Here's the short story for getting up and running quickly with LLVM: + You may install the llvm sources in other location than ``c:\llvm`` but do not + install into a path containing spaces (e.g. ``c:\Documents and Settings\...``) + as it will fail. -1. Read the documentation. -2. Seriously, read the documentation. -3. Remember that you were warned twice about reading the documentation. -4. Get the Source Code +10. Install psutil and obtain LLVM source code: + + .. code-block:: bat - * With the distributed files: + pip install psutil + git clone https://github.com/llvm/llvm-project.git llvm + + Instead of ``git clone`` you 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. - 1. ``cd `` - 2. ``gunzip --stdout llvm-VERSION.tar.gz | tar -xvf -`` - (*or use WinZip*) - 3. ``cd llvm`` +11. Finally, configure LLVM using CMake: - * With git access: + .. code-block:: bat - *Note:* some regression tests require Unix-style line ending (``\n``). + cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64 + exit - 1. ``cd `` - 2. ``git clone https://github.com/llvm/llvm-project.git llvm`` - 3. ``cd llvm`` + ``LLVM_ENABLE_PROJECTS`` specifies any additional LLVM projects you want to + build while ``LLVM_TARGETS_TO_BUILD`` selects the compiler targets. If + ``LLVM_TARGETS_TO_BUILD`` is omitted by default all targets are built + slowing compilation and using more disk space. + See the :doc:`LLVM CMake guide ` for detailed information about + how to configure the LLVM build. -5. Use `CMake `_ to generate up-to-date project files: + The ``cmake`` command 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 @@ -107,25 +135,6 @@ using LLVM. Another important option is ``LLVM_TARGETS_TO_BUILD``, which controls the LLVM target architectures that are included on the build. - * If CMake complains that it cannot find the compiler, make sure that - you have the Visual Studio C++ Tools installed, not just Visual Studio - itself (trying to create a C++ project in Visual Studio will generally - download the C++ tools if they haven't already been). - * Run cmake from a "x86/x64 Native Tools Command Prompt" so Visual C++ will - be on the PATH and its environment variables are set. Do **not** use - ``CMAKE_C_COMPILER`` and ``CMAKE_CXX_COMPILER`` for this purpose: - - .. code-block:: bat - - ********************************************************************** - ** Visual Studio 2019 Developer Command Prompt v16.11.1 - ** Copyright (c) 2021 Microsoft Corporation - ********************************************************************** - [vcvarsall.bat] Environment initialized for: 'x64' - c:\build> cmake ..\llvm\llvm -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64 - - * See the :doc:`LLVM CMake guide ` for detailed information about - how to configure the LLVM 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:Configuration`` command line option when using MSBuild. @@ -134,123 +143,92 @@ want to use the 64-bit toolset, pass the ``-Thost=x64`` flag when generating the Visual Studio solution. This requires CMake 3.8.0 or later. -6. Start Visual Studio - - * In the directory you created the project files will have an ``llvm.sln`` - file, just double-click on that to open Visual Studio. - -7. Build the LLVM Suite: - - * 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_BUILD`` project to build everything, or the ``INSTALL`` project, - which first builds the ``ALL_BUILD`` project, then installs the LLVM - headers, libs, and other useful things to the directory set by the - ``CMAKE_INSTALL_PREFIX`` setting 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. - -8. Test LLVM in Visual Studio: - - * If ``%PATH%`` does not contain GnuWin32, you may specify - ``LLVM_LIT_TOOLS_DIR`` on CMake for the path to GnuWin32. - * You can run LLVM tests by merely building the project "check-all". The test - results will be shown in the VS output window. - -9. Test LLVM on the command line: - - * The LLVM tests can be run by changing directory to the llvm source - directory and running: - - .. code-block:: bat - - c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test - - This example assumes that Python is in your PATH variable, you - have built a Release version of llvm with a standard out of - line build. You should not see any unexpected failures, but will - see many unsupported tests and expected failures. - - A specific test or test directory can be run with: - - .. code-block:: bat - - c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util - - -An Example Using the LLVM Tool Chain -==================================== - -1. First, create a simple C file, name it '``hello.c``': - - .. code-block:: c +12. Start Visual Studio and select configuration: + + In the directory you created the project files will have an ``llvm.sln`` + file, 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 librares or source files you actually need to debug. + +13. 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 ==========`` + +Alternatives to manual installation +=================================== +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: - #include - int main() { - printf("hello world\n"); - return 0; - } - -2. Next, compile the C file into an LLVM bitcode file: - - .. code-block:: bat - - C:\..> clang -c hello.c -emit-llvm -o hello.bc - - This will create the result file ``hello.bc`` which is the LLVM bitcode - that corresponds the compiled program and the library facilities that - it required. You can execute this file directly using ``lli`` tool, - compile it to native assembly with the ``llc``, optimize or analyze it - further with the ``opt`` tool, etc. - - Alternatively you can directly output an executable with clang with: - - .. code-block:: bat - - C:\..> clang hello.c -o hello.exe - - The ``-o hello.exe`` is required because clang currently outputs ``a.out`` - when neither ``-o`` nor ``-c`` are given. - -3. Run the program using the just-in-time compiler: - - .. code-block:: bat - - C:\..> lli hello.bc - -4. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code: - - .. code-block:: bat - - C:\..> llvm-dis < hello.bc | more +.. code-block:: bat -5. Compile the program to object code using the LLC code generator: + choco install -y git cmake python3 + pip3 install psutil - .. code-block:: bat +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. - C:\..> llc -filetype=obj hello.bc +Next steps +========== +1. Read the documentation. +2. Seriously, read the documentation. +3. Remember that you were warned twice about reading the documentation. -6. Link to binary using Microsoft link: +Test LLVM on the command line: +------------------------------ +The LLVM tests can be run by changing directory to the llvm source +directory and running: - .. code-block:: bat +.. code-block:: bat - C:\..> link hello.obj -defaultlib:libcmt + c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test -7. Execute the native code program: +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. - .. code-block:: bat +A specific test or test directory can be run with: - C:\..> hello.exe +.. code-block:: bat + c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util -Common Problems -=============== -If you are having problems building or using LLVM, or if you have any other -general questions about LLVM, please consult the :doc:`Frequently Asked Questions -` page. +Build the LLVM Suite: +--------------------- +* 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_BUILD`` project to build everything, or the ``INSTALL`` project, + which first builds the ``ALL_BUILD`` project, then installs the LLVM + headers, libs, and other useful things to the directory set by the + ``CMAKE_INSTALL_PREFIX`` setting 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. Links @@ -262,4 +240,8 @@ * `LLVM homepage `_ * `LLVM doxygen tree `_ - +* Additional information about the LLVM directory structure and tool chain + can be found on the main :doc:`GettingStarted` page. +* If you are having problems building or using LLVM, or if you have any other + general questions about LLVM, please consult the + :doc:`Frequently Asked Questions ` page.