步骤 1：基本起点

# Step 1: A Basic Starting Point

如何开始使用CMake？这一步将介绍一些CMake的基本语法、命令和变量。随着这些概念的介绍，我们将完成三个练习，并创建一个简单的CMake项目。

本步骤中的每个练习都将以一些背景信息开始。然后，提供一个目标和有用资源列表。`Files to Edit` 部分中的每个文件都在 `Step1` 目录中，并包含一个或多个 `TODO` 注释。每个 `TODO` 代表需要更改或添加的一行或两行代码。`TODO` 应按照数字顺序完成，首先完成 `TODO 1`，然后是 `TODO 2`，依此类推。`Getting Started` 部分将提供一些有用的提示，并指导您完成练习。然后 `Build and Run` 部分将逐步介绍如何构建和测试练习。最后，在每个练习结束时将讨论预期的解决方案。

还请注意，教程中的每个步骤都是基于下一个步骤构建的。因此，例如，`Step2` 的起始代码是 `Step1` 的完整解决方案。

## Exercise 1 - Building a Basic Project

最基本的CMake项目是由单个源代码文件构建的可执行文件。对于这样的简单项目，只需要一个包含三个命令的 `CMakeLists.txt` 文件。

**注意：** 虽然CMake支持大写、小写和混合大小写命令，但小写命令是首选，并将在整个教程中使用。

任何项目的顶层CMakeLists.txt文件必须通过使用`cmake_minimum_required()`命令指定最低的CMake版本。这会建立策略设置，并确保以下的CMake函数在兼容版本的CMake中运行。

要启动一个项目，我们使用`project()`命令来设置项目名称。这个调用在每个项目中都是必需的，并且应该在`cmake_minimum_required()`之后尽快调用。正如我们稍后将看到的，这个命令也可以用来指定其他项目级别的信息，比如语言或版本号。

最后，`add_executable()`命令告诉CMake使用指定的源代码文件创建一个可执行文件。

### Goal

理解如何创建一个简单的CMake项目。

### Helpful Resources

+   `add_executable()`
+   `cmake_minimum_required()`
+   `project()`

### Files to Edit

+   `CMakeLists.txt`

### Getting Started

提供了`Help/guide/tutorial/Step1`目录中的`tutorial.cxx`源代码，可用于计算一个数的平方根。在这一步中，不需要编辑此文件。

在同一个目录中有一个`CMakeLists.txt`文件，您将要完成它。从`TODO 1`始，依次完成`TODO 3`。

### Build and Run

一旦完成了 `TODO 1` 到 `TODO 3`，我们就可以构建和运行我们的项目了！首先，运行`cmake`可执行文件或者 `cmake-gui` 来配置项目，然后使用您选择的构建工具构建它。

例如，从命令行，我们可以导航到 CMake 源代码树中的 `Help/guide/tutorial` 目录，并创建一个构建目录：

```cmake
mkdir Step1_build
```

然后，导航到该构建目录并运行 `cmake` 来配置项目并生成本地构建系统：

```shell
cd Step1_build
cmake ../Step1
```

接着调用构建系统实际编译/链接项目：

```shell
cmake --build .
```

对于支持多配置的生成器（例如 Visual Studio），首先导航到适当的子目录，例如：

```shell
cd Debug
```

最后，尝试使用新构建的 `Tutorial`：

```shell
Tutorial 4294967296
Tutorial 10
Tutorial
```

**注意：** 根据不同的 shell，正确的语法可能是 `Tutorial`、`./Tutorial` 或 `.\Tutorial`。为简单起见，本练习中将始终使用 `Tutorial`。

### Solution

正如前面提到的，我们只需要一个三行的 `CMakeLists.txt` 文件就可以开始运行了。第一行是使用 `cmake_minimum_required()` 设置 CMake 版本，如下所示：

TODO 1:`CMakeLists.txt`
```cmake
cmake_minimum_required(VERSION 3.10)
```
创建基本项目的下一步是使用 project() 命令来设置项目名称，如下所示：

TODO 2: `CMakeLists.txt`
```cmake
project(Tutorial)
```

创建基本项目的最后一步是调用 `add_executable()` 命令。我们调用它如下：

TODO 3: `CMakeLists.txt`
```cmake
add_executable(Tutorial tutorial.cxx)
```

## Exercise 2 - 指定C++版本

CMake有一些特殊的变量，它们要么在后台创建，要么在由项目代码设置时对CMake具有特殊含义。许多这些变量以 `CMAKE_` 开头。在创建项目变量时，应避免使用此命名约定。其中两个特殊的可由用户设置的变量是 `CMAKE_CXX_STANDARD` 和 `CMAKE_CXX_STANDARD_REQUIRED`。这两个变量可一起使用，以指定构建项目所需的C++标准。

### Goal

添加一个需要C++11的标准。

### Helpful Resources

+   `CMAKE_CXX_STANDARD`
+   `CMAKE_CXX_STANDARD_REQUIRED`
+   `set()`

### Files to Edit

+   `CMakeLists.txt`
+   `tutorial.cxx`

### Getting Started

继续编辑`Step1`目录中的文件。从`TODO 4`开始，完成到`TODO 6`。

首先，通过添加一个需要C++11的功能来编辑tutorial.cxx。然后更新CMakeLists.txt以要求C++11。

### Build and Run

让我们再次构建我们的项目。由于我们已经创建了一个构建目录并在练习1中运行了CMake，因此我们可以直接跳到构建步骤：

```shell
cd Step1_build
cmake --build .
```
现在我们可以尝试使用与之前相同的命令使用新构建的`Tutorial`：

```shell
Tutorial 4294967296
Tutorial 10
Tutorial
```

### Solution

我们首先通过在 `tutorial.cxx` 中用 `std::stod` 替换 `atof` 来向我们的项目添加一些 C++11 特性。代码如下所示：

TODO 4: tutorial.cxx

```cpp
const double inputValue = std::stod(argv[1]);
```

要完成 `TODO 5`，只需删除 `#include <cstdlib>`。

我们需要在CMake代码中明确指定应使用正确的标志。 在CMake中启用对特定C++标准的支持的一种方法是使用 `CMAKE_CXX_STANDARD` 变量。 对于本教程，请在 `CMakeLists.txt` 文件中将 `CMAKE_CXX_STANDARD` 变量设置为 `11`，并将 `CMAKE_CXX_STANDARD_REQUIRED` 设置为 `True`。 确保在调用 `add_executable()` 之前添加 `CMAKE_CXX_STANDARD` 声明。

TODO 6: CMakeLists.txt

```cmake
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)
```

## Exercise 3 - 添加版本号和配置头文件

有时，在你的 `CMakeLists.txt` 文件中定义的变量也可以在你的源代码中使用。在这种情况下，我们想要打印项目版本号。

一个实现这一目标的方法是使用配置的头文件。我们创建一个输入文件，其中包含一个或多个要替换的变量。这些变量具有特殊的语法，看起来像 `@VAR@`。然后，我们使用 `configure_file()` 命令将输入文件复制到指定的输出文件，并将这些变量替换为 `CMakelists.txt` 文件中 `VAR` 的当前值。

虽然我们可以直接在源代码中编辑版本号，但使用此功能更可取，因为它创建了一个单一的真实来源，并避免了重复。

### Goal

定义并报告项目的版本号。

### Helpful Resources

+   `<PROJECT-NAME>_VERSION_MAJOR`
+   `<PROJECT-NAME>_VERSION_MINOR`
+   `configure_file()`
+   `target_include_directories()`

### Files to Edit

+   `CMakeLists.txt`
+   `tutorial.cxx`

### Getting Started

继续编辑`Step1`中的文件。从`TODO 7`开始，直到完成`TODO 12`为止。在这个练习中，我们首先在`CMakeLists.txt`中添加项目版本号。在同一个文件中，使用`configure_file()`将给定的输入文件复制到输出文件，并在输入文件内容中替换一些变量值。

接下来，创建一个输入头文件 `TutorialConfig.h.in`，定义版本号，该版本号将接受从 `configure_file()` 传递的变量。

最后，更新 `tutorial.cxx` 以打印出其版本号。

### Build and Run

让我们再次构建我们的项目。与之前一样，我们已经创建了一个构建目录并运行了 CMake，所以我们可以直接跳到构建步骤：

```shell
cd Step1_build
cmake --build .
```

验证当运行可执行文件而没有任何参数时，版本号现在是否被报告。

### Solution

在这个练习中，我们通过打印版本号来改进我们的可执行文件。虽然我们可以在源代码中独立完成这个任务，但使用`CMakeLists.txt`让我们可以维护版本号的单一数据源。

首先，我们修改`CMakeLists.txt`文件，使用project()命令设置项目名称和版本号。当调用project()命令时，CMake会在幕后定义Tutorial_VERSION_MAJOR和Tutorial_VERSION_MINOR。

TODO 7: CMakeLists.txt

```cmake
project(Tutorial VERSION 1.0)
```

然后，我们使用`configure_file()`将输入文件复制，并替换指定的CMake变量：

TODO 8: CMakeLists.txt

```cmake
configure_file(TutorialConfig.h.in TutorialConfig.h)
```

由于配置文件将被写入项目的二进制目录中，因此我们必须将该目录添加到搜索包含文件的路径列表中。

**注意：** 在整个教程中，我们将项目构建和项目二进制目录互换使用。它们是相同的，不是指 bin/ 目录。

我们使用 `target_include_directories()` 来指定可执行目标应该查找包含文件的位置。

TODO 9: CMakeLists.txt

```cmake
target_include_directories(Tutorial PUBLIC
                           "${PROJECT_BINARY_DIR}"
                           )
```

`TutorialConfig.h.in` 是要配置的输入头文件。当从我们的 `CMakeLists.txt` 调用 `configure_file()` 时，`@Tutorial_VERSION_MAJOR@` 和 `@Tutorial_VERSION_MINOR@` 的值将被替换为 `TutorialConfig.h` 中项目的相应版本号。

TODO 10: TutorialConfig.h.in

```cpp
// the configured options and settings for Tutorial
#define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
#define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
```

接下来，我们需要修改 `tutorial.cxx` 文件，以包含配置好的头文件 `TutorialConfig.h`。

TODO 11: tutorial.cxx

```cpp
#include "TutorialConfig.h"
```

最后，我们通过更新 `tutorial.cxx` 文件来打印出可执行文件的名称和版本号，具体操作如下：

TODO 12 : tutorial.cxx

```cpp
if (argc < 2) {
  // report version
  std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
              << Tutorial_VERSION_MINOR << std::endl;
  std::cout << "Usage: " << argv[0] << " number" << std::endl;
  return 1;
}
```