第2章：项目目录结构与构建系统

说实话，我见过太多C语言项目，代码写得挺漂亮，但一看目录结构就头疼。头文件乱放，源文件堆在一起，构建脚本更是五花八门。嗯，这一章我们就来聊聊怎么把项目骨架搭好。

经典C项目目录结构

一个成熟的项目，目录结构就是它的骨架。我个人习惯用这套结构，在多个嵌入式项目里验证过，效果不错：

project_root/
├── src/            # 源文件
│   ├── main.c
│   ├── module_a.c
│   └── module_b.c
├── include/        # 头文件
│   ├── module_a.h
│   └── module_b.h
├── lib/            # 第三方库或静态库
│   └── libfoo.a
├── test/           # 单元测试
│   ├── test_module_a.c
│   └── test_module_b.c
├── doc/            # 文档
│   └── design.md
├── build/          # 构建输出（可选）
├── Makefile        # 构建脚本
└── CMakeLists.txt  # CMake配置

你想想看，这套结构有什么好处？职责清晰。新同事来了，一看就知道代码放哪，测试放哪。我在项目中遇到过好几次，因为目录混乱导致头文件引用错误，编译半天过不了。

头文件与源文件的组织原则

这里有个坑，我刚开始做项目时也踩过。头文件里放函数实现，或者源文件里写了一大堆全局变量声明。说白了，就是没搞清楚接口和实现的区别。

我的建议是：

• 头文件只放声明：函数原型、宏定义、类型定义、extern变量声明。别放实现。
• 源文件放实现：函数体、静态变量、内部辅助函数。
• 每个模块一对文件：module_a.h + module_a.c，一一对应。

举个例子，一个简单的LED驱动模块：

// include/led_driver.h
#ifndef LED_DRIVER_H
#define LED_DRIVER_H

#include <stdint.h>

void led_init(void);
void led_on(uint8_t led_id);
void led_off(uint8_t led_id);

#endif // LED_DRIVER_H

// src/led_driver.c
#include "led_driver.h"
#include <avr/io.h>  // 硬件相关

static uint8_t led_state = 0;

void led_init(void) {
    DDRB |= 0x0F;  // 设置PB0-PB3为输出
    led_state = 0;
}

void led_on(uint8_t led_id) {
    if (led_id < 4) {
        PORTB |= (1 << led_id);
        led_state |= (1 << led_id);
    }
}

void led_off(uint8_t led_id) {
    if (led_id < 4) {
        PORTB &= ~(1 << led_id);
        led_state &= ~(1 << led_id);
    }
}

Makefile实战

Makefile这东西，说简单也简单，说复杂能写几百行。我一般用最精简的写法，够用就行。来看一个实际项目的Makefile：

CC = gcc
CFLAGS = -Wall -Wextra -Iinclude
LDFLAGS = -Llib -lfoo

SRC_DIR = src
OBJ_DIR = build
TARGET = myapp

SRCS = $(wildcard $(SRC_DIR)/*.c)
OBJS = $(patsubst $(SRC_DIR)/%.c, $(OBJ_DIR)/%.o, $(SRCS))

all: $(TARGET)

$(TARGET): $(OBJS)
	$(CC) $^ -o $@ $(LDFLAGS)

$(OBJ_DIR)/%.o: $(SRC_DIR)/%.c | $(OBJ_DIR)
	$(CC) $(CFLAGS) -c $< -o $@

$(OBJ_DIR):
	mkdir -p $@

clean:
	rm -rf $(OBJ_DIR) $(TARGET)

.PHONY: all clean

这段Makefile做了几件事：自动扫描src目录下的所有.c文件，编译到build目录，最后链接成可执行文件。我曾经在一个项目里，因为手动列出源文件，漏了一个.c文件，结果链接报错找了半天。用wildcard自动扫描，省心多了。

CMake实战

如果项目要跨平台，或者依赖关系复杂，我建议用CMake。它比Makefile更现代化，语法也更友好。来看对应的CMakeLists.txt：

cmake_minimum_required(VERSION 3.10)
project(myapp C)

set(CMAKE_C_STANDARD 11)

# 源文件
file(GLOB SOURCES "src/*.c")

# 头文件路径
include_directories(include)

# 可执行文件
add_executable(${PROJECT_NAME} ${SOURCES})

# 链接库
target_link_libraries(${PROJECT_NAME} foo)

使用CMake的步骤：

1. 在项目根目录创建build文件夹
2. 进入build，运行 cmake ..
3. 运行 make 或 cmake --build .

我个人更喜欢CMake，因为它能自动处理依赖关系，而且生成的是平台原生的构建文件。在嵌入式项目里，我经常用CMake配合交叉编译工具链，一套脚本搞定多个平台。

构建系统的选择建议

场景	推荐工具	理由
小型项目（少于10个源文件）	Makefile	简单直接，无需额外依赖
中型项目（10-50个源文件）	CMake	跨平台，依赖管理方便
大型项目（50+源文件，多模块）	CMake + 模块化	支持子目录、测试框架集成
嵌入式裸机项目	Makefile	对编译选项控制更精细

你想想看，选构建工具其实跟选工具一样，顺手最重要。我见过有人用CMake写了个三行的小项目，也见过有人用Makefile管理几百个文件。没有绝对的对错，但一致性很重要——团队里所有人都得用同一套。

知识体系结构图

下面这张图，是我梳理的本章知识脉络。你可以把它当作一个检查清单，看看自己掌握了哪些：

这张图把本章的三个核心模块串起来了。目录结构是骨架，头文件组织是肌肉，构建系统是血液。三者缺一不可。

好了，这一章的内容就这些。记住，好的项目结构不是约束，而是解放。它让你不用操心「文件放哪」，专心写代码。