Lập trình đa tệp, Preprocessor & Công cụ Build trong C

Khi dự án C phát triển lớn hơn vài trăm dòng code, việc nhồi nhét tất cả vào một file duy nhất trở nên bất khả thi. Trong bài học này, chúng ta sẽ học cách tổ chức mã nguồn chuyên nghiệp với nhiều file, làm chủ bộ tiền xử lý (Preprocessor) mạnh mẽ của C, và sử dụng các công cụ build tự động.

1. Tại sao cần chia mã nguồn thành nhiều file?

Trong thực tế, các dự án phần mềm thường có hàng nghìn đến hàng triệu dòng code. Viết tất cả vào một file duy nhất sẽ gặp phải nhiều vấn đề nghiêm trọng:

• Khó bảo trì: File quá dài khiến việc đọc, tìm kiếm và sửa lỗi trở nên cực kỳ khó khăn.
• Không thể làm việc nhóm: Nhiều lập trình viên không thể cùng chỉnh sửa một file mà không xung đột (merge conflicts).
• Biên dịch chậm: Mỗi lần thay đổi nhỏ, toàn bộ file phải được biên dịch lại từ đầu.

Giải pháp là tách mã nguồn thành các module theo nguyên tắc Separation of Concerns (Phân tách mối quan tâm):

• File tiêu đề (.h) - Interface: Khai báo "giao diện" công khai: struct, typedef, nguyên mẫu hàm, macro, hằng số.
• File mã nguồn (.c) - Implementation: Định nghĩa chi tiết các hàm, chứa các hàm nội bộ (static).

Lợi ích lớn nhất: biên dịch gia tăng (Incremental Compilation) - chỉ cần biên dịch lại file nào bị thay đổi, tiết kiệm rất nhiều thời gian cho dự án lớn.

2. Header Files & Source Files

Một module trong C thường gồm một cặp file: .h và .c cùng tên.

Nội dung của file Header (.h)

• Định nghĩa struct và typedef
• Nguyên mẫu hàm (Function prototypes)
• Macro và hằng số (#define)
• Khai báo kiểu dữ liệu (enum, union)

Nội dung của file Source (.c)

• Định nghĩa (implementation) các hàm đã khai báo trong .h
• Các hàm nội bộ đánh dấu static (không công khai ra ngoài)
• Biến toàn cục nội bộ (static ở file scope)

Hai cách #include

// System libraries - searched on the system include path
#include <stdio.h>
#include <stdlib.h>

// Project headers - the current directory is searched first
#include "student.h"
#include "utils/math_helper.h"

Khác biệt nằm ở chỗ trình biên dịch tìm file ở đâu trước: <stdio.h> chỉ được tìm trong các thư mục hệ thống, còn "student.h" được tìm trong thư mục chứa file .c hiện tại trước, không thấy mới tìm tiếp ra ngoài. Quy ước là: thư viện chuẩn dùng ngoặc nhọn, file của chính dự án dùng ngoặc kép.

3. Header Guards & #pragma once

Khi nhiều file .c cùng #include một file header, hoặc các header include lẫn nhau (circular includes), trình biên dịch sẽ gặp lỗi định nghĩa trùng lặp (Redefinition error). Header Guards giải quyết vấn đề này.

Cách truyền thống: #ifndef / #define / #endif

#ifndef STUDENT_H    // If STUDENT_H has not been defined yet...
#define STUDENT_H    // ...then define it right now

#include <stdio.h>

typedef struct {
    char name[50];
    int age;
    float gpa;
} Student;

// Function prototypes
void printStudent(Student s);
Student createStudent(const char* name, int age, float gpa);

#endif // STUDENT_H  // End of the guarded block

Hãy đọc lại 2 dòng đầu như một câu điều kiện: lần #include đầu tiên, STUDENT_H chưa tồn tại nên toàn bộ nội dung được nạp và macro đó được định nghĩa. Lần #include thứ hai (từ một file khác), STUDENT_H đã có, #ifndef sai, nên cả khối bị bỏ qua — không còn lỗi định nghĩa trùng lặp.

Cách hiện đại: #pragma once

#pragma once là chỉ thị không chuẩn (non-standard) nhưng được hầu hết trình biên dịch hiện đại hỗ trợ (GCC, Clang, MSVC). Ưu điểm: ngắn gọn, không lo đặt tên trùng macro.

#pragma once

#include <stdio.h>

typedef struct {
    char name[50];
    int age;
    float gpa;
} Student;

void printStudent(Student s);
Student createStudent(const char* name, int age, float gpa);

Ví dụ hoàn chỉnh: student.h + student.c + main.c

#include "student.h"
#include <string.h>

// Internal helper - only used inside this file
static void capitalize(char* str) {
    if (str[0] >= 'a' && str[0] <= 'z') {
        str[0] -= 32;
    }
}

Student createStudent(const char* name, int age, float gpa) {
    Student s;
    strncpy(s.name, name, 49);
    s.name[49] = '\0';
    capitalize(s.name);
    s.age = age;
    s.gpa = gpa;
    return s;
}

void printStudent(Student s) {
    printf("Name: %s | Age: %d | GPA: %.2f\n", s.name, s.age, s.gpa);
}

#include <stdio.h>
#include "student.h"

int main() {
    Student s = createStudent("nguyen van a", 20, 8.5);
    printStudent(s);
    return 0;
}

Chú ý là main.c chỉ #include "student.h" chứ không bao giờ include student.c. File header cho trình biên dịch biết hàm createStudent tồn tại và có kiểu gì; phần thân hàm nằm ở student.c và chỉ được ghép vào ở bước liên kết. Vì thế lệnh biên dịch phải liệt kê cả hai file .c: gcc main.c student.c -o demo (file .h không bao giờ đưa vào dòng lệnh).

4. Phạm vi liên kết: extern, static & Compilation Units

Từ khóa extern: Chia sẻ biến/hàm giữa các file

extern khai báo rằng một biến hoặc hàm được định nghĩa ở file khác. Nó không cấp phát bộ nhớ mới, chỉ "hứa" với trình biên dịch rằng biến đó tồn tại ở đâu đó.

// Define the global variables (memory is allocated here)
int max_connections = 100;
const char* app_name = "MyApp";

#include <stdio.h>

// extern declarations - use the variables defined in config.c
extern int max_connections;
extern const char* app_name;

void startServer() {
    printf("Starting %s with max %d connections\n", app_name, max_connections);
}

Điểm mấu chốt: config.c định nghĩa biến (cấp phát bộ nhớ thật), còn server.c chỉ khai báo rằng nó tồn tại ở đâu đó. Nếu bạn bỏ chữ extern ở server.c, cả hai file sẽ cùng định nghĩa max_connections và Linker báo multiple definition.

Từ khóa static ở phạm vi file: Internal Linkage

Khi đặt static trước biến toàn cục hoặc hàm, phạm vi của chúng bị giới hạn chỉ trong file nguồn hiện tại. Các file khác không thể truy cập, giúp đóng gói (encapsulation) an toàn.

static int log_count = 0;  // Visible only inside this file

static void writeToFile(const char* msg) {  // Internal function
    // ... write the message to the log file
}

// Public function (external linkage) - other files may call it
void logMessage(const char* msg) {
    log_count++;
    writeToFile(msg);
}

Cả log_count lẫn writeToFile đều không thể nhìn thấy từ file khác, dù có khai báo extern đúng tên. Chỉ logMessage là cửa ra vào công khai của module này — đây chính là cách C đóng gói dữ liệu khi không có private như các ngôn ngữ hướng đối tượng.

Translation Unit & Lỗi Linker thường gặp

Một Translation Unit (đơn vị biên dịch) là một file .c sau khi đã xử lý tất cả #include và macro. Mỗi translation unit được biên dịch độc lập thành file object (.o), sau đó Linker ghép chúng lại.

5. Bộ tiền xử lý C (C Preprocessor) chuyên sâu

C Preprocessor chạy trước trình biên dịch, xử lý các chỉ thị bắt đầu bằng #. Nó thực hiện thay thế văn bản thuần túy (text substitution), không hiểu ngữ nghĩa C.

Macro dạng đối tượng (Object-like macros)

#define PI          3.14159265358979
#define MAX_SIZE    1024
#define APP_VERSION "2.1.0"

// Using them
double area = PI * r * r;
char buffer[MAX_SIZE];

Preprocessor chỉ thay thế văn bản: mọi chỗ viết MAX_SIZE đều bị đổi thành 1024 trước khi trình biên dịch nhìn thấy dòng code. Nó không có kiểu dữ liệu, nên cũng không có kiểm tra kiểu — đó vừa là sức mạnh vừa là cạm bẫy của macro.

Macro dạng hàm (Function-like macros)

// ALWAYS wrap both the parameters and the whole expression in brackets!
#define MAX(a, b)       ((a) > (b) ? (a) : (b))
#define SQUARE(x)       ((x) * (x))
#define ABS(x)          ((x) < 0 ? -(x) : (x))

// What goes wrong without the brackets:
// #define BAD_SQUARE(x)  x * x
// BAD_SQUARE(2 + 3) => 2 + 3 * 2 + 3 = 11 (wrong! 25 was expected)
// SQUARE(2 + 3)     => ((2 + 3) * (2 + 3)) = 25 (correct!)

// Warning: macros and side effects!
// int a = 5;
// SQUARE(a++) => ((a++) * (a++)) => a is incremented twice! (undefined behaviour)

Hai dòng comment cuối là bài học đắt giá nhất về macro. Vì đây là thay thế văn bản chứ không phải lời gọi hàm, tham số truyền vào sẽ được viết ra nhiều lần trong biểu thức kết quả. Với SQUARE(a++), biến a bị tăng hai lần trong cùng một biểu thức — đó là undefined behavior, chứ không phải "kết quả sai" có thể đoán trước.

#undef — Hủy định nghĩa một macro

#define BUFFER_SIZE 256
// ... BUFFER_SIZE is used here ...

#undef BUFFER_SIZE          // Undefine it
#define BUFFER_SIZE 1024    // Define it again with a new value

Stringification (#) và Token Pasting (##)

#include <stdio.h>

// Stringification (#) - turn the parameter into a string literal
#define PRINT_VAR(var)  printf(#var " = %d\n", var)

// Token pasting (##) - glue tokens together
#define DECLARE_PAIR(type, name) \
    type name##_first;           \
    type name##_second;

int main() {
    int score = 95;
    PRINT_VAR(score);    // => printf("score" " = %d\n", score);
                         // => prints: score = 95

    DECLARE_PAIR(int, point)  // Expands to: int point_first; int point_second;
    point_first = 10;
    point_second = 20;

    return 0;
}

Hai toán tử này chỉ tồn tại trong preprocessor: #var biến tên tham số thành chuỗi "score", còn name##_first ghép hai token thành một tên biến mới point_first. Chúng thường dùng để sinh code lặp lại (macro log, macro khai báo hàng loạt) mà không phải gõ tay từng dòng.

Macro định nghĩa sẵn (Predefined Macros)

#include <stdio.h>

int main() {
    printf("File: %s\n", __FILE__);        // Current file name
    printf("Line: %d\n", __LINE__);        // Current line number
    printf("Function: %s\n", __func__);    // Current function name (C99)
    printf("Date: %s\n", __DATE__);        // Compilation date
    printf("Time: %s\n", __TIME__);        // Compilation time
    printf("C Standard: %ld\n", __STDC_VERSION__); // C version (e.g. 201112L = C11)
    return 0;
}

Những macro này do chính trình biên dịch điền vào, nên giá trị của __LINE__ thay đổi theo đúng dòng bạn đặt nó. Đó là lý do macro log ở phần dưới in được vị trí chính xác của lệnh log mà không cần bạn truyền tay tên file.

Variadic Macros (macro có số lượng tham số thay đổi)

#include <stdio.h>

// LOG macro - prints the file name and line number too
#define LOG(fmt, ...) \
    printf("[%s:%d] " fmt "\n", __FILE__, __LINE__, ##__VA_ARGS__)

// ##__VA_ARGS__: the ## handles the case where no extra argument is passed
// (it removes the dangling comma when the argument list is empty)

int main() {
    LOG("Server started");              // [variadic_macros.c:11] Server started
    LOG("Port: %d", 8080);              // [variadic_macros.c:12] Port: 8080
    LOG("Host: %s, Port: %d", "localhost", 3000);
    return 0;
}

__VA_ARGS__ nhận toàn bộ phần tham số còn lại. Điểm đáng chú ý là ## đứng trước nó: khi bạn gọi LOG("Server started") mà không truyền thêm gì, dấu phẩy thừa sẽ bị xóa đi — thiếu ## thì lần gọi đó không biên dịch được. (Đây là mở rộng của GCC/Clang; C++20 và C23 chuẩn hóa cách khác là __VA_OPT__.)

6. Biên dịch có điều kiện (Conditional Compilation)

Biên dịch có điều kiện cho phép giữ lại hoặc loại bỏ hẳn từng đoạn mã nguồn dựa trên một điều kiện được xét ngay tại thời điểm biên dịch. Đây là công cụ cực kỳ mạnh để viết mã đa nền tảng (cross-platform) và để bật/tắt các tính năng theo cấu hình.

Các chỉ thị cơ bản

#include <stdio.h>

// Define DEBUG at compile time: gcc -DDEBUG main.c
// Or define it directly in the source:
// #define DEBUG

#ifdef DEBUG
    #define DBG_PRINT(fmt, ...) \
        fprintf(stderr, "[DEBUG %s:%d] " fmt "\n", __FILE__, __LINE__, ##__VA_ARGS__)
#else
    #define DBG_PRINT(fmt, ...) // Expands to nothing (stripped out of a release build)
#endif

// Check the C standard version
#if __STDC_VERSION__ >= 201112L
    #define C_VERSION "C11 or later"
#elif __STDC_VERSION__ >= 199901L
    #define C_VERSION "C99"
#else
    #define C_VERSION "C89/C90"
#endif

int main() {
    DBG_PRINT("Program started");
    printf("Compiled with: %s\n", C_VERSION);
    DBG_PRINT("Value of x = %d", 42);
    return 0;
}

Điểm cần nhớ: khi biên dịch bình thường (gcc conditional.c), DBG_PRINT nở ra thành rỗng — các dòng debug biến mất hoàn toàn khỏi file thực thi, không tốn một lệnh máy nào. Chỉ khi thêm cờ -DDEBUG chúng mới xuất hiện. Hãy thử chạy cả hai cách để thấy sự khác biệt.

Mã nguồn đa nền tảng (Cross-platform code)

#include <stdio.h>

// Detect the operating system at compile time
#if defined(_WIN32) || defined(_WIN64)
    #include <windows.h>
    #define CLEAR_SCREEN() system("cls")
    #define PATH_SEP '\\'
#elif defined(__linux__) || defined(__APPLE__)
    #include <unistd.h>
    #define CLEAR_SCREEN() system("clear")
    #define PATH_SEP '/'
#else
    #error "Unsupported platform!"
#endif

// Feature toggles
#ifndef MAX_USERS
    #define MAX_USERS 100  // Default value when none is passed on the command line
#endif

int main() {
    printf("Path separator: '%c'\n", PATH_SEP);
    printf("Max users: %d\n", MAX_USERS);
    // Compile with: gcc -DMAX_USERS=500 platform.c
    return 0;
}

#error ở nhánh #else là một thói quen tốt: nếu ai đó biên dịch trên nền tảng bạn chưa hỗ trợ, họ nhận được một thông báo rõ ràng ngay lúc biên dịch, thay vì một lỗi khó hiểu về PATH_SEP không tồn tại.

7. Quy trình biên dịch đa file & Makefile nâng cao

Biên dịch thủ công (Manual compilation)

Quy trình biên dịch đa file gồm 2 bước: biên dịch từng file .c thành một file object (.o), rồi liên kết (link) tất cả chúng lại thành file thực thi.

# Step 1: compile each .c file into a .o object file
gcc -c main.c -o main.o
gcc -c student.c -o student.o
gcc -c utils.c -o utils.o

# Step 2: link every .o file into one executable
gcc main.o student.o utils.o -o my_program

# Or do it all in one command (convenient, but not incremental)
gcc main.c student.c utils.c -o my_program

Makefile và biến dựng sẵn của Make

# Variables
CC      = gcc
CFLAGS  = -Wall -Wextra -std=c11
TARGET  = my_program
SRCS    = main.c student.c utils.c
OBJS    = $(SRCS:.c=.o)   # Rewrites .c to .o: main.o student.o utils.o

# Default rule
all: $(TARGET)

# Link the object files
$(TARGET): $(OBJS)
	$(CC) $(OBJS) -o $(TARGET)

# Pattern rule: compile any .c file into a .o
%.o: %.c
	$(CC) $(CFLAGS) -c $< -o $@

# Clean up generated files
clean:
	rm -f $(OBJS) $(TARGET)

# Phony targets (not real files)
.PHONY: all clean

Giá trị thật của Makefile nằm ở pattern rule %.o: %.c: make so sánh thời gian sửa của student.c với student.o, và chỉ biên dịch lại đúng file nào mới hơn. Đây chính là biên dịch gia tăng đã nhắc ở mục 1 — sửa một file trong dự án 500 file thì chỉ biên dịch lại một file.

CMake — Công cụ build đa nền tảng

Với các dự án lớn cần hỗ trợ nhiều hệ điều hành và nhiều trình biên dịch, CMake là công cụ build phổ biến nhất. CMake không tự biên dịch mà sinh ra Makefile (hoặc project file cho Visual Studio, Xcode, v.v.) từ một file cấu hình CMakeLists.txt duy nhất:

cmake_minimum_required(VERSION 3.10)
project(MyProject C)

set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)

# Collect every .c file in the src/ directory
file(GLOB SOURCES "src/*.c")

add_executable(my_program ${SOURCES})

# Add the include directory
target_include_directories(my_program PRIVATE include/)

# Create a separate build directory (out-of-source build)
mkdir build && cd build
cmake ..
make