Структура проекта C

Структура проекта C — это организация каталогов для размещения исходного кода проекта на языке C, заголовочных файлов, сборочных скриптов и файлов ресурсов.

Чёткая и стандартизированная структура проекта упрощает сопровождение больших проектов на C, облегчает совместную работу нескольких человек и упрощает процессы сборки и развёртывания.


Зачем нужна стандартизированная структура проекта?

Когда новички пишут код на C, они часто сваливают все файлы в один каталог, что создаёт серьёзные проблемы по мере роста проекта.

Дублирующиеся заголовочные файлы, конфликты имён, медленная компиляция и сложность поиска кода — подобный хаос в конечном итоге делает проект трудно поддерживаемым.

Обычная структура каталогов помогает вам и вашей команде быстро понимать проект в целом, а также позволяет таким инструментам автоматизированной сборки, как Make и CMake, работать эффективно.


Стандартная структура каталогов

Ниже представлена рекомендуемая структура каталогов для типичного проекта на C, подходящая для малых и средних проектов.

Чёткие обязанности и иерархия для каждого каталога:


Подробное объяснение основных каталогов

Ниже поочерёдно объясняются обязанности и лучшие практики для каждого каталога.

src/ — каталог исходного кода

Храните все.cисходные файлы: разбивайте их на несколько файлов по модулям.

Один .c-файл на модуль, имена файлов соответствуют функциональности для быстрого поиска.

Входная функцияmain()Обычно размещается в main.c; не смешивайте с бизнес-логикой.

Пример

/* Путь к файлу: src/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Заголовочные файлы — это определения интерфейсов для связи между модулями.

Заголовочные файлы содержат только объявления (прототипы функций, структуры, макросы, перечисления), а не код реализации.

Пример

/* Путь к файлу: include/utils.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
# Базовая структура 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 и автоматически генерирует файлы сборки для каждой платформы.

Подходит для средних и крупных проектов, требующих кросс-платформенной поддержки.

Пример

# Путь к файлу: 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 до исполняемого файла:

Stage 1: Preprocessing Preprocessing Preprocessing Expand #include and #defineArrow 1→2Stage 2: Compilation Compile Compilation C → assembly codeArrow 2→3Stage 3: Assembly Assembly Assembly Assembly → .o object fileArrow 3→4Stage 4: Linking Links Linking .o + libraries → executable fileOutput artifact labels→ .i file → .s file → .o file → executable filegcc command gcc -E → -S → -c → (ld)

Пошаговые команды компиляции

Вы можете использовать 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/

Напишите код модуля

Пример: модуль математических утилит

/* Путь к файлу: src/math_utils.c */
#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;                    /* Делитель не найден; это простое число */
}

Пример: соответствующий заголовочный файл

/* Путь к файлу: include/math_utils.h */
#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) загружаются во время выполнения и могут совместно использоваться несколькими программами; необходимо убедиться, что соответствующая версия существует в целевой системе.

Другие расширения