CMake官方教程中文翻译 Step 2: Adding a Library

鉴于自己破烂的英语，所以把cmake的官方文档用 谷歌翻译 翻译下来方便查看。
英语好的同学建议直接去看cmake官方文档（英文）学习：地址 点这里
或复制：https://cmake.org/cmake/help/latest/guide/tutorial/index.html

因为官方文档有点多，所以只截取CMake Tutorial的 step1——step12 进行翻译，这是第2步的翻译，以下是每一步的翻译链接：
Documentation » CMake Tutorial » Step 1: A Basic Starting Point
Documentation » CMake Tutorial » Step 2: Adding a Library
Documentation » CMake Tutorial » Step 3: Adding Usage Requirements for a Library
Documentation » CMake Tutorial » Step 4: Adding Generator Expressions
Documentation » CMake Tutorial » Step 5: Installing and Testing
Documentation » CMake Tutorial » Step 6: Adding Support for a Testing Dashboard
Documentation » CMake Tutorial » Step 7: Adding System Introspection
Documentation » CMake Tutorial » Step 8: Adding a Custom Command and Generated File
Documentation » CMake Tutorial » Step 9: Packaging an Installer
Documentation » CMake Tutorial » Step 10: Selecting Static or Shared Libraries
Documentation » CMake Tutorial » Step 11: Adding Export Configuration
Documentation » CMake Tutorial » Step 12: Packaging Debug and Release

谷歌翻译可能有错，此文档的目的仅是加快观看英文官方文档的速度，所以请结合英文官方文档观看

Step 2: Adding a Library

至此，我们已经了解了如何使用 CMake 创建一个基本项目。 在这一步中，我们将学习如何在项目中创建和使用库。 我们还将了解如何使我们的库的使用变得可选。

Exercise 1 - Creating a Library

要在 CMake 中添加库，请使用 add_library() 命令并指定应由哪些源文件组成该库。

我们可以用一个或多个子目录来组织项目，而不是将所有源文件放在一个目录中。 在这种情况下，我们将专门为我们的库创建一个子目录。 在这里，我们可以添加一个新的 CMakeLists.txt 文件和一个或多个源文件。 在顶层 CMakeLists.txt 文件中，我们将使用 add_subdirectory() 命令将子目录添加到构建中。

创建库后，它会通过 target_include_directories() 和 target_link_libraries() 连接到我们的可执行目标。

Goal

Add and use a library.

Helpful Resources

add_library()
add_subdirectory()
target_include_directories()
target_link_libraries()
PROJECT_SOURCE_DIR

Files to Edit

CMakeLists.txt
tutorial.cxx
MathFunctions/CMakeLists.txt

Getting Started

在本练习中，我们将向项目添加一个库，其中包含我们自己的用于计算数字平方根的实现。 然后，可执行文件可以使用该库，而不是编译器提供的标准平方根函数。

在本教程中，我们将把库放入名为 MathFunctions 的子目录中。 该目录已包含头文件 MathFunctions.h 和 mysqrt.h。 还提供了它们各自的源文件 MathFunctions.cxx 和 mysqrt.cxx。 我们不需要修改任何这些文件。 mysqrt.cxx 有一个名为 mysqrt 的函数，它提供与编译器的 sqrt 函数类似的功能。 MathFunctions.cxx 包含一个函数 sqrt，该函数用于隐藏 sqrt 的实现细节。

在 Help/guide/tutorial/Step2 目录中，从 TODO 1 开始，直到 TODO 6 完成。

首先，填写MathFunctions子目录中的一行CMakeLists.txt。

接下来，编辑顶级 CMakeLists.txt。

最后，在tutorial.cxx中使用新创建的MathFunctions库

Build and Run

运行 cmake 可执行文件或 cmake-gui 来配置项目，然后使用您选择的构建工具进行构建。

下面是命令行的回顾：
mkdir Step2_build
cd Step2_build
cmake …/Step2
cmake --build .

尝试使用新构建的教程并确保它仍然产生准确的平方根值。

Solution

在 MathFunctions 目录中的 CMakeLists.txt 文件中，我们使用 add_library() 创建一个名为 MathFunctions 的库目标。 库的源文件作为参数传递给 add_library()。 这看起来像下面的行：
TODO 1: MathFunctions/CMakeLists.txt
add_library(MathFunctions MathFunctions.cxx mysqrt.cxx)

为了使用新库，我们将在顶级 CMakeLists.txt 文件中添加 add_subdirectory() 调用，以便构建该库。
TODO 2: CMakeLists.txt
add_subdirectory(MathFunctions)

接下来，使用 target_link_libraries() 将新的库目标链接到可执行目标。
TODO 3: CMakeLists.txt
target_link_libraries(Tutorial PUBLIC MathFunctions)

最后我们需要指定库的头文件位置。 修改 target_include_directories() 将 MathFunctions 子目录添加为包含目录，以便可以找到 MathFunctions.h 头文件。
TODO 4: CMakeLists.txt
target_include_directories(Tutorial PUBLIC
“${PROJECT_BINARY_DIR}”
“${PROJECT_SOURCE_DIR}/MathFunctions”
)

现在让我们使用我们的库。 在tutorial.cxx中，包含MathFunctions.h：
TODO 5: tutorial.cxx
#include “MathFunctions.h”

最后，用包装函数 mathfunctions::sqrt 替换 sqrt。
TODO 6: tutorial.cxx
const double outputValue = mathfunctions::sqrt(inputValue);

Exercise 2 - Adding an Option

现在让我们在 MathFunctions 库中添加一个选项，以允许开发人员选择自定义平方根实现或内置标准实现。 虽然对于教程来说确实没有必要这样做，但对于较大的项目来说这是很常见的情况。

Goal

添加不使用 MathFunctions 进行构建的选项。

Helpful Resources

if()
option()
target_compile_definitions()

Files to Edit

MathFunctions/CMakeLists.txt
MathFunctions/MathFunctions.cxx

Getting Started

从练习 1 中生成的文件开始。完成 TODO 7 到 TODO 14。

首先使用 MathFunctions/CMakeLists.txt 中的 option() 命令创建变量 USE_MYMATH。 在同一文件中，使用该选项将编译定义传递到 MathFunctions 库。

然后，更新MathFunctions.cxx以基于USE_MYMATH重定向编译。

最后，在 MathFunctions/CMakeLists.txt 的 USE_MYMATH 块中将 mysqrt.cxx 设为自己的库，以防止在 USE_MYMATH 开启时编译 mysqrt.cxx。

Build and Run

由于我们已经在练习 1 中配置了构建目录，因此我们可以通过简单地调用以下命令来重建：
cd …/Step2_build
cmake --build .

接下来，对几个数字运行教程可执行文件以验证它是否仍然正确。

现在让我们将 USE_MYMATH 的值更新为 OFF。 最简单的方法是使用 cmake-gui 或 ccmake（如果您在终端中）。 或者，如果您想从命令行更改选项，请尝试：
cmake …/Step2 -DUSE_MYMATH=OFF

现在，使用以下内容重建代码：
cmake --build .

然后，再次运行可执行文件以确保它在 USE_MYMATH 设置为 OFF 的情况下仍然可以工作。 sqrt 或 mysqrt 哪个函数能提供更好的结果？

Solution

第一步是向 MathFunctions/CMakeLists.txt 添加一个选项。 该选项将显示在 cmake-gui 和 ccmake 中，默认值为 ON，用户可以更改。
TODO 7: MathFunctions/CMakeLists.txt
option(USE_MYMATH “Use tutorial provided math implementation” ON)

接下来，使用这个新选项来有条件地使用 mysqrt 函数构建和链接我们的库。

创建一个 if() 语句来检查 USE_MYMATH 的值。 在 if() 块内，将 target_compile_definitions() 命令与编译定义 USE_MYMATH 放在一起。
TODO 8: MathFunctions/CMakeLists.txt
if (USE_MYMATH)
target_compile_definitions(MathFunctions PRIVATE “USE_MYMATH”)
endif()

当 USE_MYMATH 为 ON 时，将设置编译定义 USE_MYMATH。 然后，我们可以使用此编译定义来启用或禁用源代码的某些部分。

对源代码的相应更改相当简单。 在 MathFunctions.cxx 中，我们使用 USE_MYMATH 控制使用哪个平方根函数：
TODO 9: MathFunctions/MathFunctions.cxx
#ifdef USE_MYMATH
return detail::mysqrt(x);
#else
return std::sqrt(x);
#endif

接下来，如果定义了 USE_MYMATH，我们需要包含 mysqrt.h。
TODO 10: MathFunctions/MathFunctions.cxx
#ifdef USE_MYMATH
# include “mysqrt.h”
#endif

最后，由于我们正在使用 std::sqrt，所以我们需要包含 cmath。
TODO 11 : MathFunctions/MathFunctions.cxx
#include

此时，如果 USE_MYMATH 为 OFF，则不会使用 mysqrt.cxx，但仍会编译它，因为 MathFunctions 目标在源下列出了 mysqrt.cxx。

有几种方法可以解决这个问题。 第一个选项是使用 target_sources() 从 USE_MYMATH 块中添加 mysqrt.cxx。 另一种选择是在 USE_MYMATH 块中创建一个额外的库，负责编译 mysqrt.cxx。 为了本教程的目的，我们将创建一个额外的库。

首先，从 USE_MYMATH 中创建一个名为 SqrtLibrary 的库，其中包含源 mysqrt.cxx。
TODO 12 : MathFunctions/CMakeLists.txt
add_library(SqrtLibrary STATIC
mysqrt.cxx
)

接下来，当启用 USE_MYMATH 时，我们将 SqrtLibrary 链接到 MathFunctions。
TODO 13 : MathFunctions/CMakeLists.txt
target_link_libraries(MathFunctions PRIVATE SqrtLibrary)

最后，我们可以从 MathFunctions 库源列表中删除 mysqrt.cxx，因为当包含 SqrtLibrary 时它将被拉入。
TODO 14 : MathFunctions/CMakeLists.txt
add_library(MathFunctions MathFunctions.cxx)

通过这些更改，mysqrt 函数现在对于构建和使用 MathFunctions 库的任何人来说都是完全可选的。 用户可以切换 USE_MYMATH 来操作构建中使用的库。