Structure d'un projet C

La structure d'un projet C fait référence à l'agencement des répertoires pour organiser le code source d'un projet en langage C, les fichiers d'en-tête, les scripts de compilation et les fichiers de ressources.

Une structure de projet claire et normalisée rend les grands projets C faciles à maintenir, facilite la collaboration entre plusieurs personnes et simplifie les processus de compilation et de déploiement.


Pourquoi une structure de projet normalisée est-elle nécessaire ?

Lorsque les débutants écrivent du code C, ils ont souvent tendance à mettre tous les fichiers dans un seul répertoire, ce qui cause de graves problèmes à mesure que le projet grandit.

Des fichiers d'en-tête dupliqués, des conflits de nommage, une compilation lente et une difficulté à localiser le code — ce genre de chaos finit par rendre le projet difficile à maintenir.

Une structure de répertoires conventionnelle vous aide, vous et votre équipe, à comprendre rapidement l'ensemble du projet, et permet également aux outils de build automatisés tels que Make et CMake de fonctionner efficacement.


Structure de répertoires standard

Voici une structure de répertoires recommandée pour un projet C typique, adaptée aux projets de petite et moyenne taille.

Des responsabilités et une hiérarchie claires pour chaque répertoire :


Explication détaillée des répertoires principaux

La suite explique les responsabilités et les bonnes pratiques de chaque répertoire, une par une.

src/ — répertoire du code source

Stocker tous les.cfichiers source : divisez-les en plusieurs fichiers par module.

Un fichier .c par module, avec des noms de fichiers correspondant à la fonctionnalité pour un repérage rapide.

Fonction d'entréemain()généralement placée dans main.c ; ne mélangez pas de logique métier.

Exemple

/* Chemin du fichier : src/main.c */
#include "utils.h" /* Fichier d'en-tête de fonctions utilitaires personnalisées */
#include "database.h" /* Fichier d'en-tête des opérations de base de données */
#include <stdio.h> /* Entrée/sortie standard */

int main(int argc, char *argv[]) {
    /* argc : nombre d'arguments de ligne de commande, argv : tableau d'arguments */
    printf("Démarrage du projet C d'exemple\n");

    init_database();     /* Initialiser la connexion à la base de données */
    print_version();     /* Afficher les informations de version (du module utils) */

    return 0;            /* Retourner 0 pour indiquer une sortie normale du programme */
}

include/ — Répertoire des fichiers d'en-tête

Stocker tous.hLes fichiers d'en-tête sont les définitions d'interface pour la communication entre modules.

Les fichiers d'en-tête contiennent uniquement des déclarations (prototypes de fonctions, structures, macros, énumérations), et non du code d'implémentation.

Exemple

/* Chemin du fichier : include/utils.h */
#ifndef UTILS_H /* Macro de garde d'en-tête, empêche l'inclusion en double */
#define UTILS_H

/* Nom du projet et numéro de version (constantes macro, nommage tout en majuscules) */
#define PROJECT_NAME "EXAMPLE"
#define VERSION_MAJOR 1
#define VERSION_MINOR 0

/* Structure : représente un point de coordonnées 2D */
typedef struct {
    int x;              /* Coordonnée X */
    int y;              /* Coordonnée Y */
} Point;

/* Déclaration de fonction : calculer la distance entre deux points */
double distance(Point a, Point b);

/* Déclaration de fonction : afficher les informations de version */
void print_version(void);

#endif /* UTILS_H */

tests/ — répertoire de tests

Stocke le code de tests unitaires ; généralement un fichier de test correspond à un module source.

Il est recommandé d'utiliser des frameworks de test tels que CUnit et Check, ou vous pouvez écrire manuellement de simples tests d'assertion.

build/ — répertoire de compilation

Stocke les fichiers intermédiaires (.o) générés par la compilation et l'exécutable final.

Ce répertoire est automatiquement généré et nettoyé par le système de build et n'est pas inclus dans le contrôle de version (il doit être ajouté à .gitignore).

lib/ — répertoire des bibliothèques tierces

Stocke les bibliothèques tierces statiques (.a) ou dynamiques (.so / .dylib) dont dépend le projet.

Il est davantage recommandé d'utiliser des gestionnaires de paquets (tels que vcpkg, Conan) pour gérer les dépendances plutôt que de copier manuellement les fichiers de bibliothèque.

doc/ — répertoire de documentation

Stocke les documents de conception du projet, la documentation d'API, les journaux de modification, etc.

Il est recommandé d'utiliser Doxygen pour générer automatiquement la documentation d'API à partir des commentaires du code source.


Gestion des fichiers d'en-tête

Les fichiers d'en-tête sont le pont clé pour la collaboration entre modules dans les projets C ; une mauvaise gestion peut causer de nombreux problèmes de compilation.

Le diagramme suivant montre les relations de référence entre les fichiers d'en-tête dans un projet C typique :

Chaque fichier .c a un fichier .h correspondant du même nom ; le fichier .h sert d'interface publique du module.

Les fichiers d'en-tête doivent utiliserla macro de garde de fichier d'en-tête(garde d'inclusion) pour empêcher une inclusion en double.

Ne définissez pas de variables globales dans les fichiers d'en-tête. Si plusieurs fichiers .c incluent le même fichier d'en-tête, des définitions en double de variables globales provoqueront des erreurs de liaison. L'approche correcte consiste à les déclarer avec extern dans le fichier d'en-tête et à les définir dans un seul fichier .c.


Système de compilation

Le système de build est responsable de la compilation du code source en exécutables, de la gestion de l'ordre de compilation, des dépendances et des options du compilateur.

Makefile — outil de build classique.

Makefile contrôle le processus de compilation en définissant des règles (cible, dépendances, commandes).

Convient aux petits et moyens projets ; préinstallé sur presque tous les systèmes Unix/Linux.

Exemple

# Chemin du fichier : Makefile
# Structure de base du Makefile : cible : dépendances\n\tcommande

# Paramètres du compilateur
CC = gcc                    # Spécifie le compilateur C
CFLAGS = -Wall -Wextra -g      # Options du compilateur : tous les avertissements + informations de débogage
INCLUDE = -I./include           # Chemin de recherche des fichiers d'en-tête
TARGET = example_app            # Nom du fichier exécutable final

# Fichiers sources et fichiers objets
SRCS = $(wildcard src/*.c)   # Collecte automatiquement tous les fichiers .c sous src/
OBJS = $(SRCS:.c=.o)         # Déduit les noms des fichiers .o correspondants

# Cible par défaut : construire l'exécutable
$(TARGET): $(OBJS)
        $(CC) $(CFLAGS) -o $@ $^
        @echo "Compilation réussie : ./$(TARGET)"

# Règles de compilation : .c → .o
%.o: %.c
        $(CC) $(CFLAGS) $(INCLUDE) -c $< -o $@

# Nettoyer les artefacts de compilation
.PHONY: clean
clean:
        rm -f $(OBJS) $(TARGET)
        @echo "Fichiers de compilation nettoyés"

CMake — système de compilation multiplateforme

CMake décrit la structure du projet via CMakeLists.txt et génère automatiquement les fichiers de build pour chaque plateforme.

Adapté aux projets de taille moyenne à grande qui nécessitent une prise en charge multiplateforme.

Exemple

# Chemin du fichier : CMakeLists.txt
# Version minimale requise de CMake
cmake_minimum_required(VERSION 3.10)

# Nom du projet et langage
project(example_app C)

# Définir le standard C sur C11
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)

# Collecter tous les fichiers sources
file(GLOB SOURCES "src/*.c")

# Définir les chemins de recherche des fichiers d'en-tête
include_directories(include)

# Générer le fichier exécutable
add_executable(${PROJECT_NAME} ${SOURCES})

# Facultatif : lier des bibliothèques tierces
# target_link_libraries(${PROJECT_NAME} PRIVATE m)

Étapes de construction CMake :

$ mkdir build && cd build
$ cmake ..
$ make
$ ./example_app
EXAMPLE C 项目启动
版本: v1.0

Processus de compilation

Comprendre l'ensemble du processus du code source C, de l'écriture à l'exécution, aide à résoudre les erreurs de compilation et d'édition de liens.

Le diagramme suivant montre les quatre étapes d'un fichier .c à un exécutable :

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)

Commandes de compilation étape par étape

Vous pouvez utiliser GCC pour l'exécuter étape par étape et observer la sortie à chaque étape :

# 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

Exemples courants

Voici un exemple complet de petit projet C, couvrant tout le processus, de la création du répertoire à la compilation et à l'exécution.

Créer le squelette du projet

$ mkdir -p example_project/{src,include,tests,build,lib,doc}
$ tree example_project/
example_project/
├── build/
├── doc/
├── include/
├── lib/
├── src/
└── tests/

Écrire le code du module

Exemple : module d’utilitaires mathématiques

/* Chemin du fichier : src/math_utils.c */
#include "math_utils.h" /* son propre fichier d'en-tête */
#include <math.h> /* bibliothèque mathématique standard, fournit sqrt() */

/* Calculer la distance euclidienne entre deux points */
double distance(Point a, Point b) {
    int dx = a.x - b.x;          /* différence selon l’axe x */
    int dy = a.y - b.y;          /* différence selon l’axe y */
    return sqrt(dx * dx + dy * dy);  /* Théorème de Pythagore */
}

/* Vérifier si un nombre est premier */
int is_prime(int n) {
    if (n < 2) return 0;         /* Les nombres inférieurs à 2 ne sont pas premiers */
    for (int i = 2; i * i <= n; i++) {
        if (n % i == 0) return 0; /* Facteur trouvé, pas un nombre premier */
    }
    return 1;                    /* Aucun facteur trouvé ; c'est un nombre premier */
}

Exemple : fichier d'en-tête correspondant

/* Chemin du fichier : include/math_utils.h */
#ifndef MATH_UTILS_H
#define MATH_UTILS_H

/* Structure de point 2D */
typedef struct {
    int x;
    int y;
} Point;

/* Calculer la distance entre deux points */
double distance(Point a, Point b);

/* Détermine si n est premier, renvoie 1 si oui, 0 sinon */
int is_prime(int n);

#endif /* MATH_UTILS_H */

Compilation et exécution

$ 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 是质数: 是

Notes

Les macros de garde d'en-tête doivent être uniques. Il est recommandé d'utiliserPROJECT_NAME_MODULE_NAME_Hcomme convention de nommage pour éviter les conflits de noms de macros entre différents projets.

N'utilisez pas #include "file.c" pour référencer des fichiers source. Cela entraînera la compilation multiple de la même fonction, provoquant des erreurs de définition en double. Listez toujours tous les fichiers .c dans la commande de compilation, ou utilisez Makefile/CMake pour les gérer.

Résumé des responsabilités des répertoires :

RépertoireResponsabilitésInclusion dans le contrôle de version
src/fichiers source .cOui
include/fichiers d'en-tête .h, interfaces publiquesOui
tests/Code de testOui
build/Artefacts intermédiaires de compilation, fichiers exécutablesNon (à ajouter à .gitignore)
lib/Fichiers de bibliothèques tiercesCela dépend
doc/Documentation du projetOui

Un exemple complet de .gitignore :

# 构建产物
build/
*.o
*.out
*.exe

# IDE 配置
.vscode/
.idea/

# macOS
.DS_Store

FAQ

Q : Pourquoi le compilateur signale-t-il une erreur 'undefined reference' ?

Il s'agit d'une erreur de liaison, indiquant que la fonction a été déclarée mais que son implémentation n'a pas été trouvée.

Vérifiez si le fichier .c correspondant est inclus dans la commande de compilation, ou si le fichier de bibliothèque est correctement lié.

Q : Les fichiers d'en-tête doivent-ils utiliser <> ou "" ?

Les en-têtes de la bibliothèque standard utilisent <stdio.h>, et le compilateur recherche dans le chemin système.

Les en-têtes personnalisés utilisent "utils.h" ; le compilateur recherche d'abord le répertoire courant, puis le chemin système.

Q : Quelle est la différence entre les bibliothèques statiques et dynamiques ?

Les bibliothèques statiques (.a) sont copiées dans l'exécutable au moment de l'édition de liens ; le programme est autonome mais volumineux.

Les bibliothèques dynamiques (.so / .dylib) sont chargées au moment de l'exécution et peuvent être partagées par plusieurs programmes ; vous devez vous assurer que la version correspondante existe sur le système cible.

autres extensions