[docs] Recipe templates with Conan 2.x support only (#25849)

* [docs] package_templates: demo non-list conandata URLs as well

* [docs] autotools: do not use `-nologo` for AR with MSVC

It keeps the logs slightly cleaner for a very infrequent command but has caused issues with "ar interface detection" in ./configure for several recipes.

* [docs] autotools: provide tool_requires() versions

These change very infrequently (except for pkgconf, somewhat). I think these can be included for convenience.

* [docs] autotools: mention a common workaround for MSVC

* [docs] cmake: improve recipe example

* [docs] package_templates: update the conventional LicenseRef format

* [docs] package_templates: improve package_type comment

* [docs] package_templates: various minor improvements

* [docs] package_templates: remove outdated test_package comment

* [docs] meson: bump versions in template

* [docs] package_templates: add a version range example

* [docs] package_templates: improve transitive_headers=True examples

* [docs] autotools: improve AutotoolsDeps workaround comment

* [docs] autotools: revert to x.y.z tool versions

* [docs] package_templates: remove outdated CMakeLists.txt comment

* [docs] package_templates: add layout to prebuilt_tool_package test_package

The test_package directory gets gunked up with generated VirtualBuildEnv files otherwise.

* [docs] package_templates: fix some typos

* Move CMake and and PkgConfig properties to the top, drop legacy generator props

The CMake and PkgConfig info is the most relevant part to any consumers and should come first, imo.

New recipes should not bother with the legacy generators, especially after test_v1_package is no longer included.

* Simplify Cmake template

Signed-off-by: Uilian Ries <[email protected]>

* Simplify header-only template

Signed-off-by: Uilian Ries <[email protected]>

* Simplify header-only template

Signed-off-by: Uilian Ries <[email protected]>

* Move patches to source

Signed-off-by: Uilian Ries <[email protected]>

* Simplify autotools template

Signed-off-by: Uilian Ries <[email protected]>

* Simplify meson template

Signed-off-by: Uilian Ries <[email protected]>

* Simplify msbuild template

Signed-off-by: Uilian Ries <[email protected]>

* Simplify prebuilt template

Signed-off-by: Uilian Ries <[email protected]>

* Grammar typo

Signed-off-by: Uilian Ries <[email protected]>

* Use cxx language by default on test package

Signed-off-by: Uilian Ries <[email protected]>

* Remove VirtuanEnvs from test package

Signed-off-by: Uilian Ries <[email protected]>

* Update test package comment

Signed-off-by: Uilian Ries <[email protected]>

* Remove VirtuanEnvs - They are automatic

Signed-off-by: Uilian Ries <[email protected]>

* Comment update

Co-authored-by: Daniel <[email protected]>

* Comment update

Co-authored-by: Daniel <[email protected]>

* Comment update

Co-authored-by: Daniel <[email protected]>

* Comment update

Co-authored-by: Daniel <[email protected]>

* Comment how to install

---------

Signed-off-by: Uilian Ries <[email protected]>
Co-authored-by: Martin Valgur <[email protected]>
Co-authored-by: Daniel <[email protected]>

Author: 3 people

docs/package_templates/autotools_package/all/conandata.yml

@@ -1,17 +1,13 @@
 sources:
-  # Newer versions at the top
   "1.2.0":
     url:
     - "https://mirror1.net/package-1.2.0.tar.gz"
     - "https://mirror2.net/package-1.2.0.tar.gz"
     sha256: "________________________________________________________________"
   "1.1.0":
-    url:
-    - "https://mirror1.net/package-1.1.0.tar.gz"
-    - "https://mirror2.net/package-1.1.0.tar.gz"
+    url: "https://mirror2.net/package-1.1.0.tar.gz"
     sha256: "________________________________________________________________"
 patches:
-  # Newer versions at the top
   "1.1.0":
     - patch_file: "patches/0001-fix-cmake.patch"
       patch_description: "correct the order of cmake min and project"

docs/package_templates/autotools_package/all/conanfile.py

@@ -2,7 +2,7 @@
 from conan.errors import ConanInvalidConfiguration
 from conan.tools.apple import fix_apple_shared_install_name
 from conan.tools.build import check_min_cppstd, cross_building
-from conan.tools.env import Environment, VirtualBuildEnv, VirtualRunEnv
+from conan.tools.env import Environment, VirtualRunEnv
 from conan.tools.files import apply_conandata_patches, copy, export_conandata_patches, get, rm, rmdir
 from conan.tools.gnu import Autotools, AutotoolsDeps, AutotoolsToolchain, PkgConfigDeps
 from conan.tools.layout import basic_layout
@@ -11,7 +11,7 @@
 import os
 
 
-required_conan_version = ">=1.54.0"
+required_conan_version = ">=2.0.9"
 
 #
 # INFO: Please, remove all comments before pushing your PR!
@@ -22,13 +22,13 @@ class PackageConan(ConanFile):
     name = "package"
     description = "short description"
     # Use short name only, conform to SPDX License List: https://spdx.org/licenses/
-    # In case not listed there, use "LicenseRef-<license-file-name>"
+    # In case not listed there, use "DocumentRef-<license-file-name>:LicenseRef-<package-name>"
     license = ""
     url = "https://github.com/conan-io/conan-center-index"
     homepage = "https://github.com/project/package"
     # no "conan" and project name in topics. Use topics from the upstream listed on GH
     topics = ("topic1", "topic2", "topic3")
-    # package_type should usually be "library" (if there is shared option)
+    # package_type should usually be "library", "shared-library" or "static-library"
     package_type = "library"
     settings = "os", "arch", "compiler", "build_type"
     options = {
@@ -41,65 +41,44 @@ class PackageConan(ConanFile):
         "fPIC": True,
         "with_foobar": True,
     }
-
-    @property
-    def _min_cppstd(self):
-        return 14
-
-    # in case the project requires C++14/17/20/... the minimum compiler version should be listed
-    @property
-    def _compilers_minimum_version(self):
-        return {
-            "apple-clang": "10",
-            "clang": "7",
-            "gcc": "7",
-            "msvc": "191",
-            "Visual Studio": "15",
-        }
+    implements = ["auto_shared_fpic"]
 
     @property
     def _settings_build(self):
         return getattr(self, "settings_build", self.settings)
 
     # no exports_sources attribute, but export_sources(self) method instead
-    # this allows finer grain exportation of patches per version
     def export_sources(self):
         export_conandata_patches(self)
 
-    def config_options(self):
-        if self.settings.os == "Windows":
-            del self.options.fPIC
-
     def configure(self):
-        if self.options.shared:
-            self.options.rm_safe("fPIC")
-        # for plain C projects only
+        # for plain C projects only. Otherwise, remove this method.
         self.settings.rm_safe("compiler.cppstd")
         self.settings.rm_safe("compiler.libcxx")
 
     def layout(self):
-        # src_folder must use the same source folder name the project
         basic_layout(self, src_folder="src")
 
     def requirements(self):
-        # prefer self.requires method instead of requires attribute
+        # Prefer self.requirements() method instead of self.requires attribute.
         self.requires("dependency/0.8.1")
         if self.options.with_foobar:
+            # INFO: used in foo/baz.hpp:34
             self.requires("foobar/0.1.0")
+        # Some dependencies on CCI are allowed to use version ranges.
+        # See https://github.com/conan-io/conan-center-index/blob/master/docs/adding_packages/dependencies.md#version-ranges
+        self.requires("openssl/[>=1.1 <4]")
 
     def validate(self):
         # validate the minimum cpp standard supported. Only for C++ projects
-        if self.settings.compiler.get_safe("cppstd"):
-            check_min_cppstd(self, self._min_cppstd)
-        minimum_version = self._compilers_minimum_version.get(str(self.settings.compiler), False)
-        if minimum_version and Version(self.settings.compiler.version) < minimum_version:
-            raise ConanInvalidConfiguration(
-                f"{self.ref} requires C++{self._min_cppstd}, which your compiler does not support."
-            )
+        check_min_cppstd(self, 14)
+
+        # Always comment the reason including the upstream issue.
+        # INFO: Upstream only support Unix systems. See <URL>
         if self.settings.os not in ["Linux", "FreeBSD", "Macos"]:
             raise ConanInvalidConfiguration(f"{self.ref} is not supported on {self.settings.os}.")
 
-    # if another tool than the compiler or autotools is required to build the project (pkgconf, bison, flex etc)
+    # if a tool other than the compiler or autotools is required to build the project (pkgconf, bison, flex etc)
     def build_requirements(self):
         # only if we have to call autoreconf
         self.tool_requires("libtool/x.y.z")
@@ -118,17 +97,16 @@ def build_requirements(self):
 
     def source(self):
         get(self, **self.conan_data["sources"][self.version], strip_root=True)
+        # apply patches listed in conandata.yml
+        # Using patches is always the last resort to fix issues. If possible, try to fix the issue in the upstream project.
+        apply_conandata_patches(self)
 
     def generate(self):
-        # inject tool_requires env vars in build scope (not needed if there is no tool_requires)
-        env = VirtualBuildEnv(self)
-        env.generate()
-        # inject requires env vars in build scope
+        # inject required env vars into the build scope
         # it's required in case of native build when there is AutotoolsDeps & at least one dependency which might be shared, because configure tries to run a test executable
         if not cross_building(self):
-            env = VirtualRunEnv(self)
-            env.generate(scope="build")
-        # --fpic is automatically managed when 'fPIC'option is declared
+            VirtualRunEnv(self).generate(scope="build")
+        # --fpic is automatically managed when 'fPIC' option is declared
         # --enable/disable-shared is automatically managed when 'shared' option is declared
         tc = AutotoolsToolchain(self)
         # autotools usually uses 'yes' and 'no' to enable/disable options
@@ -143,8 +121,10 @@ def yes_no(v): return "yes" if v else "no"
         tc = PkgConfigDeps(self)
         tc.generate()
         # generate dependencies for autotools
-        tc = AutotoolsDeps(self)
-        tc.generate()
+        # some recipes might require a workaround for MSVC (https://github.com/conan-io/conan/issues/12784):
+        # https://github.com/conan-io/conan-center-index/blob/00ce907b910d0d772f1c73bb699971c141c423c1/recipes/xapian-core/all/conanfile.py#L106-L135
+        deps = AutotoolsDeps(self)
+        deps.generate()
 
         # If Visual Studio is supported
         if is_msvc(self):
@@ -158,16 +138,15 @@ def yes_no(v): return "yes" if v else "no"
             env.define("CC", f"{compile_wrapper} cl -nologo")
             env.define("CXX", f"{compile_wrapper} cl -nologo")
             env.define("LD", "link -nologo")
-            env.define("AR", f"{ar_wrapper} \"lib -nologo\"")
+            env.define("AR", f"{ar_wrapper} lib")
             env.define("NM", "dumpbin -symbols")
             env.define("OBJDUMP", ":")
             env.define("RANLIB", ":")
             env.define("STRIP", ":")
             env.vars(self).save_script("conanbuild_msvc")
 
     def build(self):
-        # apply patches listed in conandata.yml
-        apply_conandata_patches(self)
+
         autotools = Autotools(self)
         # (optional) run autoreconf to regenerate configure file (libtool should be in tool_requires)
         autotools.autoreconf()
@@ -180,8 +159,9 @@ def package(self):
         autotools = Autotools(self)
         autotools.install()
 
-        # some files extensions and folders are not allowed. Please, read the FAQs to get informed.
+        # Some files extensions and folders are not allowed. Please, read the FAQs to get informed.
         rm(self, "*.la", os.path.join(self.package_folder, "lib"))
+        # Consider disabling these at first to verify that the package_info() output matches the info exported by the project.
         rmdir(self, os.path.join(self.package_folder, "lib", "pkgconfig"))
         rmdir(self, os.path.join(self.package_folder, "share"))
 
@@ -191,7 +171,7 @@ def package(self):
     def package_info(self):
         self.cpp_info.libs = ["package_lib"]
 
-        # if package provides a pkgconfig file (package.pc, usually installed in <prefix>/lib/pkgconfig/)
+        # if the package provides a pkgconfig file (package.pc, usually installed in <prefix>/lib/pkgconfig/)
         self.cpp_info.set_property("pkg_config_name", "package")
 
         # If they are needed on Linux, m, pthread and dl are usually needed on FreeBSD too

docs/package_templates/autotools_package/all/test_package/CMakeLists.txt

@@ -1,11 +1,7 @@
 cmake_minimum_required(VERSION 3.15)
-project(test_package LANGUAGES C) # if the project is pure C
-# project(test_package LANGUAGES CXX) # if the project uses c++
+project(test_package LANGUAGES CXX)
 
 find_package(package REQUIRED CONFIG)
 
-add_executable(${PROJECT_NAME} test_package.c)
-# don't link to ${CONAN_LIBS} or CONAN_PKG::package
+add_executable(${PROJECT_NAME} test_package.cpp)
 target_link_libraries(${PROJECT_NAME} PRIVATE package::package)
-# In case the target project need a specific C++ standard
-# target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_11)

docs/package_templates/autotools_package/all/test_package/conanfile.py

@@ -4,11 +4,9 @@
 import os
 
 
-# It will become the standard on Conan 2.x
 class TestPackageConan(ConanFile):
     settings = "os", "arch", "compiler", "build_type"
-    generators = "CMakeDeps", "CMakeToolchain", "VirtualRunEnv"
-    test_type = "explicit"
+    generators = "CMakeDeps", "CMakeToolchain"
 
     def layout(self):
         cmake_layout(self)

docs/package_templates/autotools_package/all/test_package/test_package.c

@@ -0,0 +1,21 @@
+#include <cstdlib>
+#include "package/foobar.h"
+
+
+int main(void) {
+    /*
+     * TODO: Remove this comment before pushing the testing code;
+     *
+     * Create a minimal usage for the target project here;
+     * Avoid upstream full examples, or code bigger than 15 lines;
+     * Avoid networking connections;
+     * Avoid background apps or servers;
+     * Avoid GUI apps;
+     * Avoid extra files like images, sounds and other binaries;
+     * The propose is testing the generated artifacts ONLY;
+    */
+
+    foobar_print_version(); // Make sure to call something that will require linkage for compiled libraries
+
+    return EXIT_SUCCESS;
+}

docs/package_templates/autotools_package/all/test_package/test_package.cpp

@@ -1,17 +1,13 @@
 sources:
-  # Newer versions at the top
   "1.2.0":
     url:
     - "https://mirror1.net/package-1.2.0.tar.gz"
     - "https://mirror2.net/package-1.2.0.tar.gz"
     sha256: "________________________________________________________________"
   "1.1.0":
-    url:
-    - "https://mirror1.net/package-1.1.0.tar.gz"
-    - "https://mirror2.net/package-1.1.0.tar.gz"
+    url: "https://mirror1.net/package-1.1.0.tar.gz"
     sha256: "________________________________________________________________"
 patches:
-  # Newer versions at the top
   "1.1.0":
     - patch_file: "patches/0001-fix-cmake.patch"
       patch_description: "correct the order of cmake min and project"