(conan-io#12851) [docs] header-only package template

* Add header-only template

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

* Missing self

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

Author: uilianries

docs/package_templates/header_only/all/conandata.yml

@@ -0,0 +1,29 @@
+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",
+    ]
+    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"
+      patch_type: "backport"
+      patch_source: "https://github.com/owner/package/pulls/42"
+      sha256: "________________________________________________________________"
+      base_path: "source_subfolder"
+    - patch_file: "patches/0002-fix-linux.patch"
+      patch_description: "add missing header to support linux"
+      patch_type: "portability"
+      patch_source: "https://github.com/owner/package/issues/0"
+      sha256: "________________________________________________________________"
+      base_path: "source_subfolder"

docs/package_templates/header_only/all/conanfile.py

@@ -0,0 +1,114 @@
+from conan import ConanFile
+from conan.errors import ConanInvalidConfiguration
+from conan.tools.files import apply_conandata_patches, get, copy
+from conan.tools.build import check_min_cppstd
+from conan.tools.scm import Version
+from conan.tools.layout import basic_layout
+import os
+
+
+required_conan_version = ">=1.51.3"
+
+
+class PackageConan(ConanFile):
+    name = "package"
+    description = "short description"
+    license = "" # Use short name only, conform to SPDX License List: https://spdx.org/licenses/
+    url = "https://github.com/conan-io/conan-center-index"
+    homepage = "https://github.com/project/package"
+    topics = ("topic1", "topic2", "topic3", "header-only") # no "conan"  and project name in topics, keep 'header-only'
+    settings = "os", "arch", "compiler", "build_type" # even for header only
+    no_copy_source = True # do not copy sources to build folder for header only projects, unless, need to apply patches
+
+    @property
+    def _minimum_cpp_standard(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 {
+            "Visual Studio": "15",
+            "msvc": "14.1",
+            "gcc": "5",
+            "clang": "5",
+            "apple-clang": "5.1",
+        }
+
+    # no exports_sources attribute, but export_sources(self) method instead
+    # this allows finer grain exportation of patches per version
+    def export_sources(self):
+        for p in self.conan_data.get("patches", {}).get(self.version, []):
+            copy(self, p["patch_file"], self.recipe_folder, self.export_sources_folder)
+
+    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
+        self.requires("dependency/0.8.1")
+
+    # same package ID for any package
+    def package_id(self):
+        self.info.clear()
+
+    def validate(self):
+        # compiler subsettings are not available when building with self.info.clear()
+        if self.info.settings.get_safe("compiler.cppstd"):
+            # validate the minimum cpp standard supported when installing the package. For C++ projects only
+            check_min_cppstd(self, self._minimum_cpp_standard)
+        minimum_version = self._compilers_minimum_version.get(str(self.info.settings.compiler), False)
+        if minimum_version and Version(self.info.settings.get_safe("compiler.version")) < minimum_version:
+            raise ConanInvalidConfiguration(f"{self.ref} requires C++{self._minimum_cpp_standard}, which your compiler does not support.")
+        # in case it does not work in another configuration, it should validated here too
+        if self.info.settings.os == "Windows":
+            raise ConanInvalidConfiguration(f"{self.ref} can not be used on Windows.")
+
+    # if another tool than the compiler or CMake is required to build the project (pkgconf, bison, flex etc)
+    def build_requirements(self):
+        self.tool_requires("tool/x.y.z")
+
+    def source(self):
+        # download source package and extract to source folder
+        get(self, **self.conan_data["sources"][self.version],
+            destination=self.source_folder, strip_root=True)
+
+    # not mandatory when there is no patch, but will suppress warning message about missing build() method
+    def build(self):
+        # The attribute no_copy_source should not be used when applying patches in build
+        apply_conandata_patches(self)
+
+    # copy all files to the package folder
+    def package(self):
+        copy(self, pattern="LICENSE", dst=os.path.join(self.package_folder, "licenses"), src=self.source_folder)
+        copy(self, pattern="*.h", dst=os.path.join(self.package_folder, "include"), src=os.path.join(self.source_folder, "include"))
+
+    def package_info(self):
+        # folders not used for header-only
+        self.cpp_info.bindirs = []
+        self.cpp_info.frameworkdirs = []
+        self.cpp_info.libdirs = []
+        self.cpp_info.resdirs = []
+
+        # if package has an official FindPACKAGE.cmake listed in https://cmake.org/cmake/help/latest/manual/cmake-modules.7.html#find-modules
+        # examples: bzip2, freetype, gdal, icu, libcurl, libjpeg, libpng, libtiff, openssl, sqlite3, zlib...
+        self.cpp_info.set_property("cmake_module_file_name", "PACKAGE")
+        self.cpp_info.set_property("cmake_module_target_name", "PACKAGE::PACKAGE")
+        # if package provides a CMake config file (package-config.cmake or packageConfig.cmake, with package::package target, usually installed in <prefix>/lib/cmake/<package>/)
+        self.cpp_info.set_property("cmake_file_name", "package")
+        self.cpp_info.set_property("cmake_target_name", "package::package")
+        # if 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
+        if self.settings.os in ["Linux", "FreeBSD"]:
+            self.cpp_info.system_libs.append("m")
+            self.cpp_info.system_libs.append("pthread")
+            self.cpp_info.system_libs.append("dl")
+
+        # TODO: to remove in conan v2 once cmake_find_package_* generators removed
+        self.cpp_info.filenames["cmake_find_package"] = "PACKAGE"
+        self.cpp_info.filenames["cmake_find_package_multi"] = "package"
+        self.cpp_info.names["cmake_find_package"] = "PACKAGE"
+        self.cpp_info.names["cmake_find_package_multi"] = "package"

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

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.8)
+
+project(test_package C) # if the project is pure C
+project(test_package CXX) # if the project uses c++
+
+find_package(package REQUIRED CONFIG)
+
+add_executable(${PROJECT_NAME} test_package.cpp)
+# don't link to ${CONAN_LIBS} or CONAN_PKG::package
+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_14)

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

@@ -0,0 +1,27 @@
+from conan import ConanFile
+from conan.tools.build import can_run
+from conan.tools.cmake import cmake_layout, CMake
+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"
+
+    def requirements(self):
+        self.requires(self.tested_reference_str)
+
+    def layout(self):
+        cmake_layout(self)
+
+    def build(self):
+        cmake = CMake(self)
+        cmake.configure()
+        cmake.build()
+
+    def test(self):
+        if can_run(self):
+            bin_path = os.path.join(self.cpp.build.bindirs[0], "test_package")
+            self.run(bin_path, env="conanrun")

docs/package_templates/header_only/all/test_package/test_package.cpp

@@ -0,0 +1,16 @@
+#include <cstdlib>
+#include <iostream>
+#include "package/foobar.hpp"
+
+
+int main(void) {
+    std::cout << "Create a minimal usage for the target project here." << std::endl;
+    std::cout << "Avoid big examples, bigger than 100 lines" << std::endl;
+    std::cout << "Avoid networking connections." << std::endl;
+    std::cout << "Avoid background apps or servers." << std::endl;
+    std::cout << "The propose is testing the generated artifacts only." << std::endl;
+
+    foobar.print_version();
+
+    return EXIT_SUCCESS;
+}

docs/package_templates/header_only/all/test_v1_package/CMakeLists.txt

@@ -0,0 +1,16 @@
+cmake_minimum_required(VERSION 3.8)
+
+project(test_package C) # if the project is pure C
+project(test_package CXX) # if the project uses c++
+
+include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
+conan_basic_setup(TARGETS)
+
+find_package(package REQUIRED CONFIG)
+
+# Re-use the same source file from test_package folder
+add_executable(${PROJECT_NAME} ../test_package/test_package.cpp)
+# don't link to ${CONAN_LIBS} or CONAN_PKG::package
+target_link_libraries(${PROJECT_NAME} PRIVATE package::package)
+# in case the target project requires a C++ standard
+set_compile_features(${PROJECT_NAME} PRIVATE cxx_std_14)

docs/package_templates/header_only/all/test_v1_package/conanfile.py

@@ -0,0 +1,19 @@
+from conans import ConanFile, CMake
+from conan.tools.build import cross_building
+import os
+
+
+# legacy validation with Conan 1.x
+class TestPackageV1Conan(ConanFile):
+    settings = "os", "arch", "compiler", "build_type"
+    generators = "cmake", "cmake_find_package_multi"
+
+    def build(self):
+        cmake = CMake(self)
+        cmake.configure()
+        cmake.build()
+
+    def test(self):
+        if not cross_building(self):
+            bin_path = os.path.join("bin", "test_package")
+            self.run(bin_path, run_environment=True)

docs/package_templates/header_only/config.yml

@@ -0,0 +1,6 @@
+versions:
+  # Newer versions at the top
+  "1.2.0":
+    folder: all
+  "1.1.0":
+    folder: all