diff --git a/reference/commands/config.rst b/reference/commands/config.rst index d1b86b8e902e..cc8150d8ca9b 100644 --- a/reference/commands/config.rst +++ b/reference/commands/config.rst @@ -238,6 +238,7 @@ Displays all the Conan built-in configurations. There are 2 groups: tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default + tools.cmake.cmaketoolchain:presets_environment: String to define wether to add or not the environment section to the CMake presets. Empty by default, will generate the environment section in CMakePresets. Can take values: 'disabled'. tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain @@ -256,8 +257,8 @@ Displays all the Conan built-in configurations. There are 2 groups: tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts tools.gnu:make_program: Indicate path to make program tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper - tools.google.bazel:bazelrc_path: Defines Bazel rc-path - tools.google.bazel:configs: Define Bazel config file + tools.google.bazel:bazelrc_path: List of paths to bazelrc files to be used as 'bazel --bazelrc=rcpath1 ... build' + tools.google.bazel:configs: List of Bazel configurations to be used as 'bazel build --config=config1 ...' tools.graph:skip_binaries: Allow the graph to skip binaries not needed in the current configuration (True by default) tools.info.package_id:confs: List of existing configuration to be part of the package ID tools.intel:installation_path: Defines the Intel oneAPI installation root path @@ -269,9 +270,10 @@ Displays all the Conan built-in configurations. There are 2 groups: tools.microsoft.bash:subsystem: The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu tools.microsoft.msbuild:installation_path: VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community. Use empty string to disable tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects - tools.microsoft.msbuild:vs_version: Defines the IDE version when using the new msvc compiler + tools.microsoft.msbuild:vs_version: Defines the IDE version (15, 16, 17) when using the msvc compiler. Necessary if compiler.version specifies a toolset that is not the IDE default tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options + tools.microsoft:winsdk_version: Use this winsdk_version in vcvars tools.system.package_manager:mode: Mode for package_manager tools: 'check', 'report', 'report-installed' or 'install' tools.system.package_manager:sudo: Use 'sudo' when invoking the package manager tools in Linux (False by default) tools.system.package_manager:sudo_askpass: Use the '-A' argument if using sudo in Linux to invoke the system package manager (False by default) diff --git a/reference/config_files/global_conf.rst b/reference/config_files/global_conf.rst index d137e828962e..7d24784ace31 100644 --- a/reference/config_files/global_conf.rst +++ b/reference/config_files/global_conf.rst @@ -85,6 +85,7 @@ To list all the possible configurations available, run :command:`conan config li tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default + tools.cmake.cmaketoolchain:presets_environment: String to define wether to add or not the environment section to the CMake presets. Empty by default, will generate the environment section in CMakePresets. Can take values: 'disabled'. tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain @@ -103,8 +104,8 @@ To list all the possible configurations available, run :command:`conan config li tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts tools.gnu:make_program: Indicate path to make program tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper - tools.google.bazel:bazelrc_path: Defines Bazel rc-path - tools.google.bazel:configs: Define Bazel config file + tools.google.bazel:bazelrc_path: List of paths to bazelrc files to be used as 'bazel --bazelrc=rcpath1 ... build' + tools.google.bazel:configs: List of Bazel configurations to be used as 'bazel build --config=config1 ...' tools.graph:skip_binaries: Allow the graph to skip binaries not needed in the current configuration (True by default) tools.info.package_id:confs: List of existing configuration to be part of the package ID tools.intel:installation_path: Defines the Intel oneAPI installation root path @@ -116,9 +117,10 @@ To list all the possible configurations available, run :command:`conan config li tools.microsoft.bash:subsystem: The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu tools.microsoft.msbuild:installation_path: VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community. Use empty string to disable tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects - tools.microsoft.msbuild:vs_version: Defines the IDE version when using the new msvc compiler + tools.microsoft.msbuild:vs_version: Defines the IDE version (15, 16, 17) when using the msvc compiler. Necessary if compiler.version specifies a toolset that is not the IDE default tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options + tools.microsoft:winsdk_version: Use this winsdk_version in vcvars tools.system.package_manager:mode: Mode for package_manager tools: 'check', 'report', 'report-installed' or 'install' tools.system.package_manager:sudo: Use 'sudo' when invoking the package manager tools in Linux (False by default) tools.system.package_manager:sudo_askpass: Use the '-A' argument if using sudo in Linux to invoke the system package manager (False by default) diff --git a/reference/tools/cmake/cmaketoolchain.rst b/reference/tools/cmake/cmaketoolchain.rst index bfb3653184e7..78fb2d642900 100644 --- a/reference/tools/cmake/cmaketoolchain.rst +++ b/reference/tools/cmake/cmaketoolchain.rst @@ -67,23 +67,40 @@ translated from the current ``settings``: so defining the correct Visual Studio prompt is easier. -- **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 ``conan-default`` configure preset with the information: - - - The ``generator`` to be used. - - The path to the ``conan_toolchain.cmake``. - - Some cache variables corresponding to the specified settings cannot work if specified in the toolchain. - - The ``CMAKE_BUILD_TYPE`` variable when using a single-configuration generators. - - 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"]``. - +- **CMakePresets.json**: This toolchain generates a standard `CMakePresets.json` file. For + more information, refer to the documentation `here + `_. It currently uses + version "3" of the JSON schema. Conan adds *configure*, *build*, and *test* preset + entries to the JSON file: + + - `configurePresets` storing the following information: + - The `generator` to be used. + - The path to the `conan_toolchain.cmake`. + - Cache variables corresponding to the specified settings that cannot work if + specified in the toolchain. + - The `CMAKE_BUILD_TYPE` variable for single-configuration generators. + - The `BUILD_TESTING` variable set to `OFF` when the configuration + `tools.build:skip_test` is true. + - An environment section setting all the environment information related to the + :ref:`VirtualBuildEnv` (if any). You can skip + the generation of this section by using the + ``tools.cmake.cmaketoolchain:presets_environment`` configuration. + - By default, preset names will be `conan-xxxx`, but the "conan-" prefix can be + customized with the `CMakeToolchain.presets_prefix = "conan"` attribute. + - Preset names are controlled by the `layout()` `self.folders.build_folder_vars` + definition, which can contain a list of settings and options like + `["settings.compiler", "settings.arch", "options.shared"]`. + + - `buildPresets` storing the following information: + - The `configurePreset` associated with this build preset. + + - `testPresets` storing the following information: + - The `configurePreset` associated with this build preset. + - An environment section setting all the environment information related to the + :ref:`VirtualRunEnv` (if any). You can skip the + generation of this section by using the + ``tools.cmake.cmaketoolchain:presets_environment`` configuration. + - **CMakeUserPresets.json**: If you declare a ``layout()`` in the recipe and your ``CMakeLists.txt`` file is found at the ``conanfile.source_folder`` folder, a @@ -99,8 +116,10 @@ translated from the current ``settings``: 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 + **Note:** Conan will skip the generation of the ``CMakeUserPresets.json`` if it already exists and was not generated by Conan. + + **Note:** To list all available presets, use the ``cmake --list-presets`` command: .. note:: @@ -504,6 +523,7 @@ CMakeToolchain is affected by these ``[conf]`` variables: - **tools.cmake.cmaketoolchain:system_processor** is not necessary in most cases and is only used to force-define ``CMAKE_SYSTEM_PROCESSOR``. - **tools.cmake.cmaketoolchain:toolset_arch**: Will add the ``,host=xxx`` specifier in the ``CMAKE_GENERATOR_TOOLSET`` variable of ``conan_toolchain.cmake`` file. - **tools.cmake.cmake_layout:build_folder_vars**: Settings and Options that will produce a different build folder and different CMake presets names. +- **tools.cmake.cmaketoolchain:presets_environment**: Set to ``'disabled'`` to prevent the addition of the environment section to the generated CMake presets. - **tools.build:cxxflags** list of extra C++ flags that will be appended to ``CMAKE_CXX_FLAGS_INIT``. - **tools.build:cflags** list of extra of pure C flags that will be appended to ``CMAKE_C_FLAGS_INIT``. - **tools.build:sharedlinkflags** list of extra linker flags that will be appended to ``CMAKE_SHARED_LINKER_FLAGS_INIT``.