From 1e60c4ed8ba3120ac13daf9591289f98c3899da3 Mon Sep 17 00:00:00 2001 From: memsharded Date: Fri, 17 Feb 2023 12:58:38 +0100 Subject: [PATCH 1/4] extend user CMakePresets --- examples/tools/cmake/cmake.rst | 3 +- .../build_project_cmake_presets.rst | 14 +-- .../extend_own_cmake_presets.rst | 112 ++++++++++++++++++ reference/tools/cmake/cmaketoolchain.rst | 20 +++- .../developing_packages/editable_packages.rst | 32 ++--- .../local_package_development_flow.rst | 4 +- .../developing_packages/package_layout.rst | 16 +-- 7 files changed, 165 insertions(+), 36 deletions(-) create mode 100644 examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst diff --git a/examples/tools/cmake/cmake.rst b/examples/tools/cmake/cmake.rst index ece3d65fdd91..2fc71e2b13ba 100644 --- 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 \ No newline at end of file + cmake_toolchain/build_project_cmake_presets + cmake_toolchain/extend_own_cmake_presets \ No newline at end of file diff --git a/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/build_project_cmake_presets.rst index 1fcebc8cdd22..aa1c403d443e 100644 --- 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 new file mode 100644 index 000000000000..8d43f66075e3 --- /dev/null +++ b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst @@ -0,0 +1,112 @@ +.. _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 use ``CMakeToolchain``, predefined layouts like ``cmake_layout`` and the +``CMakePresets`` CMake feature. + +Let's create a basic project based on the template ``cmake_exe`` as an example of a C++ project: + +.. code:: bash + + $ conan new -d name=foo -d version=1.0 cmake_exe + + +And now modify its ``conanfile.py`` to define a different output ``user_preset_path``: + +.. code:: python + + def generate(self): + tc = CMakeToolchain(self) + tc.user_presets_path = 'ConanPresets.json' + tc.generate() + ... + +And provide our 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 it ``include("ConanPresets.json")`` and 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 index 288c6a2abaca..f1575b4ef6b7 100644 --- a/reference/tools/cmake/cmaketoolchain.rst +++ b/reference/tools/cmake/cmaketoolchain.rst @@ -69,7 +69,7 @@ translated from the current ``settings``: - **CMakePresets.json**: The toolchain also generates a ``CMakePresets.json`` standard file, check the documentation `here `_. 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``. @@ -78,6 +78,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 @@ -88,6 +93,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` for a full example. Note: Conan will skip the generation of the ``CMakeUserPresets.json`` if it already exists and was not generated by Conan. @@ -191,7 +200,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: @@ -211,6 +220,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 index 83c682e9256b..738e6a328389 100644 --- 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 index e57ed0fe99fd..57f66639d015 100644 --- 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 index cc1b86fea406..0bcdf06d2a60 100644 --- 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 . say/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 From 26e6bb8c091504c75fb1d8614df80680f75a404f Mon Sep 17 00:00:00 2001 From: czoido Date: Fri, 17 Feb 2023 15:46:01 +0100 Subject: [PATCH 2/4] minor changes --- .../cmake_toolchain/extend_own_cmake_presets.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst index 8d43f66075e3..9eb9b10f933b 100644 --- a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst +++ b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst @@ -3,8 +3,10 @@ CMakeToolchain: Extending your CMakePresets with Conan generated ones ===================================================================== -In this example we are going to see how to use ``CMakeToolchain``, predefined layouts like ``cmake_layout`` and the -``CMakePresets`` CMake feature. +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 Let's create a basic project based on the template ``cmake_exe`` as an example of a C++ project: @@ -76,9 +78,11 @@ And provide our own ``CMakePresets.json``, besides the ``CMakeLists.txt``: ] } -Note how it ``include("ConanPresets.json")`` and every preset ``inherits`` a Conan generated one. +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): +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 From 77adf5bd10973731d60a291ec0d22d2ba14b2aaf Mon Sep 17 00:00:00 2001 From: czoido Date: Fri, 17 Feb 2023 15:58:39 +0100 Subject: [PATCH 3/4] minor changes --- .../cmake_toolchain/extend_own_cmake_presets.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst index 9eb9b10f933b..9d350c72e5a2 100644 --- a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst +++ b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst @@ -8,14 +8,17 @@ generated ones. .. include:: ../../../../tutorial/cmake_presets_note.rst -Let's create a basic project based on the template ``cmake_exe`` as an example of a C++ project: +Please, first of all, clone the sources to recreate this project. You can find them in the +`examples2.0 repository `_ in GitHub: -.. code:: bash - - $ conan new -d name=foo -d version=1.0 cmake_exe +.. code-block:: bash + $ git clone https://github.com/conan-io/examples2.git + $ cd examples2/examples/tools/cmake/cmake_toolchain/local_flow_cmake_presets -And now modify its ``conanfile.py`` to define a different output ``user_preset_path``: +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 From aef862390c1bb8e3b3b1212c62ec8a41207dfd4a Mon Sep 17 00:00:00 2001 From: czoido Date: Fri, 17 Feb 2023 16:00:23 +0100 Subject: [PATCH 4/4] minor changes --- .../tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst index 9d350c72e5a2..f720aa16c913 100644 --- a/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst +++ b/examples/tools/cmake/cmake_toolchain/extend_own_cmake_presets.rst @@ -28,7 +28,7 @@ default filename of the generated preset. tc.generate() ... -And provide our own ``CMakePresets.json``, besides the ``CMakeLists.txt``: +Now you can provide your own ``CMakePresets.json``, besides the ``CMakeLists.txt``: .. code-block:: json :caption: CMakePresets.json