extend user CMakePresets (#2985)

* extend user CMakePresets * minor changes * minor changes * minor changes --------- Co-authored-by: czoido <mrgalleta@gmail.com>
conan-io · Feb 17, 2023 · d05a61f · d05a61f
1 parent cf7e0f1
commit d05a61f
Show file tree

Hide file tree

Showing 7 changed files with 172 additions and 36 deletions.
diff --git a/examples/tools/cmake/cmake.rst b/examples/tools/cmake/cmake.rst
@@ -9,4 +9,5 @@ tools.cmake
    :maxdepth: 2
 
 
-   cmake_toolchain/build_project_cmake_presets
+   cmake_toolchain/build_project_cmake_presets
+   cmake_toolchain/extend_own_cmake_presets
diff --git a/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst
@@ -50,12 +50,12 @@ If you are using a multi-configuration generator:
 
 .. code:: bash
 
-    $ cmake --preset default
-    $ cmake --build --preset debug
+    $ cmake --preset conan-default
+    $ cmake --build --preset conan-debug
     $ build\Debug\foo.exe
     foo/1.0: Hello World Release!
 
-    $ cmake --build --preset release
+    $ cmake --build --preset conan-release
     $ build\Release\foo.exe
     foo/1.0: Hello World Release!
 
@@ -64,14 +64,14 @@ If you are using a single-configuration generator:
 
 .. code:: bash
 
-    $ cmake --preset debug
-    $ cmake --build --preset debug
+    $ cmake --preset conan-debug
+    $ cmake --build --preset conan-debug
     $ ./build/Debug/foo
     foo/1.0: Hello World Debug!
 
 
-    $ cmake --preset release
-    $ cmake --build --preset release
+    $ cmake --preset conan-release
+    $ cmake --build --preset conan-release
     $ ./build/Release/foo
     foo/1.0: Hello World Release!
 

diff --git a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst
@@ -0,0 +1,119 @@
+.. _examples-tools-cmake-toolchain-build-project-extend-presets:
+
+CMakeToolchain: Extending your CMakePresets with Conan generated ones
+=====================================================================
+
+In this example we are going to see how to extend your own CMakePresets to include Conan
+generated ones.
+
+.. include:: ../../../../tutorial/cmake_presets_note.rst
+
+Please, first of all, clone the sources to recreate this project. You can find them in the
+`examples2.0 repository <https://github.com/conan-io/examples2>`_ in GitHub:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/conan-io/examples2.git
+    $ cd examples2/examples/tools/cmake/cmake_toolchain/local_flow_cmake_presets
+
+Please open the `conanfile.py` and check how it sets ``tc.user_presets_path =
+'ConanPresets.json'``. By modifying this attribute of `CMakeToolchain`, you can change the
+default filename of the generated preset.
+
+.. code:: python
+
+    def generate(self):
+        tc = CMakeToolchain(self)
+        tc.user_presets_path = 'ConanPresets.json'
+        tc.generate()
+        ...
+
+Now you can provide your own ``CMakePresets.json``, besides the ``CMakeLists.txt``:
+
+.. code-block:: json
+    :caption: CMakePresets.json
+
+    {
+    "version": 4,
+    "include": ["./ConanPresets.json"],
+    "configurePresets": [
+        {
+            "name": "default",
+            "displayName": "multi config",
+            "inherits": "conan-default"
+        },
+        {
+            "name": "release",
+            "displayName": "release single config",
+            "inherits": "conan-release"
+        },
+        {
+            "name": "debug",
+            "displayName": "debug single config",
+            "inherits": "conan-debug"
+        }
+    ],
+    "buildPresets": [
+        {
+            "name": "multi-release",
+            "configurePreset": "default",
+            "configuration": "Release",
+            "inherits": "conan-release"
+        },
+        {
+            "name": "multi-debug",
+            "configurePreset": "default",
+            "configuration": "Debug",
+            "inherits": "conan-debug"
+        },
+        {
+            "name": "release",
+            "configurePreset": "release",
+            "configuration": "Release",
+            "inherits": "conan-release"
+        },
+        {
+            "name": "debug",
+            "configurePreset": "debug",
+            "configuration": "Debug",
+            "inherits": "conan-debug"
+        }
+    ]
+    }
+
+Note how the ``"include": ["./ConanPresets.json"],`` and that every preset ``inherits`` a
+Conan generated one.
+
+We can now install for both Release and Debug (and other configurations also, with the
+help of ``build_folder_vars`` if we want):
+
+.. code-block:: bash
+
+    $ conan install . 
+    $ conan install . -s build_type=Debug
+
+And build and run our application, by using **our own presets** that extend the Conan generated ones:
+
+.. code-block:: bash
+    
+    # Linux (single-config, 2 configure, 2 builds)
+    $ cmake --preset debug
+    $ cmake --build --preset debug
+    $ ./build/Debug/foo
+    > Hello World Debug!
+    
+    $ cmake --preset release
+    $ cmake --build --preset release
+    $ ./build/Release/foo
+    > Hello World Release!
+
+    # Windows VS (Multi-config, 1 configure 2 builds)
+    $ cmake --preset default
+
+    $ cmake --build --preset multi-debug
+    $ build\\Debug\\foo
+    > Hello World Debug!
+
+    $ cmake --build --preset multi-release
+    $ build\\Release\\foo
+    > Hello World Release!
diff --git a/reference/tools/cmake/cmaketoolchain.rst b/reference/tools/cmake/cmaketoolchain.rst
@@ -70,7 +70,7 @@ translated from the current ``settings``:
 - **CMakePresets.json**: The toolchain also generates a ``CMakePresets.json`` standard file, check the documentation
   `here <https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html>`_. It is currently using the version "3" of
   the JSON schema.
-  Conan creates a ``default`` configure preset with the information:
+  Conan creates a ``conan-default`` configure preset with the information:
 
      - The ``generator`` to be used.
      - The path to the ``conan_toolchain.cmake``.
@@ -79,6 +79,11 @@ translated from the current ``settings``:
      - The ``BUILD_TESTING`` variable set to ``OFF``, when configuration ``tools.build:skip_test`` is true.
      - If you run several ``conan install`` with different ``-s build_type`` values, it will generate the corresponding
        ``buildPresets`` and ``configurePresets``.
+     - By default, the presets names will be ``conan-xxxx``, but the "conan-" prefix can be customized with 
+       ``CMakeToolchain.presets_prefix = "conan"`` attribute.
+     - The preset names will be controlled by the ``layout()`` ``self.folders.build_folder_vars`` definition, that
+       can contain a list of settings and options like ``["settings.compiler", "settings.arch", "options.shared"]``.
+
 
 - **CMakeUserPresets.json**:  If you declare a ``layout()`` in the recipe and your
   ``CMakeLists.txt`` file is found at the ``conanfile.source_folder`` folder, a
@@ -89,6 +94,10 @@ translated from the current ``settings``:
   be further tweaked by the ``user_presets_path`` attribute, as documented below. The
   version schema of the generated ``CMakeUserPresets.json`` is "4" and requires CMake >=
   3.23.
+  The file name of this file can be configured with the ``CMakeToolchain.user_presets_path = "CMakeUserPresets.json"```
+  attribute, so if you want to generate a "ConanPresets.json" instead to be included from your own file, 
+  you can define ``tc.user_presets_path = "ConanPresets.jon"`` in the ``generate()`` method.
+  See :ref:`extending your own CMake presets<examples-tools-cmake-toolchain-build-project-extend-presets>` for a full example.
 
   Note: Conan will skip the generation of the ``CMakeUserPresets.json`` if it already exists and was not
   generated by Conan.
@@ -192,7 +201,7 @@ Will generate the sentences: ``set(FOO ON ...)`` and ``set(VAR OFF ...)``.
 
 
 user_presets_path
-+++++++++++++++++
+^^^^^^^^^^^^^^^^^
 
 This attribute allows specifying the location of the generated ``CMakeUserPresets.json`` file.
 Accepted values:
@@ -212,6 +221,13 @@ following way:
         tc.generate()
 
 
+presets_prefix
+^^^^^^^^^^^^^^
+
+By default it is ``"conan"``, and it will generate CMake presets named "conan-xxxx".
+This is done to avoid potential name clashes with users own presets.
+
+
 Using a custom toolchain file
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/tutorial/developing_packages/editable_packages.rst b/tutorial/developing_packages/editable_packages.rst
@@ -88,14 +88,14 @@ Now that the ``say/1.0`` package is in editable mode, let's build it locally:
     # Windows: we will build 2 configurations to show multi-config
     $ conan install . -s build_type=Release
     $ conan install . -s build_type=Debug
-    $ cmake --preset default
-    $ cmake --build --preset release
-    $ cmake --build --preset debug
+    $ cmake --preset conan-default
+    $ cmake --build --preset conan-release
+    $ cmake --build --preset conan-debug
 
     # Linux, MacOS: we will only build 1 configuration
     $ conan install .
-    $ cmake --preset release
-    $ cmake --build --preset release
+    $ cmake --preset conan-release
+    $ cmake --build --preset conan-release
 
 
 Using say/1.0 package in editable mode
@@ -111,9 +111,9 @@ In this case we can build the ``hello`` application as usual:
     # Windows: we will build 2 configurations to show multi-config
     $ conan install . -s build_type=Release
     $ conan install . -s build_type=Debug
-    $ cmake --preset default
-    $ cmake --build --preset release
-    $ cmake --build --preset debug
+    $ cmake --preset conan-default
+    $ cmake --build --preset conan-release
+    $ cmake --build --preset conan-debug
     $ build\Release\hello.exe
     say/1.0: Hello World Release!
     ...
@@ -123,8 +123,8 @@ In this case we can build the ``hello`` application as usual:
 
     # Linux, MacOS: we will only build 1 configuration
     $ conan install .
-    $ cmake --preset release
-    $ cmake --build --preset release
+    $ cmake --preset conan-release
+    $ cmake --build --preset conan-release
     $ ./build/Release/hello
     say/1.0: Hello World Release!
 
@@ -145,11 +145,11 @@ code:
     # Edit src/say.cpp and change the error message from "Hello" to "Bye"
 
     # Windows: we will build 2 configurations to show multi-config
-    $ cmake --build --preset release
-    $ cmake --build --preset debug
+    $ cmake --build --preset conan-release
+    $ cmake --build --preset conan-debug
 
     # Linux, MacOS: we will only build 1 configuration
-    $ cmake --build --preset release
+    $ cmake --build --preset conan-release
 
 
 And build and run the "hello" project:
@@ -160,15 +160,15 @@ And build and run the "hello" project:
 
     # Windows
     $ cd build
-    $ cmake --build --preset release
-    $ cmake --build --preset debug
+    $ cmake --build --preset conan-release
+    $ cmake --build --preset conan-debug
     $ Release\hello.exe
     say/1.0: Bye World Release!
     $ Debug\hello.exe
     say/1.0: Bye World Debug!
 
     # Linux, MacOS
-    $ cmake --build --preset release
+    $ cmake --build --preset conan-release
     $ ./hello
     say/1.0: Bye World Release!
 

diff --git a/tutorial/developing_packages/local_package_development_flow.rst b/tutorial/developing_packages/local_package_development_flow.rst
@@ -229,12 +229,12 @@ preset. Let's try it:
 .. code-block:: bash
 
     $ cd src
-    $ cmake --preset conan-release
+    $ cmake --preset conan-conan-release
     ...
     -- Configuring done
     -- Generating done
 
-    $ cmake --build --preset conan-release
+    $ cmake --build --preset conan-conan-release
     ...
     [100%] Built target hello
 

diff --git a/tutorial/developing_packages/package_layout.rst b/tutorial/developing_packages/package_layout.rst
@@ -221,9 +221,9 @@ the ``hello`` consumer project now, it will search for all the headers and libra
     $ conan install . -s build_type=Release
 
     # Linux, MacOS
-    $ cmake --preset release --log-level=VERBOSE
+    $ cmake --preset conan-release --log-level=VERBOSE
     # Windows
-    $ cmake --preset default --log-level=VERBOSE
+    $ cmake --preset conan-default --log-level=VERBOSE
 
     ...
     -- Conan: Target declared 'say::say'
@@ -233,7 +233,7 @@ the ``hello`` consumer project now, it will search for all the headers and libra
     -- Configuring done
     ...
 
-    $ cmake --build --preset release
+    $ cmake --build --preset conan-release
     [ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o
     [100%] Linking CXX executable hello
     [100%] Built target hello
@@ -262,8 +262,8 @@ package in editable mode and build it locally.
     $ cd ../say
     $ conan editable add . --name=say --version=1.0
     $ conan install . -s build_type=Release
-    $ cmake --preset release
-    $ cmake --build --preset release
+    $ cmake --preset conan-release
+    $ cmake --build --preset conan-release
 
 You can check the contents of the say project's folder now, you can see that the output
 folders match the ones we defined with ``self.folders``:
@@ -300,9 +300,9 @@ defined by ``cpp.source`` and ``cpp.build``:
     $ conan install . -s build_type=Release
 
     # Linux, MacOS
-    $ cmake --preset release --log-level=VERBOSE
+    $ cmake --preset conan-release --log-level=VERBOSE
     # Windows
-    $ cmake --preset default --log-level=VERBOSE
+    $ cmake --preset conan-default --log-level=VERBOSE
 
     ...
     -- Conan: Target declared 'say::say'
@@ -311,7 +311,7 @@ defined by ``cpp.source`` and ``cpp.build``:
     -- Configuring done
     ...
 
-    $ cmake --build --preset release
+    $ cmake --build --preset conan-release
     [ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o
     [100%] Linking CXX executable hello
     [100%] Built target hello