从零开始：用CMake和Makefile编译你的第一个C++项目（以MyTinySTL为例）

当你第一次从GitHub上克隆一个C++项目时，面对满眼的 .cpp 文件、 CMakeLists.txt 和各种 make 命令，是不是感觉像在破解某种古老咒语？别担心，每个C++开发者都经历过这个阶段。本文将带你从零开始，一步步理解这些工具的作用，并最终成功编译你的第一个C++项目。

1. 为什么需要构建工具？

想象一下，你写了一个简单的"Hello World"程序，只有一个 main.cpp 文件。这种情况下，你可以直接用 g++ main.cpp -o hello 来编译。但现实中的项目往往包含几十甚至上百个源文件，各种依赖关系错综复杂。这时候，手动指定每个文件的编译顺序和依赖关系就变得不切实际了。

构建工具的出现就是为了解决这个问题。它们能自动：

  • 确定源文件之间的依赖关系
  • 决定哪些文件需要重新编译
  • 按照正确的顺序编译所有文件
  • 链接生成最终的可执行文件或库

在C++生态中，最常见的构建工具组合就是 Makefile 和 CMake 。它们的关系可以这样理解：

工具 作用 类比
CMake 生成构建配置 建筑设计师
Makefile 执行实际构建 施工队
g++ 实际编译器 建筑工人

2. 环境准备

在开始之前，我们需要确保系统中有必要的工具链。对于Linux/macOS用户，大多数发行版已经预装了g++和make，但CMake可能需要单独安装。

2.1 安装必要工具

对于Ubuntu/Debian系统： 

sudo apt update
sudo apt install build-essential cmake

对于CentOS/RHEL系统： 

sudo yum groupinstall "Development Tools"
sudo yum install cmake

对于macOS用户（使用Homebrew）： 

brew install cmake

验证安装是否成功： 

g++ --version
make --version
cmake --version

你应该能看到类似这样的输出： 

g++ (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0
GNU Make 4.2.1
cmake version 3.16.3

2.2 获取MyTinySTL项目

我们将以MyTinySTL这个适合初学者的C++项目为例。首先克隆项目到本地： 

git clone https://github.com/Alinshans/MyTinySTL.git
cd MyTinySTL

项目结构通常包含以下关键部分： 

MyTinySTL/
├── CMakeLists.txt    # CMake配置文件
├── include/          # 头文件目录
├── src/              # 源文件目录
├── tests/            # 测试代码
└── build/            # 建议在此目录下构建

提示：建议在项目根目录下创建单独的 build 目录进行构建，这样可以保持源码目录的整洁。

3. 理解CMake和Makefile的工作流程

3.1 CMake的作用

CMake是一个跨平台的构建系统生成器。它不直接构建项目，而是根据 CMakeLists.txt 文件生成对应平台的构建文件：

  • 在Linux/macOS上生成Makefile
  • 在Windows上可能生成Visual Studio项目文件
  • 也可以生成其他构建系统如Ninja的配置文件

一个典型的CMake工作流程如下：

  1. 创建构建目录： mkdir build && cd build
  2. 运行CMake生成构建文件： cmake ..
  3. 使用生成的构建文件编译项目： make

3.2 Makefile的作用

Makefile是make工具使用的构建脚本，它定义了：

  • 目标文件（targets）及其依赖关系
  • 构建每个目标所需的命令
  • 文件之间的依赖关系

当你在项目目录下运行 make 时，它会：

  1. 解析Makefile
  2. 根据文件时间戳判断哪些文件需要重新编译
  3. 按照依赖关系顺序执行编译命令

4. 实际构建MyTinySTL项目

现在让我们实际构建这个项目。我们将分步骤详细解释每个命令的作用。

4.1 生成构建系统

首先进入项目目录并创建构建目录： 

cd MyTinySTL
mkdir build
cd build

然后运行CMake生成Makefile： 

cmake ..

这个命令会：

  1. 解析上一级目录中的 CMakeLists.txt 文件
  2. 检查系统环境（编译器版本、依赖等）
  3. 生成适用于当前系统的构建文件

你应该能看到类似这样的输出： 

-- The C compiler identification is GNU 9.3.0
-- The CXX compiler identification is GNU 9.3.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
...
-- Configuring done
-- Generating done
-- Build files have been written to: /path/to/MyTinySTL/build

4.2 编译项目

现在我们可以使用生成的Makefile来编译项目： 

make

这个命令会：

  1. 编译所有源文件
  2. 链接生成可执行文件和库
  3. 显示编译进度和可能的警告/错误

成功的编译会输出类似： 

Scanning dependencies of target mystl
[  5%] Building CXX object CMakeFiles/mystl.dir/src/vector.cpp.o
[ 10%] Building CXX object CMakeFiles/mystl.dir/src/list.cpp.o
...
[100%] Linking CXX static library libmystl.a
[100%] Built target mystl

4.3 运行测试（可选）

如果项目包含测试，你可以运行： 

make test

或者直接运行生成的可执行文件（如果有的话）： 

./bin/mystl_test

5. 常见问题与解决方案

在编译过程中，你可能会遇到一些问题。以下是几个常见问题及其解决方法：

5.1 找不到CMake或版本太低

错误信息： 

CMake 3.xx or higher is required. You are running version 2.8.12

解决方案： 升级CMake。对于Ubuntu/Debian： 

sudo apt remove cmake
sudo apt install cmake

如果仓库中的版本仍然太低，可以考虑从源码安装： 

wget https://github.com/Kitware/CMake/releases/download/v3.20.0/cmake-3.20.0.tar.gz
tar -xzvf cmake-3.20.0.tar.gz
cd cmake-3.20.0
./bootstrap && make && sudo make install

5.2 编译错误：缺少依赖

错误信息： 

fatal error: some_header.h: No such file or directory

解决方案：

  1. 确保所有依赖已安装
  2. 检查 CMakeLists.txt 中是否正确设置了包含路径
  3. 有时需要手动指定包含路径： 
    cmake .. -DCMAKE_INCLUDE_PATH=/path/to/headers

5.3 链接错误：未定义的引用

错误信息： 

undefined reference to `some_function()'

这通常意味着：

  • 源文件没有包含在构建中
  • 库链接顺序有问题
  • 需要的库没有链接

解决方案：

  1. 检查 CMakeLists.txt 是否包含了所有必要的源文件
  2. 确保链接了所有需要的库
  3. 尝试清理后重新构建： 
    make clean
make

6. 进阶：理解CMakeLists.txt

为了更好地控制构建过程，我们需要理解 CMakeLists.txt 的基本结构。以MyTinySTL为例，关键部分包括： 

# 设置CMake最低版本要求
cmake_minimum_required(VERSION 3.5)

# 定义项目名称
project(MyTinySTL)

# 设置C++标准
set(CMAKE_CXX_STANDARD 11)

# 包含目录
include_directories(include)

# 添加库
add_library(mystl STATIC src/vector.cpp src/list.cpp ...)

# 添加可执行文件
add_executable(mystl_test tests/test_main.cpp ...)
target_link_libraries(mystl_test mystl)

关键CMake命令解释：

命令 作用 示例
project() 定义项目名称 project(MyProject)
add_executable() 添加可执行目标 add_executable(myapp main.cpp)
add_library() 添加库目标 add_library(mylib STATIC lib.cpp)
target_link_libraries() 链接库到目标 target_link_libraries(myapp mylib)
include_directories() 添加头文件搜索路径 include_directories(include)

7. 实际项目中的构建技巧

7.1 使用外部依赖

现代C++项目经常依赖第三方库。CMake提供了多种方式来管理依赖：

  1. 使用 find_package 查找系统安装的库： 

    find_package(Boost REQUIRED)
target_link_libraries(myapp Boost::boost)

  2. 使用Git子模块或FetchContent包含第三方源码： 

    include(FetchContent)
FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG release-1.11.0
)
FetchContent_MakeAvailable(googletest)

7.2 构建类型和编译器选项

你可以通过 -DCMAKE_BUILD_TYPE 指定构建类型： 

cmake .. -DCMAKE_BUILD_TYPE=Debug  # 调试版本
cmake .. -DCMAKE_BUILD_TYPE=Release  # 优化版本

在 CMakeLists.txt 中，可以针对不同构建类型设置不同选项： 

if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    add_compile_options(-g -O0 -Wall -Wextra)
else()
    add_compile_options(-O3)
endif()

7.3 跨平台构建

CMake的一个主要优势是跨平台支持。要确保项目能在不同平台构建，需要注意：

  1. 使用平台无关的路径操作： 

    file(GLOB SOURCES "src/*.cpp")

  2. 条件判断平台特定代码： 

    if(WIN32)
    add_definitions(-DWINDOWS)
elseif(UNIX)
    add_definitions(-DLINUX)
endif()

  3. 使用CMake的生成器表达式处理复杂条件： 

    target_compile_definitions(myapp
    PRIVATE $<$<PLATFORM_ID:Windows>:WINDOWS>
            $<$<PLATFORM_ID:Linux>:LINUX>)

8. 调试构建问题

当构建失败时，可以尝试以下调试方法：

  1. 查看详细构建输出： 

    make VERBOSE=1

  2. 检查CMake缓存变量： 

    ccmake .  # 交互式查看和修改变量

  3. 清理后重新构建： 

    rm -rf * && cmake .. && make

  4. 检查编译器命令行： 

    set(CMAKE_EXPORT_COMPILE_COMMANDS ON)  # 生成compile_commands.json

注意：构建C++项目时，90%的问题都能通过"清理并重新构建"解决。当遇到奇怪的问题时，先尝试 rm -rf build && mkdir build && cd build && cmake .. && make 。

Logo
亚马逊云科技技术品牌专区