path: root/man/ru/mcpu-cpp.1

.TH MCPU-CPP 1 "Октябрь 2026" "MCPU-CPP 1.0.3" "Команды пользователя"
.SH ИМЯ
mcpu-cpp \- препроцессор языков MCPU
.SH СИНТАКСИС
.B mcpu-cpp
.RI [ параметры ]
.RI [ входной-файл
.RI [ выходной-файл ]]
.SH ОПИСАНИЕ
.B mcpu-cpp
\- препроцессор инструментария MCPU. Он обрабатывает исходный текст до передачи
языковым frontend, раскрывает макро, вычисляет условия условной компиляции,
выполняет поиск include-файлов, поддерживает информацию о позиции в исходном
тексте и может формировать зависимости Make.
.PP
Внешний текст имеет кодировку UTF-8. Внутри текст представлен строгим UCS-2
средствами LibMPUIO. Идентификаторы препроцессора поддерживают Unicode: первый
символ должен быть подчёркиванием или иметь свойство Unicode XID_Start;
последующие символы дополнительно могут быть знаком доллара или иметь
XID_Continue. Знак доллара не может начинать идентификатор.
.PP
Директивы препроцессора имеют только канонические английские имена. Unicode
полностью сохраняется в идентификаторах, строках, комментариях, диагностике и
обычном исходном тексте.
.PP
Если
.I входной-файл
не задан или равен
.BR - ,
читается стандартный ввод. Если
.I выходной-файл
не задан или равен
.BR - ,
обычный результат препроцессирования записывается в стандартный вывод.
.SH ОБРАБОТКА ТЕКСТА
Склейка backslash-newline выполняется до разбора директив. Блочные комментарии
C и однострочные комментарии C++ удаляются фазой препроцессирования. Длинные
невидимые участки исходного файла представляются компактно с сохранением
исходных координат: короткие переходы задаются переводами строк, большие
переходы \- корректирующими GNU-style linemarkers.
.SH ДИРЕКТИВЫ
Основные поддерживаемые директивы:
.TP
.B #define
Определяет object-like или function-like macro.
.TP
.B #undef
Удаляет определение макро.
.TP
.BR #if , " #ifdef" , " #ifndef" , " #elif" , " #else" , " #endif"
Управляют условной компиляцией. В выражениях
.B #if
поддерживается оператор
.BR defined .
.TP
.B #include
Включает заголовочный файл в кавычках или угловых скобках. Operand может быть
получен macro expansion.
.TP
.B #include_next
Продолжает поиск header после элемента search chain, которым был найден текущий
header. Директива предназначена прежде всего для wrapper headers.
.TP
.B #pragma once
Обрабатывает физический header только один раз. Используется физическая
идентичность файла, а не написание его имени в исходном тексте.
.TP
.B #line
Задаёт логический номер строки и, необязательно, логическое имя исходного файла.
Аргументы проходят macro expansion; в выходе используются GNU-style
linemarkers.
.TP
.B #error
Выдаёт сообщение об ошибке и немедленно завершает препроцессирование неуспешно.
.TP
.B #warning
Выдаёт предупреждение и продолжает работу, если политика предупреждений не
повышает его до ошибки.
.TP
.B #lang
Помещает состояние языка MCPU в стек. Аргументом является одно имя языка в
кавычках.
.TP
.B #endlang
Восстанавливает предыдущее состояние языка MCPU.
.PP
.B #lang
и
.B #endlang
сохраняются в выходном потоке для последующего frontend dispatcher.
Поддерживаются имена языков
.BR diff ,
.BR dift ,
.BR alg ,
.BR as ,
.BR avm
и
.BR ACS .
Сравнение имени языка выполняется без учёта ASCII-регистра, а написание внутри
кавычек сохраняется в нормализованном выводе
.BR #lang .
.SH МАКРО
Поддерживаются object-like и function-like macros, повторный macro rescan,
stringification оператором
.BR # ,
token concatenation оператором
.BR ## ,
variadic macros с
.B ...
и
.BR __VA_ARGS__ ,
а также стандартный
.BR __VA_OPT__ .
.PP
Обычные фактические аргументы раскрываются до подстановки, кроме случаев, когда
stringification или token concatenation требуют сырого аргумента. Горизонтальные
пробелы replacement list нормализуются без изменения пробелов внутри quoted
tokens и фактических аргументов.
.SH УСЛОВНЫЕ ВЫРАЖЕНИЯ
Выражения
.B #if
поддерживают целые и символьные константы, оператор
.BR defined ,
унарные, арифметические, shift, relational, equality, bitwise, logical,
условный оператор
.B ?: 
и оператор comma. Для
.BR && ,
.BR ||
и
.B ?: 
используется short-circuit evaluation.
.PP
Вычисление выражений выполняется в единой 64-битной модели. MCPU дополнительно
поддерживает суффиксы разрядности
.B zNNN
и
.B zNNNU
для исходных целых литералов с разрядностью не более 64 бит. Отрицательное
значение shift count меняет направление сдвига согласно контракту
препроцессора MCPU.
.SH ПОИСК INCLUDE-ФАЙЛОВ
Для
.B "#include \"file\""
сначала проверяется физический каталог текущего исходного файла. Для
.B "#include <file>"
этот шаг отсутствует. Остальная effective search chain имеет строгий порядок:
.PP
.nf
explicit -I
explicit -isystem
MCPU_CPP_<LANG>_INCLUDE_PATH
MCPU_CPP_INCLUDE_PATH
MCPU_CPP_SYSTEM_INCLUDE_PATH/<lang>
MCPU_CPP_SYSTEM_INCLUDE_PATH
explicit -idirafter
MCPU_CPP_AFTER_INCLUDE_PATH
.fi
.PP
Внутри одного search class сохраняется порядок добавления. Логическое имя,
заданное
.BR #line ,
не изменяет поиск quoted header.
.SH ПАРАМЕТРЫ
.TP
.BI -o " ФАЙЛ"
Записывает обычный результат препроцессирования в
.IR ФАЙЛ .
.TP
.BI -D " ИМЯ[=ЗНАЧЕНИЕ]"
Определяет макро командной строки.
.TP
.BI -U " ИМЯ"
Отменяет определение макро командной строки.
.TP
.BI -imacros " ФАЙЛ"
Полностью препроцессирует
.I ФАЙЛ
для изменения macro/preprocessing state, но отбрасывает его обычный вывод. Все
.B -imacros
обрабатываются раньше всех
.BR -include .
.TP
.BI -include " ФАЙЛ"
Препроцессирует
.I ФАЙЛ
до основного входного файла.
.TP
.BR "-I КАТАЛОГ" ", " "-IКАТАЛОГ"
Добавляет пользовательский include-каталог.
.TP
.BI -isystem " КАТАЛОГ"
Добавляет явный системный include-каталог.
.TP
.BI -idirafter " КАТАЛОГ"
Добавляет include-каталог, который ищется после configured system tree.
.TP
.B -nostdinc
Исключает effective standard-system include tree. Явные каталоги
.B -isystem
остаются активными.
.TP
.B -dM
После препроцессирования выводит определения непредопределённых макро.
.TP
.B -dMP
Сначала выводит предопределённые макро, затем остальные определения.
.TP
.B -dD
Сохраняет директивы
.B #define
в обычном выходном потоке.
.TP
.B -dconfig
Выводит effective configuration MCPU-CPP и завершает работу.
.TP
.B -dsearch-dirs
Выводит effective include search directories и завершает работу.
.TP
.B -M
Выводит одно правило зависимостей Make с системными headers и подавляет обычный
результат препроцессирования.
.TP
.B -MM
Аналог
.BR -M ,
но без системных зависимостей.
.TP
.B -MG
В dependency-only режимах
.B -M
или
.B -MM
считает отсутствующие headers и forced files генерируемыми зависимостями, а не
ошибками. С
.B -MD
и
.B -MMD
не используется.
.TP
.B -MD
Формирует зависимости с системными headers, сохраняя обычный результат
препроцессирования.
.TP
.B -MMD
Аналог
.BR -MD ,
но без системных зависимостей.
.TP
.BI -MF " ФАЙЛ"
Записывает зависимости в
.IR ФАЙЛ .
Имя
.B -
означает стандартный вывод. Параметр имеет смысл только при генерации
зависимостей.
.TP
.BI -MT " ЦЕЛЬ"
Задаёт явную цель правила Make без Make quoting. Параметр можно повторять.
.TP
.BI -MQ " ЦЕЛЬ"
Задаёт явную цель правила Make с Make quoting. Параметр можно повторять.
.TP
.BI --object-suffix " СУФФИКС"
Задаёт суффикс автоматически формируемой цели зависимости. По умолчанию
используется
.BR .o .
.TP
.B -w
Подавляет все предупреждения.
.TP
.BR -Wcomment , " -Wcomments"
Включает предупреждения о вложенном
.B /*
внутри блочного комментария и о backslash-newline внутри комментария
.BR // .
.TP
.BR -Wno-comment , " -Wno-comments"
Выключает comment warnings, в том числе при наличии
.BR -Wall .
.TP
.B -Wall
Включает все optional warning classes MCPU-CPP.
.TP
.B -Werror
Повышает каждое реально выдаваемое предупреждение до ошибки, но само не
включает новые классы предупреждений.
.TP
.B -Wno-error
Оставляет выдаваемые предупреждения предупреждениями.
.TP
.BI --config-file " ФАЙЛ"
Использует только явно выбранный
.I ФАЙЛ
как configuration layer поверх runtime-derived defaults.
.TP
.B --no-config
Не читает configuration files. Runtime-derived defaults остаются активными.
.TP
.BI --sys-root= ПУТЬ
Использует
.I ПУТЬ
как системный корень MCPU и не читает configuration files. Effective system
include tree становится
.IR ПУТЬ/include .
Относительный путь разрешается относительно рабочего каталога запуска.
.TP
.BR -v , " --verbose"
Выводит информацию об effective configuration и include activity.
.TP
.B --help
Выводит краткую справку по командной строке и успешно завершает работу.
.TP
.B --version
Выводит версию программы и успешно завершает работу.
.TP
.B -E
Принимается и игнорируется для совместимости с compiler drivers. Параметр
намеренно не показывается в
.BR --help .
.SH ЗАВИСИМОСТИ
Генерация зависимостей использует тот же include traversal, что и обычное
препроцессирование, включая условную компиляцию, computed includes,
.BR #include_next
и
.BR "#pragma once" .
Физические зависимости дедуплицируются по физической идентичности файла.
.PP
В режимах
.B -M
и
.B -MM
обычный результат препроцессирования подавляется. В режимах
.B -MD
и
.B -MMD
он сохраняется, а dependency file формируется как side effect. Если
.B -MF
не задан, имя dependency file выводится из имени входного файла или обычного
выхода
.B -o
и получает суффикс
.BR .d .
.SH КОНФИГУРАЦИЯ
До чтения configuration files MCPU-CPP формирует
.B MCPU_CPP_SYSTEM_INCLUDE_PATH
как
.IR <runtime-root>/include .
Runtime root определяется из фактического расположения исполняемого файла,
обычно через Linux
.IR /proc/self/exe .
.PP
Configuration layers применяются в порядке возрастания приоритета:
.PP
.nf
<runtime-root>/etc/mcpu-cpp.conf
/etc/mcpu/mcpu-cpp.conf
$HOME/.mcpu/etc/mcpu-cpp.conf
.fi
.PP
При
.BI --sys-root= ПУТЬ
эти configuration files не читаются, а
.I ПУТЬ/include
становится effective system include root. Эта опция также подавляет явно
заданный
.BR --config-file .
.PP
Пользовательские переменные путей:
.BR MCPU_CPP_INCLUDE_PATH ,
.BR MCPU_CPP_AFTER_INCLUDE_PATH ,
.BR MCPU_CPP_DIFF_INCLUDE_PATH ,
.BR MCPU_CPP_DIFT_INCLUDE_PATH ,
.BR MCPU_CPP_ALG_INCLUDE_PATH ,
.BR MCPU_CPP_AS_INCLUDE_PATH ,
.BR MCPU_CPP_AVM_INCLUDE_PATH
и
.BR MCPU_CPP_ACS_INCLUDE_PATH .
Effective system root задаётся
.BR MCPU_CPP_SYSTEM_INCLUDE_PATH .
Более позднее определение полностью заменяет раннее, включая пустое значение.
.SH ПОЗИЦИИ В ИСХОДНОМ ТЕКСТЕ
MCPU-CPP выводит GNU-style linemarkers вида:
.PP
.nf
# line "file" [flags]
.fi
.PP
Флаг 1 означает вход во включённый файл, флаг 2 \- возврат в включающий файл.
Входная директива
.B #line
изменяет логические значения
.B __LINE__
и
.BR __FILE__ .
К предопределённым source macros также относятся
.B __BASE_FILE__
и
.BR __INCLUDE_LEVEL__ .
.SH GNU-COMPATIBLE FEATURES
MCPU-CPP является самостоятельным препроцессором MCPU, но для документированных
операций намеренно повторяет поведение GNU CPP. К ним относятся object-like и
function-like macros, rescan,
.BR # ,
.BR ## ,
variadic macros,
.BR __VA_OPT__ ,
условные директивы,
.BR #include ,
.BR #include_next ,
.BR "#pragma once" ,
.BR #line ,
GNU linemarkers, forced files, параметры генерации зависимостей Make и
поддерживаемые warning controls.
.PP
MCPU-специфичные средства
.BR "#lang / #endlang" ,
суффикс целых литералов
.B zNNN
и предопределённые макро ABI MCPU являются собственными расширениями.
.SH ФАЙЛЫ
.TP
.I <runtime-root>/etc/mcpu-cpp.conf
Конфигурация, установленная вместе с перемещаемым runtime tree MCPU.
.TP
.I /etc/mcpu/mcpu-cpp.conf
Необязательная общесистемная configuration override.
.TP
.I $HOME/.mcpu/etc/mcpu-cpp.conf
Необязательная пользовательская configuration override с наивысшим обычным
приоритетом.
.SH КОД ЗАВЕРШЕНИЯ
.B mcpu-cpp
возвращает ноль после успешного препроцессирования и после успешных
информационных операций, например
.B --help
и
.BR --version .
При ошибке командной строки, конфигурации, препроцессирования, диагностике,
повышенной до ошибки, или ошибке вывода возвращается ненулевое значение.
.SH СМ. ТАКЖЕ
.BR libmpu (7),
.BR libmpuio (7),
.BR zubr (1)