[llvm] [docs][CMake] Add CMakePreset, improve VS documentation (PR #84760)
Tobias Hieta via llvm-commits
llvm-commits at lists.llvm.org
Tue Mar 12 08:22:41 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/4] [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/4] 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:
>From c0e11a1c6c56160ae9c5b66e0c7e54468edf46a8 Mon Sep 17 00:00:00 2001
From: Tobias Hieta <tobias.hieta at ubisoft.com>
Date: Tue, 12 Mar 2024 16:21:49 +0100
Subject: [PATCH 3/4] Further clarifications
---
.vs/CMakeWorkspaceSettings.json | 6 +++---
llvm/docs/GettingStartedVS.rst | 13 +++++++++----
2 files changed, 12 insertions(+), 7 deletions(-)
diff --git a/.vs/CMakeWorkspaceSettings.json b/.vs/CMakeWorkspaceSettings.json
index 28a1592305e445..989311077b2416 100644
--- a/.vs/CMakeWorkspaceSettings.json
+++ b/.vs/CMakeWorkspaceSettings.json
@@ -1,4 +1,4 @@
{
- "enableCMake": true,
- "sourceDirectory": "llvm"
-}
+ "sourceDirectory": "llvm",
+ "enableCMake": false
+}
\ No newline at end of file
diff --git a/llvm/docs/GettingStartedVS.rst b/llvm/docs/GettingStartedVS.rst
index dca6e56d628dfa..77f629d7a11b0d 100644
--- a/llvm/docs/GettingStartedVS.rst
+++ b/llvm/docs/GettingStartedVS.rst
@@ -63,6 +63,7 @@ allows you to adjust installation options.
You will need `Git for Windows <https://git-scm.com/>`_ with bash tools, too.
Git for Windows is also bundled with Visual Studio 2019.
+.. _getting_started:
Getting Started
===============
@@ -132,13 +133,15 @@ These instruction were tested with Visual Studio 2019 and Python 3.9.6:
Visual Studio native CMake support
==================================
+Before you can build LLVM with Visual Studio you need to follow the step
+outlined in :ref:`Getting Started<getting_started>`.
+
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
+If you want to generate a Visual Studio Solution, 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
@@ -167,8 +170,10 @@ documentation
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:
+Before you can generate the Visual Studio solution you need to follow the step
+outlined in :ref:`Getting Started<getting_started>`.
+
+1. You can generate a Visual Studio Solution by running the following CMake command:
.. code-block:: bat
>From dbe9f8a41d6eb9646e76bf5feafe8cce8e5bc7b0 Mon Sep 17 00:00:00 2001
From: Tobias Hieta <tobias at hieta.se>
Date: Tue, 12 Mar 2024 16:22:34 +0100
Subject: [PATCH 4/4] Update llvm/CMakePresets.json
Co-authored-by: James Henderson <46713263+jh7370 at users.noreply.github.com>
---
llvm/CMakePresets.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/CMakePresets.json b/llvm/CMakePresets.json
index 9db284143df4a1..3eaa9f7b1fe4b4 100644
--- a/llvm/CMakePresets.json
+++ b/llvm/CMakePresets.json
@@ -1,7 +1,7 @@
/*
This is the default presets for LLVM, if you want to add your own
- custom one, create a CMakeUserPreset.json instead.
+ custom one, create a CMakeUserPresets.json instead.
*/
{
More information about the llvm-commits
mailing list