From 14e5376d126ceaaa0efe6b7fac714269d161b0cf Mon Sep 17 00:00:00 2001 From: jgsogo Date: Thu, 2 Sep 2021 16:38:53 +0200 Subject: [PATCH 1/4] [doc] Enforce usage of targets --- docs/reviewing.md | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/docs/reviewing.md b/docs/reviewing.md index 7dcdf6609c4d9..44a63f43d0f13 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -105,20 +105,39 @@ def _configure_cmake(self): ### Minimalistic Source Code -The contents of `test_package.c` or `test_package.cpp` should be as minimal as possible, including a few headers at most with simple instantiation of objects to ensure linkage -and dependencies are correct. +The contents of `test_package.c` or `test_package.cpp` should be as minimal as possible, including a few headers at most with simple +instantiation of objects to ensure linkage and dependencies are correct. Any build system can be used to test the package, but +CMake or Meson are usually preferred. -### Verifying Components +### CMake targets -When components are defined in the `package_info` in `conanfile.py` the following conditions are desired +When using CMake to test a package, the information should be consumed using the **targets provided by `cmake_find_package_multi` generator**. We +enforce this generator to align with the upcoming +[Conan's new `CMakeDeps` generator](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html?highlight=cmakedeps) +and it should help in the migration (and compatibility) with Conan v2. -* use `cmake_find_package` if library has an [official](cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules) CMake module emulated in the recipe. -* use `cmake_find_package_multi` if library provides an official cmake config file emulated in the recipe. If there are more than one target, try to use all of them, or add another executable linking to the global (usually unofficial) target. There may additionally be variables that are emulated by the recipe which should be used as well. There are some ways to identify when to use it: - * Usually, project installs its cmake files into `package_folder/lib/cmake`. The folder is removed from package folder by calling `tools.rmdir(os.path.join(self.package_folder), "lib", "cmake")` - * Also, the library's CMake scripts can use [install(EXPORT ..)](https://cmake.org/cmake/help/latest/command/install.html#export) and/or may install [package configuration helpers](https://cmake.org/cmake/help/latest/module/CMakePackageConfigHelpers.html) - to indicate an exported CMake config file. - * When `self.cpp_info.filenames["cmake_find_package_multi"]`, `self.cpp_info.names["cmake_find_package_multi"]` are declared -* otherwise, use [cmake generator](https://docs.conan.io/en/latest/reference/generators/cmake.html) to not suggest an unofficial cmake target in test package. +In ConanCenter we try to mimic the names of the targets and the information provided by CMake's modules and config files that some libraries +provide. If CMake or the library itself don't enforce any target name, the ones provided by Conan should be recomended. The minimal project +in the `test_package` folder should serve as an example of the best way to consume the package, and targets are preferred over raw variables. + +This rule applies for the _global_ target and for components ones. The following snippet should serve as example: + +**CMakeLists.txt** +```cmake +cmake_minimum_required(VERSION 3.1.2) +project(test_package CXX) + +include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) +conan_basic_setup(TARGETS) + +find_package(package REQUIRED CONFIG) + +add_executable(${PROJECT_NAME} test_package.cpp) +target_link_libraries(${PROJECT_NAME} package::package) +``` + +We encourage contributors to check that not only the _global_ target works properly, but also the ones for the components. It can be +done creating and linking different libraries and or executables. ### Recommended feature options names From eca890ce5ac9b5aca7f88269005152cde434f168 Mon Sep 17 00:00:00 2001 From: jgsogo Date: Thu, 2 Sep 2021 16:43:47 +0200 Subject: [PATCH 2/4] typo --- docs/reviewing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reviewing.md b/docs/reviewing.md index 44a63f43d0f13..6a835749e0aca 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -137,7 +137,7 @@ target_link_libraries(${PROJECT_NAME} package::package) ``` We encourage contributors to check that not only the _global_ target works properly, but also the ones for the components. It can be -done creating and linking different libraries and or executables. +done creating and linking different libraries and/or executables. ### Recommended feature options names From 6d76499f3182b0cbb68f17905a7fc6d8b6693335 Mon Sep 17 00:00:00 2001 From: "Javier G. Sogo" Date: Thu, 2 Sep 2021 19:06:15 +0200 Subject: [PATCH 3/4] Update docs/reviewing.md Co-authored-by: SSE4 --- docs/reviewing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reviewing.md b/docs/reviewing.md index 6a835749e0aca..4df828a765cc5 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -117,7 +117,7 @@ enforce this generator to align with the upcoming and it should help in the migration (and compatibility) with Conan v2. In ConanCenter we try to mimic the names of the targets and the information provided by CMake's modules and config files that some libraries -provide. If CMake or the library itself don't enforce any target name, the ones provided by Conan should be recomended. The minimal project +provide. If CMake or the library itself don't enforce any target name, the ones provided by Conan should be recommended. The minimal project in the `test_package` folder should serve as an example of the best way to consume the package, and targets are preferred over raw variables. This rule applies for the _global_ target and for components ones. The following snippet should serve as example: From c3f9b8c0d36f42b28d7da5f1fd788f19fcb05683 Mon Sep 17 00:00:00 2001 From: "Javier G. Sogo" Date: Mon, 6 Sep 2021 17:42:40 +0200 Subject: [PATCH 4/4] Update docs/reviewing.md Co-authored-by: Chris Mc --- docs/reviewing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reviewing.md b/docs/reviewing.md index 4df828a765cc5..0d870f38fad8f 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -139,7 +139,7 @@ target_link_libraries(${PROJECT_NAME} package::package) We encourage contributors to check that not only the _global_ target works properly, but also the ones for the components. It can be done creating and linking different libraries and/or executables. -### Recommended feature options names +## Recommended feature options names It's often needed to add options to toggle specific library features on/off. Regardless of the default, there is a strong preference for using positive naming for options. In order to avoid the fragmentation, we recommend to use the following naming conventions for such options: