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 @@ -27,9 +28,6 @@ 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. - Requirements ============ @@ -40,63 +38,85 @@ 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 is 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. 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 later 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: - * With the distributed files: + .. code-block:: bat - 1. ``cd `` - 2. ``gunzip --stdout llvm-VERSION.tar.gz | tar -xvf -`` - (*or use WinZip*) - 3. ``cd llvm`` + 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. - * With git access: +11. Finally, configure LLVM using CMake: - *Note:* some regression tests require Unix-style line ending (``\n``). + .. code-block:: bat - 1. ``cd `` - 2. ``git clone https://github.com/llvm/llvm-project.git llvm`` - 3. ``cd llvm`` + cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64 + exit -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,23 +127,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 @@ -134,55 +137,101 @@ 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 +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. It is possible to change compiler + flags for a specific source file to debug it while the rest of LLVM is still + compiled in **Release** configuration. + +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: - * In the directory you created the project files will have an ``llvm.sln`` - file, just double-click on that to open Visual Studio. +.. code-block:: bat -7. Build the LLVM Suite: + choco install -y ninja git cmake gnuwin python3 + pip3 install psutil - * 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. +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. -8. Test LLVM in Visual Studio: +Next steps +========== +1. Read the documentation. +2. Seriously, read the documentation. +3. Remember that you were warned twice about reading the documentation. - * 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. +Learn more about LLVM +--------------------- +Additional information about the LLVM directory structure and tool chain +can be found on the main :doc:`GettingStarted` page. -9. Test LLVM on the command line: +Test LLVM on the command line: +------------------------------ - * The LLVM tests can be run by changing directory to the llvm source - directory and running: +The LLVM tests can be run by changing directory to the llvm source +directory and running: - .. code-block:: bat +.. code-block:: bat - c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test + 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. +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: +A specific test or test directory can be run with: - .. code-block:: bat +.. code-block:: bat - c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util + c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util +Build the LLVM Suite: +--------------------- -An Example Using the LLVM Tool Chain -==================================== +* 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. + + +Compile an example +------------------ 1. First, create a simple C file, name it '``hello.c``': @@ -198,7 +247,7 @@ .. code-block:: bat - C:\..> clang -c hello.c -emit-llvm -o hello.bc + 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 @@ -210,40 +259,37 @@ .. 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. + c:\..> clang hello.c 3. Run the program using the just-in-time compiler: .. code-block:: bat - C:\..> lli hello.bc + 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 + c:\..> llvm-dis < hello.bc 5. Compile the program to object code using the LLC code generator: .. code-block:: bat - C:\..> llc -filetype=obj hello.bc + c:\..> llc -filetype=obj hello.bc 6. Link to binary using Microsoft link: .. code-block:: bat - C:\..> link hello.obj -defaultlib:libcmt + c:\..> link hello.obj -defaultlib:libcmt 7. Execute the native code program: .. code-block:: bat - C:\..> hello.exe + c:\..> hello.exe Common Problems @@ -262,4 +308,3 @@ * `LLVM homepage `_ * `LLVM doxygen tree `_ -