(#12852) [docs] Add msbuild package template

* Add msbuild package template

Signed-off-by: Uilian Ries <uilianries@gmail.com>

* Missing self

Signed-off-by: Uilian Ries <uilianries@gmail.com>

docs/package_templates/msbuild_package/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/msbuild_package/all/conanfile.py

@@ -0,0 +1,109 @@
+from conan import ConanFile
+from conan.errors import ConanInvalidConfiguration
+from conan.tools.microsoft import is_msvc, MSBuildDeps, MSBuildToolchain, MSBuild, VCVars
+from conan.tools.layout import vs_layout
+from conan.tools.files import apply_conandata_patches, get, copy, rm, replace_in_file
+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") # no "conan" and project name in topics
+    settings = "os", "arch", "compiler", "build_type"
+    options = {
+        "shared": [True, False],
+        "fPIC": [True, False],
+    }
+    default_options = {
+        "shared": False,
+        "fPIC": True,
+    }
+
+    # 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 config_options(self):
+        if self.settings.os == "Windows":
+            del self.options.fPIC
+
+    def configure(self):
+        if self.options.shared:
+            try:
+                del self.options.fPIC # once removed by config_options, need try..except for a second del
+            except Exception:
+                pass
+        try:
+            del self.settings.compiler.libcxx # for plain C projects only
+        except Exception:
+            pass
+        try:
+            del self.settings.compiler.cppstd # for plain C projects only
+        except Exception:
+            pass
+
+    def layout(self):
+        vs_layout(self, src_folder="src") # src_folder must use the same source folder name the project
+
+    def requirements(self):
+        self.requires("dependency/0.8.1") # prefer self.requires method instead of requires attribute
+
+    def validate(self):
+        # in case it does not work in another configuration, it should validated here too
+        if not is_msvc(self):
+            raise ConanInvalidConfiguration(f"{self.ref} can be built only by Visual Studio and msvc.")
+
+    # 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):
+        get(self, **self.conan_data["sources"][self.version],
+                  destination=self.source_folder, strip_root=True)
+
+    def generate(self):
+        tc = MSBuildToolchain(self)
+        tc.generate()
+        tc = MSBuildDeps(self)
+        tc.generate()
+        tc = VCVars(self)
+        tc.generate()
+
+    def _patch_sources(self):
+        apply_conandata_patches(self)
+        # remove bundled xxhash
+        rm(self, "whateer.*", os.path.join(self.source_folder, "lib"))
+        replace_in_file(
+            self,
+            os.path.join(self.source_folder, "CMakeLists.txt"),
+            "...",
+            "",
+        )
+
+    def build(self):
+        self._patch_sources() # It can be apply_conandata_patches(self) only in case no more patches are needed
+        msbuild = MSBuild(self)
+        # customize to Release when RelWithDebInfo
+        msbuild.build_type = "Debug" if self.settings.build_type == "Debug" else "Release"
+        # use Win32 instead of the default value when building x86
+        msbuild.platform = "Win32" if self.settings.arch == "x86" else msbuild.platform
+        # customize according the solution file and compiler version
+        msbuild.build(sln="project_2017.sln")
+
+    def package(self):
+        copy(self, pattern="LICENSE", dst=os.path.join(self.package_folder, "licenses"), src=self.source_folder)
+        copy(self, pattern="*.lib", dst=os.path.join(self.package_folder, "lib"), src=self.build_folder, keep_path=False)
+        copy(self, pattern="*.dll", dst=os.path.join(self.package_folder, "bin"), src=self.build_folder, keep_path=False)
+        copy(self, pattern="*.h", dst=os.path.join(self.package_folder, "include"), src=os.path.join(self.source_folder, "include"))
+
+    def package_info(self):
+        self.cpp_info.libs = ["package_lib"]

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

@@ -0,0 +1,10 @@
+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)

docs/package_templates/msbuild_package/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/msbuild_package/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/msbuild_package/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_11)

docs/package_templates/msbuild_package/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/msbuild_package/config.yml

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