Conan 2.x 通用 conanfile.py 模板详解

import os
from conan import ConanFile
from conan.tools.cmake import CMakeToolchain, CMake, cmake_layout, CMakeDeps
from conan.tools.files import copy


class MyGenericProjectConan(ConanFile):
    # ==========================================
    # 1. 项目基础元数据 (Metadata)
    # ==========================================
    name = "my_project"         # 包的名称
    version = "1.0.0"           # 包的版本号
    license = "MIT"             # 开源协议或授权声明
    author = "Your Name <your.email@example.com>"  # 作者信息
    url = "https://github.com/your-repo/my_project"  # 源码或 Conan 菜谱的托管地址
    description = "这是一个通用的 Conan C++ 项目模板"  # 项目简短描述
    topics = ("cpp", "template", "cmake")  # 标签，方便在包管理器中搜索

    # ==========================================
    # 2. 构建与二进制配置 (Configuration)
    # ==========================================
    # settings 影响构建的二进制哈希值（即不同的操作系统、编译器会导致生成不同的包）
    settings = "os", "compiler", "build_type", "arch"

    # options 允许在编译时以传参的方式开关某些特性
    options = {
        "shared": [True, False],  # 是否编译为动态库
        "fPIC": [True, False],    # 是否生成位置无关代码 (Linux/macOS 下动态库通常需要)
    }

    # default_options 指定上述选项的默认值
    default_options = {
        "shared": False,
        "fPIC": True,
    }

    # 指定哪些源文件需要与此 recipe 一起被打包（用于本地构建包）
    # 通常会将 CMakeLists.txt 和源码目录包含进去
    exports_sources = "CMakeLists.txt", "src/*", "include/*"

    # ==========================================
    # 3. 选项配置 (Config Options & Configure)
    # ==========================================
    def config_options(self):
        """
        在解析选项之前调用。通常用于根据不同的操作系统动态移除不适用的选项。
        """
        # Windows 系统原生不支持也不需要 fPIC，因此将其移除
        if self.settings.os == "Windows":
            del self.options.fPIC

    def configure(self):
        """
        在 settings 和 options 被解析后调用。
        常用于处理设置或选项之间的冲突、依赖关系。
        """
        # 如果当前构建的是动态库 (shared=True)，则 fPIC 必然生效，
        # 移除这个单独的选项，避免它参与 package_id 计算
        if self.options.shared:
            self.options.rm_safe("fPIC")

        # 如果这是一个纯 C 项目，可以移除 C++ 运行时的设定：
        # self.settings.rm_safe("compiler.libcxx")
        # self.settings.rm_safe("compiler.cppstd")

    # ==========================================
    # 4. 目录结构布局 (Layout)
    # ==========================================
    def layout(self):
        """
        定义项目的目录结构（源码在哪，构建目录在哪）。
        使用 CMake 的项目直接调用 cmake_layout(self) 即可获得最佳实践的标准布局。
        """
        cmake_layout(self)

    # ==========================================
    # 5. 依赖管理 (Requirements)
    # ==========================================
    def requirements(self):
        """
        声明项目所需要的依赖包。
        """
        # 示例：添加 zlib 和 fmt 作为依赖库
        # self.requires("zlib/1.3.1")
        # self.requires("fmt/10.2.1")
        #
        # transitive_headers=True: 将依赖的头文件包含路径（Include Directories）
        #   传递给任何依赖"当前包"的下游包
        # transitive_libs=True: 将依赖的二进制库文件（.lib, .a, .so 等）
        #   传递给下游，使其参与最终的链接过程
        # self.requires("zlib/1.3.1", transitive_headers=True, transitive_libs=True)
        #
        # 提示：若在类属性中声明了 package_type = "header-library"，
        # Conan 会自动为所有依赖加上这两个 trait，无需手动指定
        pass

    def build_requirements(self):
        """
        声明仅在构建时需要的工具（如 CMake, Ninja, 单元测试框架等），
        这些依赖不会包含在最终产物中。
        """
        # 示例：强制使用指定版本的 CMake 和 GTest
        # self.tool_requires("cmake/[>=3.24]")
        # self.test_requires("gtest/1.14.0")
        pass

    # ==========================================
    # 6. 生成器配置 (Generate)
    # ==========================================
    def generate(self):
        """
        在实际调用构建系统（如 CMake）之前运行。
        用于生成构建系统能读懂的工具链文件(Toolchain)和依赖查找文件(Dependencies)。
        """
        # 生成第三方库的依赖配置文件 (例如为 zlib 生成 zlib-config.cmake)
        deps = CMakeDeps(self)
        deps.generate()

        # 生成 CMake 工具链文件 (conan_toolchain.cmake)，将 settings 传递给 CMake
        tc = CMakeToolchain(self)
        # 如果需要向 CMake 传递额外的预定义变量，可以在这里添加：
        # tc.variables["MY_CUSTOM_CMAKE_VAR"] = True
        tc.generate()

    # ==========================================
    # 7. 构建过程 (Build)
    # ==========================================
    def build(self):
        """
        执行实际的编译指令。相当于在命令行手动执行 cmake .. && cmake --build .
        """
        cmake = CMake(self)
        cmake.configure()  # 对应 `cmake -S . -B build`
        cmake.build()      # 对应 `cmake --build build`

    # ==========================================
    # 8. 打包产物 (Package)
    # ==========================================
    def package(self):
        """
        定义哪些文件（如头文件、静态库、动态库、可执行文件）应该被提取到最终的 Conan 包中。
        """
        # 通常直接调用 CMake 的 install 目标即可（前提是 CMakeLists.txt 中写好了 install 指令）
        cmake = CMake(self)
        cmake.install()

        # 也可以手动复制所需的 License 文件到包目录中
        # copy(self, "LICENSE", src=self.source_folder,
        #      dst=os.path.join(self.package_folder, "licenses"))

    # ==========================================
    # 9. 包信息配置 (Package Info)
    # ==========================================
    def package_info(self):
        """
        告诉依赖此包的其他项目，在使用本包时需要链接哪些库文件，以及包含哪些目录。
        """
        # 指定要链接的库名称（不需要写 .lib 或 .a 等后缀，假设生成的库名字叫 my_project）
        self.cpp_info.libs = ["my_project"]

        # 如果你的库包含额外的系统依赖项（如 Linux 下的 pthread 或 math 库），需要在此处追加：
        # if self.settings.os in ["Linux", "FreeBSD"]:
        #     self.cpp_info.system_libs = ["m", "pthread"]

        # cpp_info 默认会将 package_folder 里的 "include" 作为头文件目录，"lib" 作为库目录。
        # 一般不需要特别修改，但可以根据需要添加宏定义等：
        # self.cpp_info.defines.append("MY_PROJECT_ENABLED=1")

config_options → configure → layout → requirements/build_requirements
→ generate → build → package → package_info