===========================================
Глава 12: Заголовочные файлы и препроцессор
===========================================

В этой главе рассматриваются основы **модульной архитектуры программ на C** с помощью заголовочных файлов и директив препроцессора.

.. contents::
   :local:
   :depth: 2

---

1. Что такое препроцессор и зачем он нужен?
-------------------------------------------

**Препроцессор** — это первый этап компиляции программы на Си. Он обрабатывает **директивы** (специальные команды, начинающиеся с ``#``) перед тем, как код будет передан компилятору. Его основные задачи:

* Включение других файлов в текущий исходный файл.
* Определение и замена макросов.
* Условная компиляция частей кода.

---

2. Директива ``#include``
--------------------------

``#include`` используется для включения содержимого одного файла в другой. Это фундаментальный механизм для модульности в Си.

* **``#include <filename.h>``**: Используется для включения **стандартных библиотечных заголовочных файлов**. Компилятор ищет их в предопределенных системных директориях. Например, ``#include <stdio.h>`` включает стандартную библиотеку ввода/вывода.
* **``#include "filename.h"``**: Используется для включения **пользовательских заголовочных файлов** (ваших собственных). Компилятор сначала ищет их в текущей директории проекта, а затем, если не найдет, может искать в стандартных директориях (зависит от настроек компилятора).

**Пример:**

``main.c``:


.. code-block:: c

    #include <stdio.h>       // Стандартный заголовок
    #include "my_utility.h"  // Пользовательский заголовок (файл в вашем проекте)

    int main() {
        printf("Hello from main!\n");
        return 0;
  } 



---

3. Директива ``#define``
-------------------------

``#define`` позволяет определять **макросы**. Макрос — это текстовая замена: препроцессор заменяет каждое вхождение имени макроса его определением перед компиляцией.

* **Определение констант**:
    .. code-block:: c

        #define MAX_SIZE 100
        #define PI 3.14159

    Компилятор не видит ``MAX_SIZE`` или ``PI``, он видит ``100`` и ``3.14159``. Это отличается от ``const int MAX_SIZE = 100;``, которая является переменной с константным значением, обрабатываемой компилятором.

* **Определение функциональных макросов (остерегайтесь!)**:
    .. code-block:: c

        #define SQUARE(x) (x * x)
        // Использование: int result = SQUARE(5); // Препроцессор заменит на (5 * 5)
        // Будьте осторожны с побочными эффектами и двойными вычислениями!
        // SQUARE(a++) превратится в (a++ * a++), что даст неожиданный результат.

---

4. Условная компиляция (``#ifdef``, ``#ifndef``, ``#endif``, ``#if``, ``#else``, ``#elif``)
---------------------------------------------------------------------------------------------

Эти директивы позволяют включать или исключать блоки кода из компиляции в зависимости от определенных условий. Это очень полезно для:

* **Предотвращения многократного включения заголовочных файлов (Include Guards)**: Самое распространенное использование.
* Отладки (Debug/Release сборки).
* Портирования кода под разные операционные системы или аппаратные платформы.

* **``#ifndef MACRO_NAME`` / ``#define MACRO_NAME`` / ``#endif``**:
    Это стандартный шаблон для защиты заголовочных файлов от многократного включения.
    Если ``MACRO_NAME`` *не определен* (``#ifndef``), то он определяется (``#define``), и код между ``#define`` и ``#endif`` включается. При последующих включениях этого же файла ``MACRO_NAME`` уже будет определен, и код будет проигнорирован.

    **Пример из вашей главы (``math_utils.h``):**
    .. code-block:: c

        #ifndef MATH_UTILS_H    // Если MATH_UTILS_H не определен
        #define MATH_UTILS_H    // Определить MATH_UTILS_H

        int add(int a, int b);
        int multiply(int a, int b);

        #endif // MATH_UTILS_H // Конец условного блока

* **``#ifdef MACRO_NAME``**: Код компилируется, только если ``MACRO_NAME`` *определен*.
* **``#if expression``**: Код компилируется, если *выражение* истинно. Можно использовать ``defined(MACRO_NAME)``.
* **``#else``**: Блок кода, который компилируется, если условие в предыдущем ``#if``/``#ifdef``/``#ifndef`` ложно.
* **``#elif expression``**: Как ``else if`` для препроцессора.

**Пример из вашей главы (``main.c``):**

.. code-block:: c

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

        #define DEBUG

        int main() {
        #ifdef DEBUG
            printf("Debug mode is ON\n");
        #endif

            int sum = add(5, 3);
            int product = multiply(4, 2);

            printf("Sum: %d, Product: %d\n", sum, product);
            return 0;
        }

---

5. Разделение кода на ``.c`` и ``.h`` файлы
--------------------------------------------

Это основа **модульного программирования** в Си:

* **``.h`` (заголовочный файл)**: Содержит **объявления** (декларации) функций, структур, перечислений и макросов, которые должны быть доступны другим частям программы. Это своего рода "интерфейс" модуля.
* **``.c`` (файл реализации)**: Содержит **определения** (реализации) функций, объявленных в соответствующем ``.h`` файле, а также любые внутренние функции или данные, которые не предназначены для внешнего использования. Это "внутренняя работа" модуля.

**Пример из вашей главы:**

* **``math_utils.h``**: Объявляет функции ``add`` и ``multiply``.
    .. code-block:: c

        #ifndef MATH_UTILS_H
        #define MATH_UTILS_H

        int add(int a, int b);
        int multiply(int a, int b);

        #endif // MATH_UTILS_H

* **``math_utils.c``**: Реализует функции ``add`` и ``multiply``.
    .. code-block:: c

        #include "math_utils.h"

        int add(int a, int b) {
            return a + b;
        }

        int multiply(int a, int b) {
            return a * b;
        }

* **``main.c``**: Использует функции ``add`` и ``multiply`` из ``math_utils.h``, включая их через ``#include``.
    .. code-block:: c

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

        #define DEBUG

        int main() {
        #ifdef DEBUG
            printf("Debug mode is ON\n");
        #endif

            int sum = add(5, 3);
            int product = multiply(4, 2);

            printf("Sum: %d, Product: %d\n", sum, product);
            return 0;
        }

Это позволяет:

* **Инкапсуляцию**: Скрывать детали реализации.
* **Быструю компиляцию**: При изменении только ``.c`` файла, нет необходимости перекомпилировать все остальные файлы, которые используют его заголовок, только тот ``.c`` файл и затем компоновать заново.
* **Повторное использование кода**: Легко использовать один и тот же модуль в разных проектах.

---

6. Повторное использование и масштабирование проекта
----------------------------------------------------

Правильное использование заголовочных файлов и препроцессора критически важно для:

* **Организации больших проектов**: Разбиение на модули делает код более управляемым.
* **Командной работы**: Разные разработчики могут работать над разными ``.c`` файлами, используя общие ``.h`` интерфейсы.
* **Поддержки и отладки**: Логически разделенный код легче читать, понимать и исправлять ошибки.

---

7. Компиляция проекта из нескольких файлов
------------------------------------------

Как показано в вашем примере:

.. code-block:: shell

    $ gcc main.c math_utils.c -o program
    $ ./program
    Debug mode is ON
    Sum: 8, Product: 8

Здесь ``gcc`` принимает несколько исходных файлов (``main.c`` и ``math_utils.c``) и компилирует их, а затем компонует в один исполняемый файл ``program``.

---

8. Дополнительные ресурсы
--------------------------

Для более глубокого изучения этих тем рекомендуем обратиться к следующим источникам:

* `C Preprocessor Directives – GeeksForGeeks`_
* `Header Files in C – cprogramming.com`_
* **Книга "Язык программирования Си" (K&R)**: Главы, посвященные препроцессору и модульному программированию.

.. _C Preprocessor Directives – GeeksForGeeks: https://www.geeksforgeeks.org/c-preprocessors/
.. _Header Files in C – cprogramming.com: https://www.cprogramming.com/tutorial/cfileio.html

---

Эта глава закладывает основу для создания сложных, хорошо структурированных приложений на Си.