# 18.1 C 预处理器

顾名思义，预处理器在编译器运行之前在源文件上运行。它的能力非常有限，但你可以在构建 C 程序时使用它们来发挥巨大的优势。

预处理器会生成一个新文件，这是编译器实际处理的文件。预处理器的所有命令都从行首开始，# 符号作为第一个非空白字符。

预处理器的主要用途是在源文件中执行文本替换，但它也会使用 `#if` 或类似的语句来执行一些基本的条件代码。

让我们从最常见的预处理器指令开始：`#include`。

## #include

`#include` 用于将一个文件的内容拉取到当前源文件中。`#include` 没有什么复杂的内容。它从文件系统中读取文件，在该文件上运行预处理器，并将结果放入输出文件中。这是为每个 `#include` 指令递归达成的。

例如，如果你查看 `Modules/_multiprocessing/semaphore.c` 文件，那么在文件顶部附近，你将看到以下行：

```c
#include "multiprocessing.h"
```

此行代码会告诉预处理器获取到 `multi-processing.h` 的全部内容，并将它们放入到输出文件的同个位置上。

你需要注意到 `#include` 语句有两种不同形式。其中一个使用引号（""）指定所包含的文件名，另一个使用括号（<>）。两者区别在于在文件系统上查找文件时的搜索路径。

如果你使用 `<>` 作为文件名，则预处理器将仅查看系统包含文件。在文件名周围使用引号将强制预处理器首先查找本地目录，然后再回退到系统目录。

## #define

**#define** 允许你执行简单的文本替换，还可以使用 **#if** 指令，你将会在下面看到。

在最基本的情况下，#define 允许你定义一个新的符号，该符号将在预处理器输出中替换文本字符串。

仍然是在 `semphore.c` 中，你会发现这样的一行文本：

```c
#define SEM_FAILED NULL
```

此行文本告诉预处理器在将代码发送到编译器之前，用文本字符串 `NULL` 替换低于此行的 `SEM_FAILED` 的所有实例。

`#define` 定义项也可以在 `Windows` 特定版本的 `SEM_CREATE` 中使用参数：

```c
#define SEM_CREATE(name, val, max) CreateSemaphore(NULL, val, max, NULL)
```

在这种情况下，预处理器将期望 `SEM_CREATE()`看起来像一个函数调用，并有三个参数。这通常被称为**宏**。它直接将这三个参数的文本替换到输出代码中。

例如，在 `semphore.c` 的第 460 行，`SEM_CREATE` 宏是这样使用的：

```c
handle = SEM_CREATE(name, value, max);
```

当你为 Windows 编译时，此宏将被展开，使此行看起来像这样：

```c
handle = CreateSemaphore(NULL, value, max, NULL);
```

在后面的章节中，你将看到此宏在 Windows 和其他操作系统上的定义有什么不同。

## #undef

此指令将从 `#define` 中删除任何以前的预处理器定义。这使得 `#define` 仅对文件中的部分有效成为可能。

## #if

预处理器还允许使用条件语句，允许你根据某些条件包括或排除文本部分。使用 `#endif` 指令来关闭条件语句，还可以使用 `#elif` 和 `#else` 进行微调。

你将在 CPython 源代码中看到 `#if` 的三种基本形式：

1. 如果定义了指定的宏，则`#ifdef <macro>` 会包含后面的文本块。你还可以看到它被写成 `#if defined(<macro>)`。
2. 如果**没有**定义指定的宏，则`#ifndef <macro>` 会包含后面的文本块。
3. 如果定义了指定的宏并且求得的值为 `True` ，则`#if <macro>` 会包含后面的文本块。

这里要注意的是，使用“文本”而不是“代码”来描述文件中所包含或排除的内容，是因为预处理器对 C 语法一无所知，也不关心指定的文本是什么。

## #pragma

Pragma 是编译器的指令或提示。一般来说，你可以在阅读代码时忽略这些代码，因为它们通常用于处理代码是如何编译的，而不是代码是如何运行的。

## #error

最后，`#error` 会显示一条消息，并导致预处理器停止执行。同样，你在阅读 CPython 源代码时可以安全地忽略这些内容。