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,8 +38,10 @@ 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 -------- @@ -55,81 +55,68 @@ 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 -`its web site `_. We recommend the later since it +the `Python web site `_. We recommend the later since it allows you to to adjust installation options. You will need `Git for Windows `_ with bash tools, too. Git for Windows is also bundled with Visual Studio 2019. -If you 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 - - choco install -y ninja git cmake gnuwin 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. Getting Started =============== Here's the short story for getting up and running quickly with LLVM. -These instruction were tested on Visual Studio 2019 and Python 3.9.6: +These instruction were tested with Visual Studio 2019 and Python 3.9.6: -1. Read the documentation. -2. Seriously, read the documentation. -3. Remember that you were warned twice about reading the documentation. -4. Download and install `Visual Studio `_. -5. In the Visual Studio installer, workloads tab, select the +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**. -6. Complete the Visual Studio installation. -7. Download and install `Python `_. -8. In the first install screen, select both **Install launcher for all users** - and **Add Python to the PATH**. This will make allow us to install psutil for - all users required by the regression tests. -9. In the second install screen, select (again) **Install for all users** and +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. -10. Complete the Python installation. -11. Run as administrator a "Developer Command Prompt for VS 2019". -12. In the terminal window, type the commands: +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: -.. code-block:: bat + .. code-block:: bat - c: - cd \ + c: + cd \ -you may install llvm in other location than c:\ but do not install into a path -containing spaces (e.g.``C:\Documents and Settings\...``) as it will fail. + 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. -13. Install psutil and obtain LLVM source code: -.. code-block:: bat +10. Install psutil and obtain LLVM source code: + + .. code-block:: bat - pip install psutil - git clone https://github.com/llvm/llvm-project.git llvm + pip install psutil + git clone https://github.com/llvm/llvm-project.git llvm -As an alternative to ``git clone`` step you may download a compressed source -distribution from the `releases page `_ -and unpack it: - - 1. ``cd `` - 2. ``gunzip --stdout llvm-VERSION.tar.gz | tar -xvf -`` - (*or use WinZip*) + 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. -14. Finally, configure LLVM: -.. code-block:: bat +11. Finally, configure LLVM using CMake: - cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64 - exit + .. code-block:: bat -The cmake command line is bundled with Visual Studio but its GUI is not avaialble. -You may install `CMake `_ to generate up-to-date project files -or provide paramates from the command line: + cmake -S llvm\llvm -B build -DLLVM_ENABLE_PROJECTS=clang -DLLVM_TARGETS_TO_BUILD=X86 -Thost=x64 + exit + + 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 @@ -140,10 +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). * 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 @@ -154,37 +137,24 @@ 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. -15. 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 later change compiler - flags for a specific library to debug it while the rest of LLVM is still + 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. -16. 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. - -17. Test LLVM in Visual Studio: +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 working LLVM development environment. You should not see any - unexpected failures, but will see many unsupported tests and expected - failures: + have verified a working LLVM development environment! + + You should not see any unexpected failures, but will see many unsupported + tests and expected failures: :: @@ -195,29 +165,73 @@ 114> Expectedly Failed: 93 ========== Build: 114 succeeded, 0 failed, 321 up-to-date, 0 skipped ==========`` -18. Test LLVM on the command line: +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: - The LLVM tests can be run by changing directory to the llvm source - directory and running: +.. code-block:: bat - .. code-block:: bat + choco install -y ninja git cmake gnuwin python3 + pip3 install psutil - c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test +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. - 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. +Next steps +========== +1. Read the documentation. +2. Seriously, read the documentation. +3. Remember that you were warned twice about reading the documentation. - A specific test or test directory can be run with: +Learn more about LLVM +--------------------- +Additional information about the LLVM directory structure and tool chain +can be found on the main :doc:`GettingStarted` page. - .. code-block:: bat +Test LLVM on the command line: +------------------------------ - c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util +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 -An Example Using the LLVM Tool Chain -==================================== +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: + +.. code-block:: bat + + c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test\Transforms\Util + +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. + + +Compile an example +------------------ 1. First, create a simple C file, name it '``hello.c``': @@ -233,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 @@ -245,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