Структура проекта C
Структура проекта C — это организация каталогов для размещения исходного кода проекта на языке C, заголовочных файлов, сборочных скриптов и файлов ресурсов.
Чёткая и стандартизированная структура проекта упрощает сопровождение больших проектов на C, облегчает совместную работу нескольких человек и упрощает процессы сборки и развёртывания.
Зачем нужна стандартизированная структура проекта?
Когда новички пишут код на C, они часто сваливают все файлы в один каталог, что создаёт серьёзные проблемы по мере роста проекта.
Дублирующиеся заголовочные файлы, конфликты имён, медленная компиляция и сложность поиска кода — подобный хаос в конечном итоге делает проект трудно поддерживаемым.
Обычная структура каталогов помогает вам и вашей команде быстро понимать проект в целом, а также позволяет таким инструментам автоматизированной сборки, как Make и CMake, работать эффективно.
Стандартная структура каталогов
Ниже представлена рекомендуемая структура каталогов для типичного проекта на C, подходящая для малых и средних проектов.
Чёткие обязанности и иерархия для каждого каталога:

Подробное объяснение основных каталогов
Ниже поочерёдно объясняются обязанности и лучшие практики для каждого каталога.
src/ — каталог исходного кода
Храните все.cисходные файлы: разбивайте их на несколько файлов по модулям.
Один .c-файл на модуль, имена файлов соответствуют функциональности для быстрого поиска.
Входная функцияmain()Обычно размещается в main.c; не смешивайте с бизнес-логикой.
Пример
#include "utils.h" /* Заголовочный файл пользовательской служебной функции */
#include "database.h" /* Заголовочный файл операций с базой данных */
#include <stdio.h> /* Стандартный ввод/вывод */
int main(int argc, char *argv[]) {
/* argc: количество аргументов командной строки, argv: массив аргументов */
printf("ЗАПУСК ПРИМЕРА ПРОЕКТА НА C\n");
init_database(); /* Инициализировать подключение к базе данных */
print_version(); /* Вывести информацию о версии (из модуля utils) */
return 0; /* Вернуть 0 для обозначения нормального завершения программы */
}
include/ — Каталог заголовочных файлов
Храните все.hЗаголовочные файлы — это определения интерфейсов для связи между модулями.
Заголовочные файлы содержат только объявления (прототипы функций, структуры, макросы, перечисления), а не код реализации.
Пример
#ifndef UTILS_H /* Макрос защиты заголовочного файла, предотвращает повторное включение */
#define UTILS_H
/* Название проекта и номер версии (макроконстанты, именование всеми заглавными буквами) */
#define PROJECT_NAME "EXAMPLE"
#define VERSION_MAJOR 1
#define VERSION_MINOR 0
/* Структура: представляет 2D координатную точку */
typedef struct {
int x; /* координата X */
int y; /* координата Y */
} Point;
/* Объявление функции: вычислить расстояние между двумя точками */
double distance(Point a, Point b);
/* Объявление функции: вывод информации о версии */
void print_version(void);
#endif /* UTILS_H */
tests/ — каталог тестов
Хранит код модульных тестов; обычно один тестовый файл соответствует одному исходному модулю.
Рекомендуется использовать такие фреймворки тестирования, как CUnit и Check, либо можно написать простые тесты с утверждениями вручную.
build/ — каталог сборки
Хранит промежуточные файлы (.o), создаваемые при компиляции, и итоговый исполняемый файл.
Этот каталог автоматически создаётся и очищается системой сборки и не включается в систему контроля версий (его следует добавить в .gitignore).
lib/ — каталог сторонних библиотек
Хранит сторонние статические библиотеки (.a) или динамические библиотеки (.so / .dylib), от которых зависит проект.
Более рекомендуется использовать менеджеры пакетов (такие как vcpkg, Conan) для управления зависимостями, а не вручную копировать файлы библиотек.
doc/ — каталог документации
Хранит проектные документы, документацию API, списки изменений и т. д.
Рекомендуется использовать Doxygen для автоматической генерации документации API из комментариев в исходном коде.
Управление заголовочными файлами
Заголовочные файлы — ключевой мост для взаимодействия между модулями в проектах на C; неправильное управление может вызвать множество проблем при компиляции.
На следующей диаграмме показаны связи включения между заголовочными файлами в типичном проекте на C:

Каждый файл .c имеет соответствующий .h-файл с тем же именем; .h-файл служит публичным интерфейсом модуля.
В заголовочных файлах необходимо использоватьмакрос защиты заголовочного файла(include guard), чтобы предотвратить повторное включение.
Не определяйте глобальные переменные в заголовочных файлах. Если несколько .c-файлов включают один и тот же заголовочный файл, дублирующиеся определения глобальных переменных вызовут ошибки компоновки. Правильный подход — объявить их с помощью extern в заголовочном файле, а определить в одном .c-файле.
Система сборки
Система сборки отвечает за компиляцию исходного кода в исполняемые файлы, управление порядком компиляции, зависимостями и параметрами компилятора.
Makefile — классический инструмент сборки.
Makefile управляет процессом компиляции, определяя правила (цель, зависимости, команды).
Подходит для малых и средних проектов; предустановлен почти во всех системах Unix/Linux.
Пример
# Базовая структура Makefile: target: dependencies\n\tcommand
# Настройки компилятора
CC = gcc # Укажите компилятор C
CFLAGS = -Wall -Wextra -g # Опции компилятора: все предупреждения + отладочная информация
INCLUDE = -I./include # Путь поиска заголовочных файлов
TARGET = example_app # Имя итогового исполняемого файла
# Исходные файлы и объектные файлы
SRCS = $(wildcard src/*.c) # Автоматически собирает все .c файлы в каталоге src/
OBJS = $(SRCS:.c=.o) # Получить соответствующие имена .o файлов
# Цель по умолчанию: собрать исполняемый файл
$(TARGET): $(OBJS)
$(CC) $(CFLAGS) -o $@ $^
@echo "Сборка выполнена успешно: ./$(TARGET)"
# Правила компиляции: .c → .o
%.o: %.c
$(CC) $(CFLAGS) $(INCLUDE) -c $< -o $@
# Очистка артефактов сборки
.PHONY: clean
clean:
rm -f $(OBJS) $(TARGET)
@echo "Файлы сборки очищены"
CMake — кроссплатформенная система сборки
CMake описывает структуру проекта через CMakeLists.txt и автоматически генерирует файлы сборки для каждой платформы.
Подходит для средних и крупных проектов, требующих кросс-платформенной поддержки.
Пример
# Минимальное требование к версии CMake
cmake_minimum_required(VERSION 3.10)
# Имя проекта и язык
project(example_app C)
# Установить стандарт C в C11
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
# Собрать все исходные файлы
file(GLOB SOURCES "src/*.c")
# Определить пути поиска заголовочных файлов
include_directories(include)
# Создать исполняемый файл
add_executable(${PROJECT_NAME} ${SOURCES})
# Опционально: подключить сторонние библиотеки
# target_link_libraries(${PROJECT_NAME} PRIVATE m)
Шаги сборки CMake:
$ mkdir build && cd build $ cmake .. $ make $ ./example_app EXAMPLE C 项目启动 版本: v1.0
Процесс компиляции
Понимание всего процесса от написания исходного кода на C до его запуска помогает устранять ошибки компиляции и компоновки.
На следующей диаграмме показаны четыре этапа от файла .c до исполняемого файла:
Пошаговые команды компиляции
Вы можете использовать GCC для пошагового выполнения и наблюдать вывод на каждом этапе:
# 1. 预处理:展开所有宏和头文件 $ gcc -E src/main.c -I./include -o main.i # 2. 编译:将预处理结果转为汇编代码 $ gcc -S main.i -o main.s # 3. 汇编:将汇编代码转为目标文件 $ gcc -c main.s -o main.o # 4. 链接:将所有目标文件链接为可执行程序 $ gcc main.o utils.o -o example_app
Типичные примеры
Ниже приведён полный пример небольшого проекта на C, охватывающий весь процесс от создания каталога до компиляции и запуска.
Создание каркаса проекта
$ mkdir -p example_project/{src,include,tests,build,lib,doc}
$ tree example_project/
example_project/
├── build/
├── doc/
├── include/
├── lib/
├── src/
└── tests/
Напишите код модуля
Пример: модуль математических утилит
#include "math_utils.h" /* его собственный заголовочный файл */
#include <math.h> /* стандартная математическая библиотека, предоставляет sqrt() */
/* Вычислить евклидово расстояние между двумя точками */
double distance(Point a, Point b) {
int dx = a.x - b.x; /* разность по оси x */
int dy = a.y - b.y; /* разность по оси y */
return sqrt(dx * dx + dy * dy); /* Теорема Пифагора */
}
/* Проверить, является ли число простым */
int is_prime(int n) {
if (n < 2) return 0; /* Числа меньше 2 не являются простыми */
for (int i = 2; i * i <= n; i++) {
if (n % i == 0) return 0; /* Найден делитель, не простое число */
}
return 1; /* Делитель не найден; это простое число */
}
Пример: соответствующий заголовочный файл
#ifndef MATH_UTILS_H
#define MATH_UTILS_H
/* Структура 2D-точки */
typedef struct {
int x;
int y;
} Point;
/* Вычислить расстояние между двумя точками */
double distance(Point a, Point b);
/* Определить, является ли n простым, вернуть 1, если да, 0, если нет */
int is_prime(int n);
#endif /* MATH_UTILS_H */
Компиляция и выполнение
$ cd example_project $ mkdir build && cd build $ cmake .. -- Configuring done -- Generating done $ make [100%] Built target example_app $ ./example_app EXAMPLE 项目运行成功! Point(0,0) 到 Point(3,4) 的距离 = 5.00 7 是质数: 是
Примечания
Макросы защиты заголовочных файлов должны быть уникальными. Рекомендуется использоватьPROJECT_NAME_MODULE_NAME_Hсоглашение об именовании, чтобы избежать конфликтов имён макросов между разными проектами.
Не используйте #include "file.c" для ссылки на исходные файлы. Это приведёт к тому, что одна и та же функция будет скомпилирована несколько раз, что вызовет ошибки повторного определения. Всегда перечисляйте все .c файлы в команде компиляции или используйте Makefile/CMake для управления ими.
Сводка по назначению каталогов:
| Каталог | Обязанности | Включать ли в систему контроля версий |
|---|---|---|
| src/ | Исходные файлы .c | Да |
| include/ | Заголовочные файлы .h, публичные интерфейсы | Да |
| tests/ | Тестовый код | Да |
| build/ | Промежуточные артефакты сборки, исполняемые файлы | Нет (добавить в .gitignore) |
| lib/ | Файлы сторонних библиотек | Зависит |
| doc/ | Документация проекта | Да |
Полный пример .gitignore:
# 构建产物 build/ *.o *.out *.exe # IDE 配置 .vscode/ .idea/ # macOS .DS_Store
ЧАВО
В: Почему компилятор сообщает об ошибке 'undefined reference'?
Это ошибка этапа компоновки, означающая, что функция была объявлена, но её реализация не найдена.
Проверьте, включён ли соответствующий .c файл в команду компиляции или правильно ли скомпонован файл библиотеки.
В: Следует ли в заголовочных файлах использовать <> или ""?
Заголовочные файлы стандартной библиотеки используют <stdio.h>, а компилятор ищет в системном пути.
Пользовательские заголовочные файлы используют "utils.h"; компилятор сначала ищет в текущем каталоге, затем в системном пути.
Вопрос: В чем разница между статическими и динамическими библиотеками?
Статические библиотеки (.a) копируются в исполняемый файл во время компоновки; программа самодостаточна, но имеет большой размер.
Динамические библиотеки (.so / .dylib) загружаются во время выполнения и могут совместно использоваться несколькими программами; необходимо убедиться, что соответствующая версия существует в целевой системе.
Другие расширения