DBG-макросы: отладка, которая исчезает в бою

Вечер перед выездом: я комментировал строки отладочной печати в скетче метеостанции — двенадцать штук — и на седьмой понял, что одна забытая println завтра будет сыпать мусор в порт, куда планировал подключить преобразователь для журнала. Печати — главный инструмент со времён первого урока про отладку логики, и вырывать их руками из скетча — занятие с гарантией промаха: у меня примерно каждый седьмой выезд начинался с невыметенного мусора в журнале.

Балласт не только мусорный, но и платный. Уровневый логгер из урока про уровни логов отбирает строки на лету — но компилятор грузит в плату все строки, включая те, что никогда не печатаются. Каждая из них без обёртки F() лежит копией в оперативке — байты мы считали в уроке про макрос F(); а печати в цикле ещё и стоят времени: 30 символов при 9600 бод занимают около 31 мс, и loop столько же отстаёт.

Старое решение языка C — условная компиляция. Одна строка #define решает, чем станет вызов DBG(): настоящей печатью или пустышкой, которую компилятор вырезает вместе со строками и аргументами. В боевой сборке от отладки не остаётся ни байта — ни флеша, ни оперативки, ни времени в loop, и это не про самодисциплину, а про свойства препроцессора. Здесь соберём готовый набор макросов, посчитаем цену обеих сборок и найдём флагу сборки место, откуда он не теряется.

Каркас — ветка #ifdef DBG_ON ... #else ... #endif. Флаг описан — макросы превращаются в печати; не описан — в пустые do {} while (0): компилятор выбрасывает вызов целиком, а с ним и аргументы. Отсюда первое правило: в DBG() прячем только просмотр. Счётчик, инкремент, чтение порта в аргументе отладочного макроса исчезнут в боевой сборке — и скетч начнёт жить другой жизнью: счёт собьётся, опрос датчика не случится. Отладка смотрит, но не трогает мир.

Обёртка do-while(0) — не украшение: она делает макрос безопасным после if без фигурных скобок. Голый println внутри #define, развёрнутый после if, съедает ветку else — компилятор ругается, а без ругани код ведёт себя странно. Скобки вокруг каждого аргумента — вторая страховка: DBG_MARK(t, a+b) разворачивается в Serial.print((a+b)) и считается предсказуемо. И запятая: выражение из двух частей внутри одного аргумента заворачивайте в лишние скобки, иначе макрос развалит его на два и откажется собирать.

Строки внутри макросов держим во флеше через F() — тот же механизм из урока про F(); в бою это неважно, там макросы вырезаны, а в отладочной сборке оперативка не тает. Метка времени печатается прямо в макросе: DBG_MS() выдаёт [dbg 12456], и поток событий легко соотносится с периодами работы узла. Почему строки тают в оперативке и как посчитать остаток RAM, мы разбирали в уроке про PROGMEM и память — здесь достаточно правила: F() вокруг каждого литерала в макросе.

Тела отладки прячьте в функции, а макросами оборачивайте только вызовы: если обернуть в #ifdef половину скетча, боевая версия рассыплется на ветвях и читать её станет мучительно — я собирал такой комбайн и потом полдня распутывал. Второй ход — расширить DBG_MS() номером строки: препроцессор разворачивает __LINE__ в строку вызова, и метка становится вида [dbg 12456:42] — видно не только когда, но и где. Третий — префикс модуля: DBG_METEO() против DBG_POMPA() экономят больше, чем кажется, когда журналов становится два.

Сравните сборки: с флагом монитор сыплет строками с миллисекундными метками, без — молчит, как будто печатей никогда не было, и так оно и есть: строк в прошивке нет, вызовов нет, вычислений аргументов нет. Цена видна внизу IDE в строчке Global variables use: отладочная сборка тяжелее на сотни байтов строк, боевая — на ноль. В loop разница нагляднее: печать из 30 символов при 9600 бод занимает около 31 мс — арифметика байта на линии из урока про буфер UART, — и отладочный цикл отстаёт ровно на столько.

Мой порядок перед выездом простой и скучный, потому и рабочий: вечер на столе — с флагом; перед прошивкой в поле строку флага закомментировать, собрать, посмотреть на размер внизу IDE, залить. Пропущенный боевой прогон — та самая история с мусором в журнале: телеметрия уехала в поле вместе с дебагом, и таблица опять решето. Скучная строка в чек-листе стоит десяти минут тишины в порту.

Отдельная история — скорость порта в отладочной сборке. Строки сыплются пачками, и на 9600 монитор за ними не успевает: буфер приёма на компьютере растёт, цикл тормозит. Я поднимаю отладочный порт до 115200 — аппаратный UART на Uno держит её стабильно, и печати перестают давить на loop; в боевой сборке скорость не важна, порт молчит. Уровень DBG_VERBOSE заведите сразу: обычный DBG для событий, VERBOSE для построчного потока значений — переключение одним флагом, без новых веток.

В Arduino IDE у скетча нет своего места для ключей компилятора: флаг -D туда не дотянуть без правки platform.txt, а правка глобального конфига IDE ломается при первом обновлении — я на этом собрал грабли и больше не хожу. Поэтому в IDE я описываю флаг первой строкой скетча: //#define DBG_ON 1, и включаю его, раскомментировав. Примитивно, зато флаг виден в диффе и не теряется между машинами.

В PlatformIO флаг живёт в platformio.ini: build_flags = -D DBG_ON — и среды делаются двумя секциями [env:debug] и [env:release] с общим кодом. Сборка без флага — release, с флагом — debug, и переключение не трогает исходник. Это тот же механизм, что у любых ключей -D препроцессору: флаг передаётся компилятору из командной строки, скетч остаётся чистым.

Второй флаг добавляйте по мере нужды, а не заранее: DBG_ON — события и пороги, DBG_VERBOSE — построчный поток значений. Две ветки #ifdef, четыре макроса — и вы различаете «что случилось» от «как оно тикало», не трогая код. Третий этаж, журналы с датой и графиком, живёт на компьютере в Processing и pyserial — туда уезжают те же строки, и таблица растёт сама.

Рантайм-переключатель — ложный друг: команда debug on из урока про текстовое меню включает болтливость, но строки при этом остаются в плате и память платят постоянно. Уровни логов и #ifdef — не конкуренты, а два этажа: уровни отбирают, что печатать прямо сейчас, #ifdef решает, будет ли отладка в сборке вообще. Я оставляю в бою INFO-строки за F(), весь DEBUG живёт за флагом сборки и в бой не ездит.

Эфир сборки в симуляторе заменён переключателем: команды dbg on и dbg off двигают флаг, поток и тишина сравниваются на глаз. В настоящем скетче выбор делает #ifdef при сборке — здесь то же решение показано моделью на переменной, и это честная оговорка: компилятор вырезает печати целиком, а флаг в рантайме лишь молчит о них.