[llvm] [docs][CMake] Add CMakePreset, improve VS documentation (PR #84760)
Tobias Hieta via llvm-commits
llvm-commits at lists.llvm.org
Tue Mar 12 05:36:07 PDT 2024
https://github.com/tru updated https://github.com/llvm/llvm-project/pull/84760
>From 0314d230998678b5087474e52fe918a7014946f9 Mon Sep 17 00:00:00 2001
From: Tobias Hieta <tobias.hieta at ubisoft.com>
Date: Mon, 11 Mar 2024 14:52:21 +0100
Subject: [PATCH 1/2] [docs][CMake] Add CMakePreset, improve VS documentation
This commit adds the following:
* .vs/CMakeWorkspaceSettings.json - This file make Visual Studio find
the llvm source directory out of the box with no configuration. And
enables CMake for this project.
* Adds llvm/CMakePresets.json - Some sane defaults to make VS be able
to configure and build LLVM/Clang without any changes. At this time
it only adds Windows targets, but can be expanded for other platforms.
* Update the documentation for Getting started on Windows. This points
out that the Visual Studio native CMake configuration is a better
choice for most people.
---
.vs/CMakeWorkspaceSettings.json | 4 ++
llvm/CMakePresets.json | 91 +++++++++++++++++++++++++++++++++
llvm/docs/GettingStartedVS.rst | 49 +++++++++++++++---
3 files changed, 138 insertions(+), 6 deletions(-)
create mode 100644 .vs/CMakeWorkspaceSettings.json
create mode 100644 llvm/CMakePresets.json
diff --git a/.vs/CMakeWorkspaceSettings.json b/.vs/CMakeWorkspaceSettings.json
new file mode 100644
index 00000000000000..28a1592305e445
--- /dev/null
+++ b/.vs/CMakeWorkspaceSettings.json
@@ -0,0 +1,4 @@
+{
+ "enableCMake": true,
+ "sourceDirectory": "llvm"
+}
diff --git a/llvm/CMakePresets.json b/llvm/CMakePresets.json
new file mode 100644
index 00000000000000..72d55d1b4431a3
--- /dev/null
+++ b/llvm/CMakePresets.json
@@ -0,0 +1,91 @@
+
+/*
+ This is the default presets for LLVM, if you want to add your own
+ custom one, create a CMakeUserPreset.json instead.
+*/
+
+{
+ "version": 2,
+ "cmakeMinimumRequired": {
+ "major": 3,
+ "minor": 20,
+ "patch": 0
+ },
+ "configurePresets": [
+ {
+ "name": "default_win",
+ "hidden": true,
+ "generator": "Ninja",
+ "binaryDir": "${sourceParentDir}/out/${presetName}",
+ "cacheVariables": {
+ /* Most of the users would like to have these projects enabled */
+ "LLVM_ENABLE_PROJECTS": "clang;lld;clang-tools-extra"
+ }
+ },
+ {
+ "name": "Debug_Win_x64_msvc",
+ "inherits": "default_win",
+ "displayName": "Debug Win x64 (MSVC)",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Debug",
+ "LLVM_OPTIMIZED_TABLEGEN": "ON"
+ }
+ },
+ {
+ "name": "Release_Win_x64_msvc",
+ "inherits": "default_win",
+ "displayName": "Release Win x64 (MSVC)",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Release",
+ "LLVM_ENABLE_PDB": "ON",
+ "LLVM_ENABLE_ASSERTIONS": "ON"
+ }
+ },
+ {
+ "name": "Debug_Win_x64_clang",
+ "inherits": "default_win",
+ "displayName": "Debug Win x64 (Clang)",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Debug",
+ "CMAKE_CXX_COMPILER": "clang-cl",
+ "CMAKE_C_COMPILER": "clang-cl",
+ "LLVM_OPTIMIZED_TABLEGEN": "ON"
+ }
+ },
+ {
+ "name": "Release_Win_x64_clang",
+ "inherits": "default_win",
+ "displayName": "Release Win x64 (Clang)",
+ "cacheVariables": {
+ "CMAKE_BUILD_TYPE": "Release",
+ "CMAKE_CXX_COMPILER": "clang-cl",
+ "CMAKE_C_COMPILER": "clang-cl",
+ "LLVM_ENABLE_PDB": "ON",
+ "LLVM_ENABLE_ASSERTIONS": "ON"
+ }
+ }
+ ],
+ "buildPresets": [
+ {
+ "name": "Debug_Win_x64_msvc",
+ "configurePreset": "Debug_Win_x64_msvc",
+ "inheritConfigureEnvironment": true
+ },
+ {
+ "name": "Release_Win_x64_msvc",
+ "configurePreset": "Release_Win_x64_msvc",
+ "inheritConfigureEnvironment": true
+ },
+ {
+ "name": "Debug_Win_x64_clang",
+ "configurePreset": "Debug_Win_x64_clang",
+ "inheritConfigureEnvironment": true
+ },
+ {
+ "name": "Release_Win_x64_clang",
+ "configurePreset": "Release_Win_x64_clang",
+ "inheritConfigureEnvironment": true
+ }
+
+ ]
+}
diff --git a/llvm/docs/GettingStartedVS.rst b/llvm/docs/GettingStartedVS.rst
index a1eb88dccc9e5c..283f22cc5799bc 100644
--- a/llvm/docs/GettingStartedVS.rst
+++ b/llvm/docs/GettingStartedVS.rst
@@ -36,7 +36,7 @@ and software you will need.
Hardware
--------
-Any system that can adequately run Visual Studio 2019 is fine. The LLVM
+Any system that can adequately run Visual Studio 2019 or 2022 is fine. The LLVM
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
@@ -47,7 +47,7 @@ Software
--------
You will need `Visual Studio <https://visualstudio.microsoft.com/>`_ 2019 or
later, with the latest Update installed. Visual Studio Community Edition
-suffices.
+suffices. We recommend using Visual Studio 2022.
You will also need the `CMake <http://www.cmake.org/>`_ build system since it
generates the project files you will use to build with. CMake is bundled with
@@ -72,7 +72,8 @@ 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**.
+ select **Git for Windows**. You might want to install **C++ Clang compiler for Windows**
+ as well, since this will allow you to build LLVM with Clang.
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**
@@ -119,7 +120,43 @@ These instruction were tested with Visual Studio 2019 and Python 3.9.6:
Select the last link: ``Source code (zip)`` and unpack the downloaded file using
Windows Explorer built-in zip support or any other unzip tool.
-12. Finally, configure LLVM using CMake:
+12. Open the LLVM folder in Visual Studio or configure LLVM with CMake.
+
+ Recently Visual Studio has added native support for CMake which will run and
+ manage the CMake settings for you instead of you manually having to generate
+ a Visual Studio Soluion. This is the recommended way to build and debug LLVM
+ in Visual Studio 2022.
+
+ If you want to generate a Visual Studio Solution for older versions of Visual
+ Studio or becasue that is a workflow that suites you better please refer to the
+ chapter below on :ref:`generating Visual Studio Solution<gen_vs_cmake>`.
+
+ To use the native CMake support, launch `Visual Studio 2022` and select the
+ option `Open a Local Folder` and open the root `llvm-project` folder. This
+ will automatically launch CMake (have some patience, it can be a bit slow)
+ and populate the interface.
+
+ LLVM ships with a default `CMakePresets.json` that is supposed to make it easy
+ to get started, but usually you need to modify the setings used, the best way
+ to do this is to create a `CMakeUserPresets.json` in the `llvm` subfolder and
+ add your own configuration there. For more information about the Preset system
+ see `Microsoft's documentation <https://learn.microsoft.com/en-us/cpp/build/cmake-presets-json-reference>`_.
+
+ The default CMakePreset comes with MSVC and Clang targets. In order to use the
+ Clang target you need to have the **C++ Clang compiler for Windows** component
+ of Visual Studio installed.
+
+ In order to debug Clang and other binaries within Visual Studio, see `Microsoft's
+ documentation. <https://learn.microsoft.com/en-us/cpp/build/configure-cmake-debugging-sessions>`_.
+
+
+.. _gen_vs_cmake:
+
+Generate Visual Studio Solution with CMake
+==========================================
+
+1. After following the steps above you can generate a Visual Studio Solution by
+ running the following CMake command:
.. code-block:: bat
@@ -154,7 +191,7 @@ These instruction were tested with Visual Studio 2019 and Python 3.9.6:
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.
-13. Start Visual Studio and select configuration:
+2. 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
@@ -166,7 +203,7 @@ These instruction were tested with Visual Studio 2019 and Python 3.9.6:
compiler flags, disabling optimization and enabling debug information, only
for specific libraries or source files you actually need to debug.
-14. Test LLVM in Visual Studio:
+3. 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
>From 7cea65bc34a5f8e7c0fcae29c1e00a083f6f0a4a Mon Sep 17 00:00:00 2001
From: Tobias Hieta <tobias.hieta at ubisoft.com>
Date: Tue, 12 Mar 2024 13:35:37 +0100
Subject: [PATCH 2/2] Review feedback
---
llvm/CMakePresets.json | 4 +-
llvm/docs/GettingStartedVS.rst | 68 ++++++++++++++++++++--------------
2 files changed, 41 insertions(+), 31 deletions(-)
diff --git a/llvm/CMakePresets.json b/llvm/CMakePresets.json
index 72d55d1b4431a3..9db284143df4a1 100644
--- a/llvm/CMakePresets.json
+++ b/llvm/CMakePresets.json
@@ -18,7 +18,6 @@
"generator": "Ninja",
"binaryDir": "${sourceParentDir}/out/${presetName}",
"cacheVariables": {
- /* Most of the users would like to have these projects enabled */
"LLVM_ENABLE_PROJECTS": "clang;lld;clang-tools-extra"
}
},
@@ -60,8 +59,7 @@
"CMAKE_BUILD_TYPE": "Release",
"CMAKE_CXX_COMPILER": "clang-cl",
"CMAKE_C_COMPILER": "clang-cl",
- "LLVM_ENABLE_PDB": "ON",
- "LLVM_ENABLE_ASSERTIONS": "ON"
+ "LLVM_ENABLE_PDB": "ON"
}
}
],
diff --git a/llvm/docs/GettingStartedVS.rst b/llvm/docs/GettingStartedVS.rst
index 283f22cc5799bc..dca6e56d628dfa 100644
--- a/llvm/docs/GettingStartedVS.rst
+++ b/llvm/docs/GettingStartedVS.rst
@@ -120,34 +120,46 @@ These instruction were tested with Visual Studio 2019 and Python 3.9.6:
Select the last link: ``Source code (zip)`` and unpack the downloaded file using
Windows Explorer built-in zip support or any other unzip tool.
-12. Open the LLVM folder in Visual Studio or configure LLVM with CMake.
-
- Recently Visual Studio has added native support for CMake which will run and
- manage the CMake settings for you instead of you manually having to generate
- a Visual Studio Soluion. This is the recommended way to build and debug LLVM
- in Visual Studio 2022.
-
- If you want to generate a Visual Studio Solution for older versions of Visual
- Studio or becasue that is a workflow that suites you better please refer to the
- chapter below on :ref:`generating Visual Studio Solution<gen_vs_cmake>`.
-
- To use the native CMake support, launch `Visual Studio 2022` and select the
- option `Open a Local Folder` and open the root `llvm-project` folder. This
- will automatically launch CMake (have some patience, it can be a bit slow)
- and populate the interface.
-
- LLVM ships with a default `CMakePresets.json` that is supposed to make it easy
- to get started, but usually you need to modify the setings used, the best way
- to do this is to create a `CMakeUserPresets.json` in the `llvm` subfolder and
- add your own configuration there. For more information about the Preset system
- see `Microsoft's documentation <https://learn.microsoft.com/en-us/cpp/build/cmake-presets-json-reference>`_.
-
- The default CMakePreset comes with MSVC and Clang targets. In order to use the
- Clang target you need to have the **C++ Clang compiler for Windows** component
- of Visual Studio installed.
-
- In order to debug Clang and other binaries within Visual Studio, see `Microsoft's
- documentation. <https://learn.microsoft.com/en-us/cpp/build/configure-cmake-debugging-sessions>`_.
+12. Open the LLVM folder in Visual Studio or generate a solution via CMake.
+
+ At this point you can select if you want to use the
+ :ref:`native support for CMake<vs_native_cmake>` in Visual Studio or
+ :ref:`generate Visual Studio<gen_vs_cmake>` solution file from CMake.
+ Both integrations are supported in the LLVM project.
+
+.. _vs_native_cmake:
+
+Visual Studio native CMake support
+==================================
+
+Support for native CMake integration was added in Visual Studio 2019, but it has
+been made more robust in 2022. If you are using Visual Studio before 2022, it's
+recommended to generate a Visual Studio solution from CMake instead of using the
+native CMake integration.
+
+If you want to generate a Visual Studio Solution for older versions of Visual
+Studio or because that is a workflow that suits you better, please refer to the
+chapter below on :ref:generating Visual Studio Solution<gen_vs_cmake>.
+
+To use the native CMake support, launch Visual Studio 2022 and select the option
+Open a Local Folder and open the root llvm-project folder. This will
+automatically launch CMake (have some patience, it can be a bit slow) and
+populate the interface.
+
+LLVM ships with a default CMakePresets.json that is supposed to make it easy to
+get started, but usually you need to modify the settings used. The best way to
+do this is to create a CMakeUserPresets.json in the llvm subfolder and add your
+configuration there. For more information about the Preset system, see
+Microsoft's documentation
+<https://learn.microsoft.com/en-us/cpp/build/cmake-presets-json-reference>_.
+
+The default CMakePreset comes with MSVC and Clang targets. To use the Clang
+target, you need to have the C++ Clang compiler for Windows component of Visual
+Studio installed.
+
+To debug Clang and other binaries within Visual Studio, see Microsoft's
+documentation
+<https://learn.microsoft.com/en-us/cpp/build/configure-cmake-debugging-sessions>_.
.. _gen_vs_cmake:
More information about the llvm-commits
mailing list