多读书多实践，勤思考善领悟

CMake 完整使用教程 之十二 打包项目

后端 2021/03/29

本文于1450天之前发表，文中内容可能已经过时。

本章的主要内容有：

  • 生成源代码和二进制包
  • 使用CMake/pybind11构建的C++/Python项目，通过PyPI发布
  • 使用CMake/CFFI构建C/Fortran/Python项目，通过PyPI发布
  • 以Conda包的形式发布一个简单的项目
  • 将Conda包作为依赖项发布给项目

目前为止，已经从源代码编译并安装了软件包——这意味着可以通过Git获取项目，并手动执行配置、构建、测试和安装。然而，在实际中，软件包通常是使用管理器来安装的，比如Apt、DNF、Pacman、pip和Conda。我们需要以各种格式发布我们的代码项目——作为源文件或二进制安装程序。

本章中，我们将探讨不同的打包策略。首先，讨论使用CMake中的工具CPack进行打包，还提供打包和上传CMake项目到Python包索引(PyPI, https://pypi.org)和Anaconda云(https://anaconda.organaconda(https-oi98au39f//anaconda.org) )的方法，这些都是通过包管理器pip和Conda (https://conda.io/docs/ )分发包的平台。对于PyPI，我们将演示如何打包和分发混合C++/Python或C/Fortran/Python的项目。对于Conda，我们将展示如何对依赖于其他库的C++项目进行打包。

11.1 生成源代码和二进制包

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-11/recipe-01 中找到。该示例在CMake 3.6版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

如果代码是开源的，用户将能够下载项目的源代码，并使用完全定制的CMake脚本自行构建。当然，打包操作也可以使用脚本完成，但是CPack提供了更简单和可移植的替代方案。本示例将指导您创建一些包:

准备工作

我们将使用第10章第3节的示例，项目树由以下目录和文件组成:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
.
├── cmake
│    ├── coffee.icns
│    ├── Info.plist.in
│    └── messageConfig.cmake.in
├── CMakeCPack.cmake
├── CMakeLists.txt
├── INSTALL.md
├── LICENSE
├── src
│    ├── CMakeLists.txt
│    ├── hello-world.cpp
│    ├── Message.cpp
│    └── Message.hpp
└── tests
    ├── CMakeLists.txt
    └── use_target
        ├── CMakeLists.txt
        └── use_message.cpp

由于本示例的重点是使用CPack，所以不会讨论源码。我们只会在CMakeCPack.cmake中添加打包指令。此外，还添加了INSTALL.md和LICENSE文件：打包要求需要包含安装说明和项目许可信息。

具体实施

让我们看看需要添加到这个项目中的打包指令。我们将在CMakeCPack.cmake中收集它们，并在在CMakeLists.txt的末尾包含这个模块include(cmakecpackage.cmake):

  1. 我们声明包的名称，与项目的名称相同，因此我们使用PROJECT_NAME的CMake变量:

    1
    set(CPACK_PACKAGE_NAME "${PROJECT_NAME}")

  2. 声明包的供应商：

    1
    set(CPACK_PACKAGE_VENDOR "CMake Cookbook")

  3. 打包的源代码将包括一个描述文件。这是带有安装说明的纯文本文件:

    1
    set(CPACK_PACKAGE_DESCRIPTION_FILE "${PROJECT_SOURCE_DIR}/INSTALL.md")

  4. 还添加了一个包的描述:

    1
    set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "message: a small messaging library")

  5. 许可证文件也将包括在包中:

    1
    set(CPACK_RESOURCE_FILE_LICENSE "${PROJECT_SOURCE_DIR}/LICENSE")

  6. 从发布包中安装时，文件将放在/opt/recipe-01目录下:

    1
    set(CPACK_PACKAGING_INSTALL_PREFIX "/opt/${PROJECT_NAME}")

  7. CPack所需的主要、次要和补丁版本:

    1
    2
    3
    set(CPACK_PACKAGE_VERSION_MAJOR "${PROJECT_VERSION_MAJOR}")
    set(CPACK_PACKAGE_VERSION_MINOR "${PROJECT_VERSION_MINOR}")
    set(CPACK_PACKAGE_VERSION_PATCH "${PROJECT_VERSION_PATCH}")

  8. 设置了在包装的时候需要忽略的文件列表和目录:

    1
    set(CPACK_SOURCE_IGNORE_FILES "${PROJECT_BINARY_DIR};/.git/;.gitignore")

  9. 列出了源代码归档的打包生成器——在我们的例子中是ZIP，用于生成.ZIP归档，TGZ用于.tar.gz归档:

    1
    set(CPACK_SOURCE_GENERATOR "ZIP;TGZ")

  10. 我们还列出了二进制存档生成器:

    1
    set(CPACK_GENERATOR "ZIP;TGZ")

  11. 现在也可声明平台原生二进制安装程序，从DEB和RPM包生成器开始，不过只适用于GNU/Linux:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    if(UNIX)
      if(CMAKE_SYSTEM_NAME MATCHES Linux)
        list(APPEND CPACK_GENERATOR "DEB")
        set(CPACK_DEBIAN_PACKAGE_MAINTAINER "robertodr")
        set(CPACK_DEBIAN_PACKAGE_SECTION "devel")
        set(CPACK_DEBIAN_PACKAGE_DEPENDS "uuid-dev")
        
        list(APPEND CPACK_GENERATOR "RPM")
        set(CPACK_RPM_PACKAGE_RELEASE "1")
        set(CPACK_RPM_PACKAGE_LICENSE "MIT")
        set(CPACK_RPM_PACKAGE_REQUIRES "uuid-devel")
      endif()
    endif()

  12. 如果我们在Windows上，我们会想要生成一个NSIS安装程序:

    1
    2
    3
    4
    5
    6
    if(WIN32 OR MINGW)
      list(APPEND CPACK_GENERATOR "NSIS")
      set(CPACK_NSIS_PACKAGE_NAME "message")
      set(CPACK_NSIS_CONTACT "robertdr")
      set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
    endif()

  13. 另一方面，在macOS上，bundle包是我们的安装程序的选择:

    1
    2
    3
    4
    5
    6
    7
    if(APPLE)
      list(APPEND CPACK_GENERATOR "Bundle")
      set(CPACK_BUNDLE_NAME "message")
      configure_file(${PROJECT_SOURCE_DIR}/cmake/Info.plist.in Info.plist @ONLY)
      set(CPACK_BUNDLE_PLIST ${CMAKE_CURRENT_BINARY_DIR}/Info.plist)
      set(CPACK_BUNDLE_ICON ${PROJECT_SOURCE_DIR}/cmake/coffee.icns)
    endif()

  14. 我们在现有系统的包装生成器上，向用户打印一条信息:

    1
    message(STATUS "CPack generators: ${CPACK_GENERATOR}")

  15. 最后，我们包括了CPack.cmake标准模块。这将向构建系统添加一个包和一个package_source目标:

    1
    include(CPack)

现在来配置这个项目：

1
2
3
$ mkdir -p build
$ cd build
$ cmake ..

使用下面的命令，我们可以列出可用的目标(示例输出是在使用Unix Makefile作为生成器的GNU/Linux系统上获得的):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$ cmake --build . --target help

The following are some of the valid targets for this Makefile:
... all (the default if no target is provided)
... clean
... depend
... install/strip
... install
... package_source
... package
... install/local
... test
... list_install_components
... edit_cache
... rebuild_cache
... hello- world
... message

我们可以看到package和package_source目标是可用的。可以使用以下命令生成源包:

1
2
3
4
5
6
7
8
9
10
11
12
13
$ cmake --build . --target package_source

Run CPack packaging tool for source...
CPack: Create package using ZIP
CPack: Install projects
CPack: - Install directory: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example
CPack: Create package
CPack: - package: /home/user/cmake-cookbook/chapter- 11/recipe-01/cxx-example/build/recipe-01-1.0.0-Source.zip generated.
CPack: Create package using TGZ
CPack: Install projects
CPack: - Install directory: /home/user/cmake-cookbook/chapter- 11/recipe-01/cxx-example
CPack: Create package
CPack: - package: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/recipe-01- 1.0.0-Source.tar.gz generated.

同样，也可以构建二进制包:

1
$ cmake --build . --target package message-1.0.0-Linux.deb

例子中，最后得到了以下二进制包:

1
2
3
message-1.0.0-Linux.rpm
message-1.0.0-Linux.tar.gz
message-1.0.0-Linux.zip

工作原理

CPack可用于生成用于分发的包。生成构建系统时，我们在CMakeCPack.cmake中列出了CPack指令，用于在构建目录下生成 CPackConfig.cmake。当运行以package或package_source目标的CMake命令时，CPack会自动调用，参数是自动生成的配置文件。实际上，这两个新目标是对CPack简单规则的使用。与CMake一样，CPack也有生成器的概念。CMake上下文中的生成器是用于生成本地构建脚本的工具，例如Unix Makefile或Visual Studio项目文件，而CPack上下文中的生成器是用于打包的工具。我们列出了这些变量，并对不同的平台进行了特别的关注，为源包和二进制包定义了CPACK_SOURCE_GENERATOR和CPACK_GENERATOR变量。因此，DEB包生成器将调用Debian打包实用程序，而TGZ生成器将调用给定平台上的归档工具。我们可以直接在build目录中调用CPack，并选择要与-G命令行选项一起使用的生成器。RPM包可以通过以下步骤生成:

1
2
3
4
5
6
7
8
9
10
$ cd build
$ cpack -G RPM

CPack: Create package using RPM
CPack: Install projects
CPack: - Run preinstall target for: recipe-01
CPack: - Install project: recipe-01
CPack: Create package
CPackRPM: Will use GENERATED spec file: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/_CPack_Packages/Linux/RPM/SPECS/recipe-01.spec
CPack: - package: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/recipe-01-1.0.0-Linux.rpm generated.

对于任何发行版，无论是源代码还是二进制文件，我们只需要打包用户需要的内容，因此整个构建目录和其他与版本控制相关的文件，都必须从要打包的文件列表中排除。我们的例子中，排除列表使用下面的命令声明：

1
set(CPACK_SOURCE_IGNORE_FILES "${PROJECT_BINARY_DIR};/.git/;.gitignore")

我们还需要指定包的基本信息，例如：名称、简短描述和版本。这个信息是通过CMake变量设置的，当包含相应的模块时，CMake变量被传递给CPack。

NOTE:由于CMake 3.9中的project()命令接受DESCRIPTION字段，该字段带有一个描述项目的短字符串。CMake将设置一个PROJECT_DESCRIPTION，可以用它来重置CPACK_PACKAGE_DESCRIPTION_SUMMARY。

让我们详细看看，可以为示例项目生成的不同类型包的说明。

打包源码

我们的示例中，决定对源存档使用TGZ和ZIP生成器。这些文件将分别生成.tar.gz和.zip压缩文件。我们可以检查生成的.tar.gz文件的内容:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$ tar tzf recipe-01-1.0.0-Source.tar.gz

recipe-01-1.0.0-Source/opt/
recipe-01-1.0.0-Source/opt/recipe-01/
recipe-01-1.0.0-Source/opt/recipe-01/cmake/
recipe-01-1.0.0-Source/opt/recipe-01/cmake/coffee.icns
recipe-01-1.0.0-Source/opt/recipe-01/cmake/Info.plist.in
recipe-01-1.0.0-Source/opt/recipe-01/cmake/messageConfig.cmake.in
recipe-01-1.0.0-Source/opt/recipe-01/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/src/
recipe-01-1.0.0-Source/opt/recipe-01/src/Message.hpp
recipe-01-1.0.0-Source/opt/recipe-01/src/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/src/Message.cpp
recipe-01-1.0.0-Source/opt/recipe-01/src/hello-world.cpp
recipe-01-1.0.0-Source/opt/recipe-01/LICENSE
recipe-01-1.0.0-Source/opt/recipe-01/tests/
recipe-01-1.0.0-Source/opt/recipe-01/tests/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/
recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/use_message.cpp
recipe-01-1.0.0-Source/opt/recipe-01/INSTALL.md

与预期相同，只包含源码树的内容。注意INSTALL.md 和LICENSE文件也包括在内，可以通过CPACK_PACKAGE_DESCRIPTION_FILE和CPACK_RESOURCE_FILE_LICENSE变量指定。

NOTE:Visual Studio生成器无法解析package_source目标:https://gitlab.kitware.com/cmake/cmake/issues/13058。

二进制包

创建二进制存档时，CPack将打包CMakeCPack.cmake中描述的目标的内容。因此，在我们的示例中，hello-world可执行文件、消息动态库以及相应的头文件都将以.tar.gz和.zip的格式打包。此外，还将打包CMake配置文件。这对于需要链接到我们的库的其他项目非常有用。包中使用的安装目录可能与从构建树中安装项目时使用的前缀不同，可以使用CPACK_PACKAGING_INSTALL_PREFIX变量来实现这一点。我们的示例中，我们将它设置为系统上的特定位置:/opt/recipe-01。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$ tar tzf recipe-01-1.0.0-Linux.tar.gz

recipe-01- 1.0.0-Linux/opt/
recipe-01-1.0.0-Linux/opt/recipe-01/
recipe-01-1.0.0- Linux/opt/recipe-01/bin/
recipe-01-1.0.0-Linux/opt/recipe-01/bin/hello- world
recipe-01-1.0.0-Linux/opt/recipe-01/share/
recipe-01-1.0.0- Linux/opt/recipe-01/share/cmake/
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageConfig.cmake
recipe-01-1.0.0- Linux/opt/recipe-01/share/cmake/recipe-01/messageTargets-hello- world.cmake
recipe-01-1.0.0-Linux/opt/recipe-01/share/cmake/recipe- 01/messageConfigVersion.cmake
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageTargets-hello-world- release.cmake
recipe-01-1.0.0-Linux/opt/recipe-01/share/cmake/recipe- 01/messageTargets-release.cmake
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageTargets.cmake
recipe-01-1.0.0- Linux/opt/recipe-01/include/
recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/
recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/Message.hpp
recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/messageExport.h
recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/
recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/libmessage.so
recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/libmessage.so.1`

平台原生的二进制安装

我们希望每个平台原生二进制安装程序的配置略有不同。可以在单个CMakeCPack.cmake中使用CPack管理这些差异，就像例子中做的那样。

对于GNU/Linux系统，配置了DEB和RPM生成器:

1
2
3
4
5
6
7
8
9
10
11
12
13
if(UNIX)
  if(CMAKE_SYSTEM_NAME MATCHES Linux)
    list(APPEND CPACK_GENERATOR "DEB")
    set(CPACK_DEBIAN_PACKAGE_MAINTAINER "robertodr")
    set(CPACK_DEBIAN_PACKAGE_SECTION "devel")
    set(CPACK_DEBIAN_PACKAGE_DEPENDS "uuid-dev")
    
    list(APPEND CPACK_GENERATOR "RPM")
    set(CPACK_RPM_PACKAGE_RELEASE "1")
    set(CPACK_RPM_PACKAGE_LICENSE "MIT")
    set(CPACK_RPM_PACKAGE_REQUIRES "uuid-devel")
  endif()
endif()

我们的示例依赖于UUID库，CPACK_DEBIAN_PACKAGE_DEPENDS和cpack_rpm_package_require选项允许指定，包和数据库中对其他包的依赖关系。可以使用dpkg和rpm程序分别分析生成的.deb和.rpm包的内容。

注意，CPACK_PACKAGING_INSTALL_PREFIX也会影响这些包生成器：我们的包将安装到/opt/recipe-01。

CMake真正提供了跨平台和可移植构建系统的支持。下面将使用Nullsoft脚本安装系统(NSIS)创建一个安装程序:

1
2
3
4
5
6
if(WIN32 OR MINGW)
  list(APPEND CPACK_GENERATOR "NSIS")
  set(CPACK_NSIS_PACKAGE_NAME "message")
  set(CPACK_NSIS_CONTACT "robertdr")
  set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
endif()

如果在macOS上构建项目，将启用Bundle packager:

1
2
3
4
5
6
7
if(APPLE)
  list(APPEND CPACK_GENERATOR "Bundle")
  set(CPACK_BUNDLE_NAME "message")
  configure_file(${PROJECT_SOURCE_DIR}/cmake/Info.plist.in Info.plist @ONLY)
  set(CPACK_BUNDLE_PLIST ${CMAKE_CURRENT_BINARY_DIR}/Info.plist)
  set(CPACK_BUNDLE_ICON ${PROJECT_SOURCE_DIR}/cmake/coffee.icns)
endif()

macOS的示例中，需要为包配置属性列表文件，这是通过configure_file实现的。Info.plist的位置和包的图标，这些都可以通过CPack的变量进行设置。

NOTE:可以在这里阅读，关于属性列表格式的更多信息:https://en.wikipedia.org/wiki/Property_list

更多信息

对CMakeCPack.cmake进行设置，要比列出CPack的配置选项简单的多，我们可以将CPACK_*变量的每个生成器设置放在单独的文件中，比如CMakeCPackOptions.cmake，并将这些设置包含到CMakeCPack.cmake使用set(CPACK_PROJECT_CONFIG_FILE "${PROJECT_SOUsRCE_DIR}/CMakeCPackOptions.cmake")将设置包含入 CMakeCPack.cmake中。还可以在CMake时配置该文件，然后在CPack时包含该文件，这为配置多格式包生成器提供了一种简洁的方法(参见https://cmake.org/cmake/help/v3.6/module/CPack.html )。

与CMake中的所有工具一样，CPack功能强大、功能多样，并且提供了更多的灵活性和选项。感兴趣的读者应该看官方文档的命令行界面CPack (https://cmake.org/cmake/help/v3.6/manual/cpack.1.html )手册页，如何使用CPack生成器打包相关项目的更多细节(https://cmake.org/cmake/help/v3.6/module/CPack.html )。

11.2 通过PyPI发布使用CMake/pybind11构建的C++/Python项目

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-11/recipe-02 中找到。该示例在CMake 3.11版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

本示例中，我们将以第9章第5节的代码的pybind11为例，为其添加相关的安装目标和pip打包信息，并将项目上传到PyPI。我们要实现一个可以使用pip安装，并运行CMake从而获取底层pybind11依赖项的项目。

准备工作

要通过PyPI分发包的话，需要一个https://pypi.org 帐户。当然，也可以先从本地路径进行安装练习。

TIPS:建议使用Pipenv (https://docs.pipenv.org )或虚拟环境(https://virtualenv.pypa )安装这个包和其他的Python包。

我们基于第9章第5节的项目，它包含一个主CMakeLists.txt文件和一个account/CMakeLists.txt文件，配置帐户示例目标时，使用如下的项目树：

1
2
3
4
5
6
7
.
├── account
│    ├── account.cpp
│    ├── account.hpp
│    ├── CMakeLists.txt
│    s└── test.py
└── CMakeLists.txt

示例中，account.cpp, account.hpp和test.py没有任何变化。修改account/CMakeLists.txt，并为pip添加几个文件，以便能够构建安装包。为此，需要根目录中的另外三个文件：README.rst，MANIFEST.in和setup.py。

README.rst中包含关于项目的s文档：

1
2
3
4
Example project
===============

Project description in here ...

MANIFEST.in列出了需要安装的Python模块：

1
2
include README.rst CMakeLists.txt
recursive-include account *.cpp *.hpp CMakeLists.txt

最后，setup.py包含构建指令和安装项目的说明：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
import distutils.command.build as _build
import os
import sys
from distutils import spawn
from distutils.sysconfig import get_python_lib
from setuptools import setup


def extend_build():
  class build(_build.build):
    def run(self):
      cwd = os.getcwd()
      if spawn.find_executable('cmake') is None:
        sys.stderr.write("CMake is required to build this package.\n")
        sys.exit(-1)
        _source_dir = os.path.split(__file__)[0]
        _build_dir = os.path.join(_source_dir, 'build_setup_py')
        _prefix = get_python_lib()
        try:
          cmake_configure_command = [
              'cmake',
              '-H{0}'.format(_source_dir),
              '-B{0}'.format(_build_dir),
              '-DCMAKE_INSTALL_PREFIX={0}'.format(_prefix),
          ]
          _generator = os.getenv('CMAKE_GENERATOR')
          if _generator is not None:
            cmake_configure_command.append('-
                                          G{0}'.format(_generator))
          spawn.spawn(cmake_configure_command)
          spawn.spawn(
                ['cmake', '--build', _build_dir, '--target', 'install'])
          os.chdir(cwd)
        except spawn.DistutilsExecError:
          sys.stderr.write("Error while building with CMake\n")
          sys.exit(-1)
          _build.build.run(self)
  return build

_here = os.path.abspath(os.path.dirname(__file__))

if sys.version_info[0] < 3:
  with open(os.path.join(_here, 'README.rst')) as f:
    long_description = f.read()
else:
  with open(os.path.join(_here, 'README.rst'), encoding='utf-8') as f:
    long_description = f.read()

_this_package = 'account'

version = {}
with open(os.path.join(_here, _this_package, 'version.py')) as f:
  exec(f.read(), version)
  
setup(
    name=_this_package,
    version=version['__version__'],
    description='Description in here.',
    long_description=long_description,
    author='Bruce Wayne',
    author_email='bruce.wayne@example.com',
    url='http://example.com',
    license='MIT',
    packages=[_this_package],
    include_package_data=True,
    classifiers=[
        'Development Status :: 3 - Alpha',
        'Intended Audience :: Science/Research',
        'Programming Language :: Python :: 2.7',
        'Programming Language :: Python :: 3.6'
    ],
    cmdclass={'build': extend_build()})

account子目录中放置一个__init__.py脚本：

1
2
3
4
5
6
from .version import __version__
from .account import Account
__all__ = [
  '__version__',
  'Account',
]

再放一个version.py脚本：

1
__version__ = '0.0.0'

项目的文件结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
.
├── account
│    ├── account.cpp
│    ├── account.hpp
│    ├── CMakeLists.txt
│    ├── __init__.py
│    ├── test.py
│    └── version.py
├── CMakeLists.txt
├── MANIFEST.in
├── README.rst
└── setup.py

具体实施

本示例基于第9章第5节项目的基础上。

首先，修改account/CMakeLists.txt，添加安装目标：

1
2
3
4
5
6
install(
  TARGETS
  	account
  LIBRARY
  	DESTINATION account
  )

安装目标时，README.rst, MANIFEST.in，setup.py、__init__.py和version.py将放置在对应的位置上，我们准备使用pybind11测试安装过程：

  1. 为此，在某处创建一个新目录，我们将在那里测试安装。

  2. 在创建的目录中，从本地路径运行pipenv install。调整本地路径，指向setup.py的目录：

    1
    $ pipenv install /path/to/cxx-example

  3. 在Pipenv环境中打开一个Python shell：

    1
    $ pipenv run python

  4. Python shell中，可以测试我们的CMake包：

    1
    2
    3
    4
    5
    6
    7
    >>> from account import Account
    >>> account1 = Account()
    >>> account1.deposit(100.0)
    >>> account1.deposit(100.0)
    >>> account1.withdraw(50.0)
    >>> print(account1.get_balance())
    150.0

工作原理

${CMAKE_CURRENT_BINARY_DIR}目录包含编译后的account.cpython-36m-x86_64-linux-gnu.so，这个动态库就是使用pybind11构建Python模块。但是请注意，它的名称取决于操作系统(本例中是64位Linux)和Python环境(本例中是Python 3.6)。setup.pys脚本将运行CMake，并根据所选的Python环境(系统Python，Pipenv或虚拟环境)将Python模块安装到正确的路径下。

不过，在安装模块时面临两个挑战：

  • 名称可变
  • CMake外部设置路径

可以使用下面的安装目标来解决这个问题，将在setup.py中定义安装目标位置：

1
2
3
4
5
6
install(
  TARGETS
  	account
  LIBRARY
  	DESTINATION account
  )

指示CMake将编译好的Python模块文件安装到相对于安装目标位置的account子目录中(第10章中详细讨论了如何设置目标位置)。setup.py将通过设置CMAKE_INSTALL_PREFIX来设置安装位置，并根据Python环境指向正确的路径。

让我们看看setup.py如何实现的。自下而上来看一下脚本：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
setup(
  name=_this_package,
  version=version['__version__'],
  description='Description in here.',
  long_description=long_description,
  author='Bruce Wayne',
  author_email='bruce.wayne@example.com',
  url='http://example.com',
  license='MIT',
  packages=[_this_package],
  include_package_data=True,
  classifiers=[
    'Development Status :: 3 - Alpha',
    'Intended Audience :: Science/Research',
    'Programming Language :: Python :: 2.7',
    'Programming Language :: Python :: 3.6'
  ],
  cmdclass={'build': extend_build()})

该脚本包含许多占位符，还包含一些自解释的语句。这里我们将重点介绍最后一个指令cmdclass。这个指令中，通过自定义extend_build函数扩展默认的构建步骤。这个默认的构建步骤如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def extend_build():
  class build(_build.build):
    def run(self):
      cwd = os.getcwd()
      if spawn.find_executable('cmake') is None:
        sys.stderr.write("CMake is required to build this package.\n")
        sys.exit(-1)
        _source_dir = os.path.split(__file__)[0]
        _build_dir = os.path.join(_source_dir, 'build_setup_py')
        _prefix = get_python_lib()
        try:
          cmake_configure_command = [
              'cmake',
              '-H{0}'.format(_source_dir),
              '-B{0}'.format(_build_dir),
              '-DCMAKE_INSTALL_PREFIX={0}'.format(_prefix),
          ]
          _generator = os.getenv('CMAKE_GENERATOR')
          if _generator is not None:
            cmake_configure_command.append('-
                                          G{0}'.format(_generator))
          spawn.spawn(cmake_configure_command)
          spawn.spawn(
                ['cmake', '--build', _build_dir, '--target', 'install'])
          os.chdir(cwd)
        except spawn.DistutilsExecError:
          sys.stderr.write("Error while building with CMake\n")
          sys.exit(-1)
          _build.build.run(self)
  return build

首先，检查CMake是否可用。函数执行了两个CMake命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
cmake_configure_command = [
    'cmake',
    '-H{0}'.format(_source_dir),
    '-B{0}'.format(_build_dir),
    '-DCMAKE_INSTALL_PREFIX={0}'.format(_prefix),
]
_generator = os.getenv('CMAKE_GENERATOR')
if _generator is not None:
  cmake_configure_command.append('-
                                G{0}'.format(_generator))
spawn.spawn(cmake_configure_command)
spawn.spawn(
      ['cmake', '--build', _build_dir, '--target', 'install'])

我们可以设置CMAKE_GENERATOR环境变量来修改生成器。安装目录如下方式设置：

1
_prefix = get_python_lib()

从安装目录的根目录下，通过distutils.sysconfig导入get_python_lib函数。cmake --build _build_dir --target install命令以一种可移植的方式，构建和安装我们的项目。使用_build_dir而不使用build的原因是，在测试本地安装时，项目可能已经包含了一个build目录，这将与新安装过程发生冲突。对于已经上传到PyPI的包，构建目录的名称并不会带来什么影响。

更多信息

现在我们已经测试了本地安装，准备将包上传到PyPI。在此之前，请确保setup.py中的元数据(例如：项目名称、联系方式和许可协议信息)是合理的，并且项目名称没有与PyPI已存在项目重名。在上传到https://pypi.org 之前，先测试PyPI(https://test.pypi.org )上，进行上载和下载的尝试。

上传之前，我们需要在主目录中创建一个名为.pypirc的文件，其中包含(替换成自己的yourusername和yourpassword )：

1
2
3
4
5
6
7
8
9
10
11
12
13
[distutils]account
index-servers=
  pypi
  pypitest

[pypi]
username = yourusername
password = yourpassword

[pypitest]
repository = https://test.pypi.org/legacy/
username = yourusername
password = yourpassword

我们将分两步进行。首先，我们在本地创建Release包：

1
$ python setup.py sdist

第二步中，使用Twine上传生成的分布数据(我们将Twine安装到本地的Pipenv中):

1
2
3
4
$ pipenv run twine upload dist/* -r pypitest

Uploading distributions to https://test.pypi.org/legacy/
Uploading yourpackage-0.0.0.tar.gz

下一步，从测试实例到，将包安装到一个隔离的环境中：

1
2
$ pipenv shell
$ pip install --index-url https://test.pypi.org/simple/ yourpackage

当一切正常，就将我们的包上传到了PyPI：

1
$ pipenv run twine upload dist/* -r pypi

11.3 通过PyPI发布使用CMake/CFFI构建C/Fortran/Python项目

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-11/recipe-03 中找到，其中有一个C++和Fortran示例。该示例在CMake 3.5版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

基于第9章第6节的示例，我们将重用前一个示例中的构建块，不过这次使用Python CFFI来提供Python接口，而不是pybind11。这个示例中，我们通过PyPI共享一个Fortran项目，这个项目可以是C或C++项目，也可以是任何公开C接口的语言，非Fortran就可以。

准备工作

项目将使用如下的目录结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
.
├── account
│    ├── account.h
│    ├── CMakeLists.txt
│    ├── implementation
│    │    └── fortran_implementation.f90
│    ├── __init__.py
│    ├── interface_file_names.cfg.in
│    ├── test.py
│    └── version.py
├── CMakeLists.txt
├── MANIFEST.in
├── README.rst
└── setup.py

主CMakeLists.txt文件和account下面的所有源文件(account/CMakeLists.txt除外)与第9章中的使用方式相同。README.rst文件与前面的示例相同。setup.py脚本比上一个示例多了一行(包含install_require =['cffi']的那一行):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# ... up to this line the script is unchanged
setup(
  name=_this_package,
  version=version['__version__'],
  description='Description in here.',
  long_description=long_description,
  author='Bruce Wayne',
  author_email='bruce.wayne@example.com',
  url='http://example.com',
  license='MIT',
  packages=[_this_package],
  install_requires=['cffi'],
  include_package_data=True,
  classifiers=[
    'Development Status :: 3 - Alpha',
    'Intended Audience :: Science/Research',
    'Programming Language :: Python :: 2.7',
    'Programming Language :: Python :: 3.6'
  ],
  cmdclass={'build': extend_build()})

MANIFEST.in应该与Python模块和包一起安装，并包含以下内容:

1
2
include README.rst CMakeLists.txt
recursive-include account *.h *.f90 CMakeLists.txt

account子目录下，我们看到两个新文件。一个version.py文件，其为setup.py保存项目的版本信息：

1
__version__ = '0.0.0'

子目录还包含interface_file_names.cfg.in文件:

1
2
3
[configuration]
header_file_name = account.h
library_file_name = $<TARGET_FILE_NAME:account>

具体实施

讨论一下实现打包的步骤：

  1. 示例基于第9章第6节，使用Python CFFI扩展了account/CMakeLists.txt，增加以下指令:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    file(
      GENERATE OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg
      INPUT ${CMAKE_CURRENT_SOURCE_DIR}/interface_file_names.cfg.in
      )
      
    set_target_properties(account
      PROPERTIES
        PUBLIC_HEADER "account.h;${CMAKE_CURRENT_BINARY_DIR}/account_export.h"
        RESOURCE "${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg"
      )
      
    install(
      TARGETS
        account
      LIBRARY
        DESTINATION account/lib
      RUNTIME
        DESTINATION account/lib
      PUBLIC_HEADER
        DESTINATION account/include
      RESOURCE
        DESTINATION account
      )

    安装目标和附加文件准备好之后，就可以测试安装了。为此，会在某处创建一个新目录，我们将在那里测试安装。

  2. 新创建的目录中，我们从本地路径运行pipenv install。调整本地路径，指向setup.py脚本保存的目录:

    1
    $ pipenv install /path/to/fortran-example

  3. 现在在Pipenv环境中生成一个Python shell:

    1
    $ pipenv run python

  4. Python shell中，可以测试CMake包:

    1
    2
    3
    4
    5
    6
    7
    8
    >>> import account
    >>> account1 = account.new()
    >>> account.deposit(account1, 100.0)
    >>> account.deposit(account1, 100.0)
    >>> account.withdraw(account1, 50.0)
    >>> print(account.get_balance(account1))

    150.0

工作原理

使用Python CFFI和CMake安装混合语言项目的扩展与第9章第6节的例子相对比，和使用Python CFFI的Python包多了两个额外的步骤:

  1. 需要setup.pys
  2. 安装目标时，CFFI所需的头文件和动态库文件，需要安装在正确的路径中，具体路径取决于所选择的Python环境

setup.py的结构与前面的示例几乎一致，唯一的修改是包含install_require =['cffi']，以确保安装示例包时，也获取并安装了所需的Python CFFI。setup.py脚本会自动安装__init__.py和version.py。MANIFEST.in 中的改变不仅有README.rst和CMake文件，还有头文件和Fortran源文件:

1
2
include README.rst CMakeLists.txt
recursive-include account *.h *.f90 CMakeLists.txt

这个示例中，使用Python CFFI和setup.py打包CMake项目时，我们会面临三个挑战:

  • 需要将account.h和account_export.h头文件，以及动态库复制到系统环境中Python模块的位置。
  • 需要告诉__init__.py，在哪里可以找到这些头文件和库。第9章第6节中，我们使用环境变量解决了这些问题，不过使用Python模块时，不可能每次去都设置这些变量。
  • Python方面，我们不知道动态库文件的确切名称(后缀)，因为这取决于操作系统。

让我们从最后一点开始说起：不知道确切的名称，但在CMake生成构建系统时是知道的，因此我们在interface_file_names.cfg,in中使用生成器表达式，对占位符进行展开：

1
2
3
[configuration]
header_file_name = account.h
library_file_name = $<TARGET_FILE_NAME:account>

输入文件用来生成${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg：

1
2
3
4
file(
  GENERATE OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg
  INPUT ${CMAKE_CURRENT_SOURCE_DIR}/interface_file_names.cfg.in
  )

然后，将两个头文件定义为PUBLIC_HEADER(参见第10章)，配置文件定义为RESOURCE：

1
2
3
4
5
set_target_properties(account
  PROPERTIES
  	PUBLIC_HEADER "account.h;${CMAKE_CURRENT_BINARY_DIR}/account_export.h"
  	RESOURCE "${CMAKE_CURRENT_BINARY_DIR}/interface_file_names.cfg"
)

最后，将库、头文件和配置文件安装到setup.py定义的安装路径中:

1
2
3
4
5
6
7
8
9
10
11
12
install(
  TARGETS
  	account
  LIBRARY
  	DESTINATION account/lib
  RUNTIME
  	DESTINATION account/lib
  PUBLIC_HEADER
  	DESTINATION account/include
  RESOURCE
  	DESTINATION account
  )

注意，我们为库和运行时都设置了指向account/lib的目标。这对于Windows很重要，因为动态库具有可执行入口点，因此我们必须同时指定这两个入口点。

Python包将能够找到这些文件，要使用account/__init__.py 来完成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# this interface requires the header file and library file
# and these can be either provided by interface_file_names.cfg
# in the same path as this file
# or if this is not found then using environment variables
_this_path = Path(os.path.dirname(os.path.realpath(__file__)))
_cfg_file = _this_path / 'interface_file_names.cfg'
if _cfg_file.exists():
  config = ConfigParser()
  config.read(_cfg_file)
  header_file_name = config.get('configuration', 'header_file_name')
  _header_file = _this_path / 'include' / header_file_name
  _header_file = str(_header_file)
  library_file_name = config.get('configuration', 'library_file_name')
  _library_file = _this_path / 'lib' / library_file_name
  _library_file = str(_library_file)
else:
  _header_file = os.getenv('ACCOUNT_HEADER_FILE')
  assert _header_file is not None
  _library_file = os.getenv('ACCOUNT_LIBRARY_FILE')
  assert _library_file is not None

本例中，将找到_cfg_file并进行解析，setup.py将找到include下的头文件和lib下的库，并将它们传递给CFFI，从而构造库对象。这也是为什么，使用lib作为安装目标DESTINATION，而不使用CMAKE_INSTALL_LIBDIR的原因(否则可能会让account/__init__.py 混淆)。

更多信息

将包放到PyPI测试和生产实例中的后续步骤，因为有些步骤是类似的，所以可以直接参考前面的示例。

11.4 以Conda包的形式发布一个简单的项目

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-11/recipe-04 中找到。该示例在CMake 3.5版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

虽然PyPI是发布Python包的标准平台，但Anaconda (https://anaconda.org )更为可能更为流行，因为它不仅允许使用Python接口发布Python或混合项目，还允许对非Python项目进行打包和依赖关系管理。这个示例中，我们将为一个非常简单的C++示例项目准备一个Conda包，该项目使用CMake配置和构建，除了C++之外没有依赖关系。下一个示例中，我们将会来看看一个更复杂的Conda包。

准备工作

我们的目标是打包以下示例代码(example.cpp)：

1
2
3
4
5
#include <iostream>
int main() {
	std::cout << "hello from your conda package!" << std::endl;
	return 0;
}

具体实施

  1. CMakeLists.txt文件给出了最低版本要求、项目名称和支持的语言:
1
2
3
4
5
cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
project(recipe-04 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_EXTENSIONS OFF)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

  1. 使用example.cpp构建hello-conda可执行目标：

    1
    2
    3
    4
    5
    add_executable(hello-conda "")
    target_sources(hello-conda
      PRIVATE
      	example.cpp
      )

  2. 使用CMakeLists.txt定义安装目标：

    1
    2
    3
    4
    5
    6
    nstall(
      TARGETS
      	hello-conda
      DESTINATION
      	bin
      )

  3. 将在一个名为meta.yaml的文件中，对Conda包进行描述。我们将把它放在conda-recipe目录下，文件结构如下：

    1
    2
    3
    4
    5
    .
    ├── CMakeLists.txt
    ├── conda-recipe
    │    └── meta.yaml
    └── example.cpp

  4. meta.yaml包含如下内容：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    package:
      name: conda-example-simple
      version: "0.0.0"

    source:
      path: .. /  # this can be changed to git-url
      
    build:
      number: 0
      binary_relocation: true
      script:
        - cmake -H. -Bbuild_conda -G "${CMAKE_GENERATOR}" -DCMAKE_INSTALL_PREFIX=${PREFIX} # [not win]
        - cmake -H. -Bbuild_conda -G "%CMAKE_GENERATOR%" -DCMAKE_INSTALL_PREFIX="%LIBRARY_PREFIX%" # [win]
        - cmake - -build build_conda - -target install
      
    requirements:
      build:
        - cmake >=3.5
        - { { compiler('cxx') } }
        
    about:
      home: http://www.example.com
      license: MIT
      summary: "Summary in here ..."

  5. 现在来构建包：

    1
    $ conda build conda-recipe

  6. 过程中屏幕上看到大量输出，但是一旦构建完成，就可以对包进行安装。首先，在本地进行测试：

    1
    $ conda install --use-local conda-example-simple

  7. 现在准备测试安装包，打开一个新的终端(假设Anaconda处于激活状态)，并输入以下内容：

    1
    2
    3
    $ hello-conda

    hello from your conda package!

  8. 测试成功后，再移除包装：

    1
    $ conda remove conda-example-simple

工作原理

CMakeLists.txt中，安装目标是这个示例的一个基本组件:

1
2
3
4
5
6
install(
  TARGETS
  	hello-conda
  DESTINATION
  	bin
  )

目标的二进制文件会安装到${CMAKE_INSTALL_PREFIX}/bin中。变量由Conda定义，并且构建步骤中定义在meta.yaml：

1
2
3
4
5
6
7
build:
  number: 0
  binary_relocation: true
  script:
    - cmake -H. -Bbuild_conda -G "${CMAKE_GENERATOR}" -DCMAKE_INSTALL_PREFIX=${PREFIX} # [not win]
    - cmake -H. -Bbuild_conda -G "%CMAKE_GENERATOR%" -DCMAKE_INSTALL_PREFIX="%LIBRARY_PREFIX%" # [win]
    - cmake - -build build_conda - -target install

将安装目录设置为${prefix} (Conda的内部变量)，然后构建并安装项目。调用构建目录命名为build_conda的动机与前面的示例类似：特定的构建目录名可能已经命名为build。

更多信息

配置文件meta.yaml可为任何项目指定构建、测试和安装步骤。详情请参考官方文档：https://conda.io/docs/user-guide/tasks/build-packages/define-metadata.html

要将Conda包上传到Anaconda云，请遵循官方的Anaconda文档: https://docs.anaconda.com/anaconda-cloud/user-guide/

此外，也可以考虑将Miniconda，作为Anaconda的轻量级替代品：https://conda.io/miniconda.html

11.5 将Conda包作为依赖项发布给项目

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-11/recipe-05 中找到。该示例在CMake 3.5版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

这个示例中，我们将基于之前示例的结果，并且为CMake项目准备一个更真实和复杂的Conda包，这将取决于DGEMM的函数实现，对于矩阵与矩阵的乘法，可以使用Intel的MKL库进行。Intel的MKL库可以以Conda包的形式提供。此示例将为我们提供一个工具集，用于准备和共享具有依赖关系的Conda包。

准备工作

对于这个示例，我们将使用与前一个示例中的Conda配置，和相同的文件命名和目录结构：

1
2
3
4
5
.
├── CMakeLists.txt
├── conda-recipe
│    └── meta.yaml
└── example.cpp

示例文件(example.cpp)将执行矩阵-矩阵乘法，并将MKL库返回的结果与“noddy”实现进行比较:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
#include "mkl.h"

#include <cassert>
#include <cmath>
#include <iostream>
#include <random>

int main() {
  // generate a uniform distribution of real number between -1.0 and 1.0
  std::random_device rd;
  std::mt19937 mt(rd());
  std:: uniform_real_distribution < double > dist(-1.0, 1.0);
  
  int m = 500;
  int k = 1000;
  int n = 2000;

  double *A = (double *)mkl_malloc(m * k * sizeof(double), 64);
  double *B = (double *)mkl_malloc(k * n * sizeof(double), 64);
  double *C = (double *)mkl_malloc(m * n * sizeof(double), 64);
  double * D = new double[m * n];
  
  for (int i = 0; i < (m * k); i++) {
    A[i] = dist(mt);
  }

  for (int i = 0; i < (k * n); i++) {
    B[i] = dist(mt);
  }

  for (int i = 0; i < (m * n); i++) {
    C[i] = 0.0;
  }

  double alpha = 1.0;
  double beta = 0.0;
  cblas_dgemm(CblasRowMajor,
              CblasNoTrans,
              CblasNoTrans,
              m,
              n,
              k,
              alpha,
              A,
              k,
              B,
              n,
              beta,
              C,
              n);

  // D_mn = A_mk B_kn
  for (int r = 0; r < m; r++) {
    for (int c = 0; c < n; c++) {
      D[r * n + c] = 0.0;
      for (int i = 0; i < k; i++) {
        D[r * n + c] += A[r * k + i] * B[i * n + c];
      }
    }
  }

  // compare the two matrices
  double r = 0.0;
  for (int i = 0; i < (m * n); i++) {
    r += std::pow(C[i] - D[i], 2.0);
  }
  assert (r < 1.0e-12 & & "ERROR: matrices C and D do not match");
  
  mkl_free(A);
  mkl_free(B);
  mkl_free(C);
  delete[] D;

  std:: cout << "MKL DGEMM example worked!" << std:: endl;
  
  return 0;`
}

我们还需要修改meta.yaml。然而，与上一个示例相比，唯一的变化是在依赖项中加入了mkl-devel：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
package:
  name: conda-example-dgemm
  version: "0.0.0"

source:
  path: ../ # this can be changed to git-url

build:
  number: 0
  script:
  - cmake -H. -Bbuild_conda -G "${CMAKE_GENERATOR}"
  -DCMAKE_INSTALL_PREFIX=${PREFIX} # [not win]
  - cmake -H. -Bbuild_conda -G "%CMAKE_GENERATOR%"
  -DCMAKE_INSTALL_PREFIX="%LIBRARY_PREFIX%" # [win]
  - cmake - -build build_conda - -target install
  
requirements:
  build:
    - cmake >=3.5
    - {{ compiler('cxx') }}
  host:
    - mkl - devel 2018
    
about:
  home: http://www.example.com
  license: MIT
  summary: "Summary in here ..."

具体实施

  1. CMakeLists.txt文件声明了最低版本、项目名称和支持的语言：
1
2
3
4
5
cmake_minimum_required(VERSION 3.5 FATAL_ERROR)
project(recipe-05 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_EXTENSIONS OFF)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

  1. 使用example.cpp构建dgem-example可执行目标：

    1
    2
    3
    4
    5
    add_executable(dgemm-example "")
    target_sources(dgemm-example
      PRIVATE
      	example.cpp
      )

  2. 然后，需要找到通过MKL-devel安装的MKL库。我们准备了一个名为IntelMKL的INTERFACE 库，该库可以用于其他目标，并将为依赖的目标设置包括目录、编译器选项和链接库。根据Intel的建议(https://software.intel.com/en-us/articles/intel-mml-link-line-advisor/ )进行设置。首先，设置编译器选项：

    1
    2
    3
    4
    5
    6
    add_library(IntelMKL INTERFACE)

    target_compile_options(IntelMKL
      INTERFACE
      	$<$<OR:$<CXX_COMPILER_ID:GNU>,$<CXX_COMPILER_ID:AppleClang>>:-m64>
      )

  3. 接下来，查找mkl.h头文件，并为IntelMKL目标设置include目录：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    find_path(_mkl_h
      NAMES
      	mkl.h
      HINTS
      	${CMAKE_INSTALL_PREFIX}/include
      )

    target_include_directories(IntelMKL
      INTERFACE
      	${_mkl_h}
      )
      
    message(STATUS "MKL header file FOUND: ${_mkl_h}")

  4. 最后，为IntelMKL目标设置链接库:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    find_library(_mkl_libs
      NAMES
        mkl_rt
      HINTS
        ${CMAKE_INSTALL_PREFIX}/lib
      )
    message(STATUS "MKL single dynamic library FOUND: ${_mkl_libs}")

    find_package(Threads QUIET)
    target_link_libraries(IntelMKL
      INTERFACE
        ${_mkl_libs}
        $<$<OR:$<CXX_COMPILER_ID:GNU>,$<CXX_COMPILER_ID:AppleClang>>:Threads::Threads>
        $<$<OR:$<CXX_COMPILER_ID:GNU>,$<CXX_COMPILER_ID:AppleClang>>:m>
      )

  5. 使用cmake_print_properties函数，打印IntelMKL目标的信息：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    include(CMakePrintHelpers)
    cmake_print_properties(
      TARGETS
      	IntelMKL
      PROPERTIES
        INTERFACE_COMPILE_OPTIONS
        INTERFACE_INCLUDE_DIRECTORIES
        INTERFACE_LINK_LIBRARIES
      )

  6. 将这些库连接到dgem-example:

    1
    2
    3
    4
    target_link_libraries(dgemm-example
      PRIVATE
      	IntelMKL
      )

  7. CMakeLists.txt中定义了安装目标:

    1
    2
    3
    4
    5
    6
    install(
      TARGETS
      	dgemm-example
      DESTINATION
      	bin
      )

  8. 尝试构建包：

    1
    $ conda build conda-recipe

  9. 过程中屏幕上将看到大量输出，但是一旦构建完成，就可以对包进行安装包。首先，在本地进行安装测试：

    1
    $ conda install --use-local conda-example-dgemm

  10. 现在测试安装，打开一个新的终端(假设Anaconda处于激活状态)，并输入：

    1
    2
    3
    $ dgemm-example

    MKL DGEMM example worked!

  11. 安装成功之后，再进行卸载：

    1
    $ conda remove conda-example-dgemm

工作原理

meta.yaml 中的变化就是mml-devel依赖项。从CMake的角度来看，这里的挑战是定位Anaconda安装的MKL库。幸运的是，我们知道它位于${CMAKE_INSTALL_PREFIX}中。可以使用在线的Intel MKL link line advisor(https://software.intel.com/en-us/articles/intel-mml-link-line-advisor/) 查看如何根据选择的平台和编译器，将MKL链接到我们的项目中，我们会将此信息封装到INTERFACE库中。这个解决方案非常适合类MKL的情况：库不是由我们的项目或任何子项目创建的目标，但是它仍然需要以一种方式进行处理；也就是：设置编译器标志，包括目录和链接库。INTERFACE库是构建系统中的目标，但不创建任何构建输出(至少不会直接创建)。但由于它们是目标，我们可对它们的属性进行设置。这样与“实际”目标一样，可以安装、导出和导入。

首先，我们用INTERFACE属性声明一个名为IntelMKL的新库。然后，根据需要设置属性，并使用INTERFACE属性在目标上调用适当的CMake命令：

  • target_compile_options：用于设置INTERFACE_COMPILE_OPTIONS。示例中，设置了-m64，不过这个标志只有GNU和AppleClange编译器能够识别。并且，我们使用生成器表达式来实现。
  • target_include_directories：用于设置INTERFACE_INCLUDE_DIRECTORIES。使用find_path，可以在找到系统上的mkl.h头文件后设置这些参数。
  • target_link_libraries：用于设置INTERFACE_LINK_LIBRARIES。我们决定链接动态库libmkl_rt.so，并用find_library搜索它。GNU或AppleClang编译器还需要将可执行文件链接到线程和数学库。同样，这些情况可以使用生成器表达式优雅地进行处理。

在IntelMKL目标上设置的属性后，可以通过cmake_print_properties命令将属性进行打印。最后，链接到IntelMKL目标，这将设置编译器标志，包括目录和链接库：

1
2
3
4
target_link_libraries(dgemm-example
  PRIVATE
  	IntelMKL
  )

更多信息

Anaconda云上包含大量包。使用上述方法，可以为CMake项目构建依赖于其他Conda包的Conda包。这样，就可以探索软件功能的各种可能性，并与他人分享您的软件包!

转载声明：商业转载请联系作者获得授权,非商业转载请注明出处 © Ljjyy.com
Copyright © 2019-2025 Ljjyy.com | 关于我们 | 网站地图 | 时间轴