Add support for CONAN_INSTALL_BUILD_CONFIGURATIONS (#707)

craigscott-crascit · jcar87 · web-flow · commit 162e1b8ab329 · 2025-10-31T14:41:00.000Z
* Add support for CONAN_INSTALL_BUILD_CONFIGURATIONS

Let the user or project override the set of build types we execute the
conan install command for. This is most useful for enabling projects to
build only one configuration when using a multi-config generator, but it
can also be used to install for multiple build types with a single-config
generator.

* use build_dir_multi fixture

* test: fix build dir

* fix logic around config override

* fixes

* Update conan_provider.cmake

Co-authored-by: Craig Scott &lt;craig.scott@crascit.com&gt;

* windows runtime tests: run on fresh build directory

* Update docs to mention single-config restriction

---------

Co-authored-by: Luis Caro Campos &lt;3535649+jcar87@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -50,7 +50,7 @@ cmake -B build -S . -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=[path-to-cmake-conan]/con
 
 * Only the `CMakeDeps` generator is specified - for build settings that would otherwise be provided by `CMakeToolchain` (for example, the compiler itself or other global build settings) please invoke Conan separately as per [documentation](https://docs.conan.io/2/tutorial/consuming_packages/build_simple_cmake_project.html).
 * Currently this only works such that Conan can satisfy invocations to CMake's `find_package`. For dependencies that have logic outside of `find_package`, for example, by making direct calls to `find_program`, `find_library`, `find_path` or `find_file`, these may not work correctly.
-* When using a single-configuration CMake generator, you must specify a valid `CMAKE_BUILD_TYPE` (can't be left blank)
+* When using a single-configuration CMake generator, you must specify a valid `CMAKE_BUILD_TYPE` (can't be left blank). Alternatively, `CONAN_INSTALL_BUILD_CONFIGURATIONS` can be set to a non-empty list of build types (see next section).
 * Deriving Conan settings is currently only supported on the most common platforms with the most popular compilers.
 
 ### Customizing Conan profiles
@@ -68,10 +68,25 @@ If you need to customize the profile, you can do so by modifying the value of `C
 * `-DCONAN_BUILD_PROFILE="/path/to/profile"`: alternatively, provide a path to a profile file that may be anywhere in the filesystem.
 * `-DCONAN_HOST_PROFILE="default;custom"`: semi-colon separated list of profiles. A compound profile will be used (see [docs](https://docs.conan.io/2.0/reference/commands/install.html#profiles-settings-options-conf)) - compunded from left to right, where right has the highest priority.
 
+Any `build_type` specified by a host profile is ignored.
+The `build_type` is handled separately, and the default behavior depends on the CMake generator used:
+* For single-configuration generators, `conan install` is executed once with `build_type` set to the `CMAKE_BUILD_TYPE`. The `CMAKE_BUILD_TYPE` must not be empty.
+* For multi-configuration generators, `conan install` is executed twice: once with `build_type` set to `Release`, and a second time with `build_type` set to `Debug`.
+
+You can override the default build type(s) by setting the `CONAN_INSTALL_BUILD_CONFIGURATIONS` CMake variable to a list of build types.
+`conan install` will then be invoked once for each build type.
+This can be used with both single- and multi-configuration generators, although currently only one build type can be specified for single-configuration generators.
+For example:
+* `-DCONAN_INSTALL_BUILD_CONFIGURATIONS=Release;Debug`: execute `conan install` for both `Release` and `Debug` build types with a multi-configuration generator.
+* `-DCONAN_INSTALL_BUILD_CONFIGURATIONS=Release`: execute `conan install` once for just the `Release` build type, applicable for both single- and multi-configuration generators.
+
 ### Customizing the invocation of Conan install
 The CMake-Conan dependency provider will autodetect and pass the profile information as described above. If the `conan install` command invocation needs to be customized further, the `CONAN_INSTALL_ARGS` variable can be used. 
 * By default, `CONAN_INSTALL_ARGS` is initialised to pass `--build=missing`. If you customize this variable, please be aware that Conan will revert to its default behaviour unless you specify the `--build` flag.
-* Two arguments are reserved to the dependency provider implementation and must not be set: the path to a `conanfile.txt|.py`, and the output format (`--format`).
+* Some arguments are reserved for the dependency provider implementation and must not be set in `CONAN_INSTALL_ARGS`:
+  * The path to a `conanfile.txt|.py`.
+  * The output format (`--format`).
+  * The build type setting (`-s build_type=...`).
 * Values are semi-colon separated, e.g. `--build=never;--update;--lockfile-out=''`
 
 
diff --git a/conan_provider.cmake b/conan_provider.cmake
@@ -463,7 +463,7 @@ endfunction()
 function(conan_install)
     set(conan_output_folder ${CMAKE_BINARY_DIR}/conan)
     # Invoke "conan install" with the provided arguments
-    set(conan_args ${conan_args} -of=${conan_output_folder})
+    set(conan_args -of=${conan_output_folder})
     message(STATUS "CMake-Conan: conan install ${CMAKE_SOURCE_DIR} ${conan_args} ${ARGN}")
 
 
@@ -591,18 +591,42 @@ macro(conan_provide_dependency method package_name)
             endif()
             set(generator "-g;CMakeDeps")
         endif()
+
         get_property(_multiconfig_generator GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
-        if(NOT _multiconfig_generator)
-            message(STATUS "CMake-Conan: Installing single configuration ${CMAKE_BUILD_TYPE}")
-            conan_install(${_host_profile_flags} ${_build_profile_flags} ${CONAN_INSTALL_ARGS} ${generator})
+        
+        if(DEFINED CONAN_INSTALL_BUILD_CONFIGURATIONS)
+            # Configurations are specified by the project or user
+            set(_build_configs "${CONAN_INSTALL_BUILD_CONFIGURATIONS}")
+            list(LENGTH _build_configs _build_configs_length)
+            if(NOT _multiconfig_generator AND _build_configs_length GREATER 1)
+                message(FATAL_ERROR "cmake-conan: when using a single-config CMake generator, "
+                        "please only specify a single configuration in CONAN_INSTALL_BUILD_CONFIGURATIONS")
+            endif()
+            unset(_build_configs_length)
         else()
-            message(STATUS "CMake-Conan: Installing both Debug and Release")
-            conan_install(${_host_profile_flags} ${_build_profile_flags} -s build_type=Release ${CONAN_INSTALL_ARGS} ${generator})
-            conan_install(${_host_profile_flags} ${_build_profile_flags} -s build_type=Debug ${CONAN_INSTALL_ARGS} ${generator})
+            # No configuration overrides, provide sensible defaults            
+            if(_multiconfig_generator)
+                set(_build_configs Release Debug)
+            else()
+                set(_build_configs ${CMAKE_BUILD_TYPE})
+            endif()
+            
         endif()
+        list(JOIN _build_configs ", " _build_configs_msg)
+        message(STATUS "CMake-Conan: Installing configuration(s): ${_build_configs_msg}")
+        foreach(_build_config IN LISTS _build_configs)
+            set(_self_build_config "")
+            if(NOT _multiconfig_generator AND NOT _build_config STREQUAL "${CMAKE_BUILD_TYPE}")
+                set(_self_build_config -s &:build_type=${CMAKE_BUILD_TYPE})
+            endif()
+            conan_install(${_host_profile_flags} ${_build_profile_flags} -s build_type=${_build_config} ${_self_build_config} ${CONAN_INSTALL_ARGS} ${generator})
+        endforeach()
+        unset(_self_build_config)
+        unset(_multiconfig_generator)
+        unset(_build_configs)
+        unset(_build_configs_msg)
         unset(_host_profile_flags)
         unset(_build_profile_flags)
-        unset(_multiconfig_generator)
         unset(_conan_install_success)
     else()
         message(STATUS "CMake-Conan: find_package(${ARGV1}) found, 'conan install' already ran")
diff --git a/tests/test_smoke.py b/tests/test_smoke.py
@@ -36,6 +36,15 @@
 def run(cmd, check=True):
     subprocess.run(cmd, shell=True, check=check)
 
+def clear_folder_contents(folder_path):
+    if not os.path.isdir(folder_path):
+        raise ValueError(f"{folder_path} is not a valid directory.")
+    for entry in os.listdir(folder_path):
+        entry_path = os.path.join(folder_path, entry)
+        if os.path.isfile(entry_path) or os.path.islink(entry_path):
+            os.unlink(entry_path)
+        elif os.path.isdir(entry_path):
+            shutil.rmtree(entry_path)
 
 @pytest.fixture(scope="session")
 def conan_home_dir(tmp_path_factory):
@@ -172,7 +181,7 @@ def test_single_config_only_one_configuration_installed(self, capfd):
         out, _ = capfd.readouterr()
         assert all(expected in out for expected in expected_conan_install_outputs)
         assert "Overriding config types" in out
-        assert "CMake-Conan: Installing single configuration Release" in out
+        assert "CMake-Conan: Installing configuration(s): Release\n" in out
         run("cmake --build .")
         out, _ = capfd.readouterr()
         assert all(expected not in out for expected in expected_conan_install_outputs)
@@ -183,6 +192,25 @@ def test_single_config_only_one_configuration_installed(self, capfd):
         expected_output = [f.format(config="Release") for f in expected_app_outputs]
         assert all(expected in out for expected in expected_output)
 
+    def test_single_config_override_install_config(self, capfd):
+        "Ensure that CONAN_INSTALL_BUILD_CONFIGURATIONS is honored for single-config generators"
+        generator = "-GNinja" if platform.system() == "Windows" else ""
+        run(f'cmake -S {self.source_dir} -B {self.binary_dir} -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES={conan_provider} {generator} -DCMAKE_BUILD_TYPE=RelWithDebInfo "-DCONAN_INSTALL_BUILD_CONFIGURATIONS=Release"')
+        out, _ = capfd.readouterr()
+        assert all(expected in out for expected in expected_conan_install_outputs)
+        assert "CMake-Conan: Installing configuration(s): Release\n" in out
+        # We don't need to do a build, just running CMake configure is enough to verify the config selection
+    
+    @pytest.mark.usefixtures("build_dir_multi")
+    def test_multi_config_override_install_config(self, capfd):
+        "Ensure that CONAN_INSTALL_BUILD_CONFIGURATIONS is honored for multi-config generators"
+        generator = "-G'Ninja Multi-Config'" if platform.system() != "Windows" else ""
+        run(f'cmake -S {self.source_dir} -B {self.binary_dir_multi} -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES={conan_provider} {generator} -DCONAN_INSTALL_BUILD_CONFIGURATIONS=Release')
+        out, _ = capfd.readouterr()
+        assert all(expected in out for expected in expected_conan_install_outputs)
+        assert "CMake-Conan: Installing configuration(s): Release\n" in out
+        # We don't need to do a build, just running CMake configure is enough to verify the config selection
+
     @unix
     def test_reconfigure_on_conanfile_changes(self, capfd):
         "A conanfile change triggers conan install"
@@ -202,7 +230,8 @@ def test_reconfigure_on_conanfile_changes(self, capfd):
                                               "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL",
                                               "MultiThreaded", "MultiThreadedDebugDLL"])
     def test_msvc_runtime_multiconfig(self, capfd, msvc_runtime):
-        msvc_runtime_flag = f'-DCMAKE_MSVC_RUNTIME_LIBRARY="{msvc_runtime}"' 
+        msvc_runtime_flag = f'-DCMAKE_MSVC_RUNTIME_LIBRARY="{msvc_runtime}"'
+        clear_folder_contents(self.binary_dir_multi)
         run(f"cmake -S {self.source_dir} -B {self.binary_dir_multi} -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES={conan_provider} {msvc_runtime_flag}")
         out, _ = capfd.readouterr()
         assert all(expected in out for expected in expected_conan_install_outputs)
@@ -227,7 +256,8 @@ def test_msvc_runtime_multiconfig(self, capfd, msvc_runtime):
                                               "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL",
                                               "MultiThreaded", "MultiThreadedDebugDLL"])
     def test_msvc_runtime_singleconfig(self, capfd, config, msvc_runtime):
-        msvc_runtime_flag = f'-DCMAKE_MSVC_RUNTIME_LIBRARY="{msvc_runtime}"' 
+        msvc_runtime_flag = f'-DCMAKE_MSVC_RUNTIME_LIBRARY="{msvc_runtime}"'
+        clear_folder_contents(self.binary_dir)
         run(f"cmake -S {self.source_dir} -B {self.binary_dir} -GNinja -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES={conan_provider} -DCMAKE_BUILD_TYPE={config} {msvc_runtime_flag} -GNinja")
         out, _ = capfd.readouterr()
         assert all(expected in out for expected in expected_conan_install_outputs)
