diff --git a/llvm/docs/GettingStartedVS.rst b/llvm/docs/GettingStartedVS.rst --- a/llvm/docs/GettingStartedVS.rst +++ b/llvm/docs/GettingStartedVS.rst @@ -10,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 @@ -28,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 ============ @@ -41,7 +38,7 @@ Hardware -------- Any system that can adequately run Visual Studio 2017 is fine. The LLVM -source tree including he git index consumes 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. @@ -64,70 +61,53 @@ You will need `Git for Windows `_ with bash tools, too. Git for Windows is also bundled with Visual Studio 2019. -Alternatives to manual installation ------------------------------------ -Instead of the steps below, 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 - - 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 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 the latest `Python 3 release `_. -8. In the first install screen, select both **Install launcher for all users** - and **Add Python to the PATH**. This will make allow installing psutil for - all users for 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 under ``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: +10. Install psutil and obtain LLVM source code: .. code-block:: bat pip install psutil git clone https://github.com/llvm/llvm-project.git llvm - As an alternative to ``git clone`` you may download a compressed source - distribution from the `releases page `_. + 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 using CMake: +11. Finally, configure LLVM using CMake: .. code-block:: bat @@ -157,7 +137,7 @@ 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 and select configuration: +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 @@ -167,13 +147,14 @@ flags for a specific source file to debug it while the rest of LLVM is still compiled in **Release** configuration. -16. 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: :: @@ -184,43 +165,73 @@ 114> Expectedly Failed: 93 ========== Build: 114 succeeded, 0 failed, 321 up-to-date, 0 skipped ==========`` -17. 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: + +.. code-block:: bat - The LLVM tests can be run by changing directory to the llvm source - directory and running: + 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:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test +Next steps +========== +1. Read the documentation. +2. Seriously, read the documentation. +3. Remember that you were warned twice about reading the documentation. + +Learn more about LLVM +--------------------- +Additional information about the LLVM directory structure and tool chain +can be found on the main :doc:`GettingStarted` page. - 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. +Test LLVM on the command line: +------------------------------ - A specific test or test directory can be run with: +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\Transforms\Util + c:\llvm> python ..\build\Release\bin\llvm-lit.py llvm\test -18. Build the LLVM Suite: +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. - * 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. +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: +--------------------- -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``': @@ -248,10 +259,7 @@ .. 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: @@ -263,7 +271,7 @@ .. 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: