[llvm] 1958575 - [docs] Update Getting Started with Visual Studio guide
Yaron Keren via llvm-commits
llvm-commits at lists.llvm.org
Thu Aug 26 11:21:42 PDT 2021
Author: Yaron Keren
Date: 2021-08-26T21:21:36+03:00
New Revision: 195857585908c23ca22b0e12cc86bc64c8570c78
URL: https://github.com/llvm/llvm-project/commit/195857585908c23ca22b0e12cc86bc64c8570c78
DIFF: https://github.com/llvm/llvm-project/commit/195857585908c23ca22b0e12cc86bc64c8570c78.diff
LOG: [docs] Update Getting Started with Visual Studio guide
Update this document for 2021.
Reviewed By: aaron.ballman, kuhnel, amccarth
Differential Revision: https://reviews.llvm.org/D108513
Added:
Modified:
llvm/docs/GettingStartedVS.rst
Removed:
################################################################################
diff --git a/llvm/docs/GettingStartedVS.rst b/llvm/docs/GettingStartedVS.rst
index 8050187e49ba6..56f0df85db591 100644
--- 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 @@ Getting Started with the LLVM System using Microsoft Visual Studio
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
diff erent 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 @@ bitcode. Clang typically uses LLVM libraries to optimize the bitcode and emit
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 @@ and software you will need.
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 <https://visualstudio.microsoft.com/>`_ 2017 or
+higher, with the latest Update installed. Visual Studio Community Edition
+suffices.
You will also need the `CMake <http://www.cmake.org/>`_ 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
-<http://www.python.org/>`_. Version 3.6 and newer are known to work. You will
-need `GnuWin32 <http://gnuwin32.sourceforge.net/>`_ tools, too.
+<http://www.python.org/>`_. 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 <http://www.python.org/>`_. 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 <https://git-scm.com/>`_ with bash tools, too.
+Git for Windows is also bundled with Visual Studio 2019.
-To simplify the installation procedure, you can also use
-`Chocolatey <https://chocolatey.org/>`_ as package manager. After the
-`installation <https://chocolatey.org/install>`_ 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 <https://visualstudio.microsoft.com/>`_.
+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 <http://www.python.org/>`_.
+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 <https://lldb.llvm.org/>`_, 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 <https://github.com/llvm/llvm-zorg/blob/main/buildbot/google/docker/windows-base-vscode2019/Dockerfile>`_
-with the entire build tool chain. This can be used to test the build with a
-tool chain
diff erent 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 <https://github.com/llvm/llvm-project/releases>`_.
+ 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 <where-you-want-llvm-to-live>``
- 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 <where-you-want-llvm-to-live>``
- 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 <CMake>` for detailed information about
+ how to configure the LLVM build.
-5. Use `CMake <http://www.cmake.org/>`_ 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 <http://www.cmake.org/>`_ 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 @@ Here's the short story for getting up and running quickly with LLVM:
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 <CMake>` 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 @@ Here's the short story for getting up and running quickly with LLVM:
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 <https://chocolatey.org/>`_ as package manager.
+After the `installation <https://chocolatey.org/install>`_ of Chocolatey,
+run these commands in an admin shell to install the required tools:
- #include <stdio.h>
- 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 <https://github.com/llvm/llvm-zorg/blob/main/buildbot/google/docker/windows-base-vscode2019/Dockerfile>`_
+with the entire build tool chain. This can be used to test the build with a
+tool chain
diff erent 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
-<FAQ>` 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 @@ write something up!). For more information about LLVM, check out:
* `LLVM homepage <https://llvm.org/>`_
* `LLVM doxygen tree <https://llvm.org/doxygen/>`_
-
+* 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 <FAQ>` page.
More information about the llvm-commits
mailing list