Сборка воспроизводима, если при одном и том же исходном коде, среде сборки и инструкциях сборки любая сторона может воссоздать побитовые идентичные копии указанных результирующих артефактов кода.
Соответствующие атрибуты окружения сборки, инструкции сборки и исходный код, а также ожидаемые воспроизводимые артефакты определяются авторами или дистрибьюторами. Артефакты сборки это части результатов сборки, которые являются требуемыми первичными выходными результатами сборки.
[Определения]
Исходный код это обычно выборка (checkout) из системы управления версиями на определенной ревизии проекта или содержимое архива исходного кода.
Соответствующие атрибуты окружения сборки обычно включают зависимости и их версии, флаги конфигурации сборки и переменные окружения, если они используются системой сборки (например установленная локаль). Предпочтительно уменьшить этот набор атрибутов.
Артефакты будут включать исполняемые файлы, дистрибутивы или образы файловой системы. Они обычно не включают журналы построения или аналогичные вспомогательные результаты.
Воспроизводимость артефактов проверяется побитовым сравнением. Обычно это выполняется с помощью криптографически безопасных хеш-функций.
Авторы или распространители означают стороны, которые заявляют о воспроизводимости набора артефактов. Это могут быть вышестоящие авторы, сопровождающие дистрибутива или любой другой дистрибьютор.
Когда воспроизводимые сборки разрешены, собираемое в ESP-IDF приложение не зависит от окружения сборки. И файл .elf, и файлы .bin приложения остаются абсолютно такими же, даже если меняются следующие переменные:
• Директория, где находится проект • Директория, где находится ESP-IDF (переменная IDF_PATH) • Время сборки • Путь установки тулчейна
[Причины, по которым сборка не воспроизводится]
Есть несколько факторов, из-за которых приложение может зависеть от окружения сборки, даже когда для сборки использовался тот же самый исходный код и те же самые версии утилит сборки.
• В коде C/C++, макрос препроцессора __FILE__ разворачивается в полный путь файла исходного кода. • Макросы препроцессора __DATE__ и __TIME__ разворачиваются в дату и время момента компиляции. • Когда компилятор генерирует объектные файлы, он добавляет секции с отладочной информацией. Эти секции помогают отладчикам, таким как GDB, найти исходный код на машине разработчика, соответствующий определенным местам в машинном коде. Эти секции обычно содержат пути соответствующих файлов исходного кода. Пути эти могут быть абсолютными, и будут включать путь до ESP-IDF или каталога проекта.
Могут быть также и другие возможные причины, такие как нестабильный порядок сборки входных файлов и отсутствие детерминизма системы сборки (например многопоточная сборка сложных проектов).
[Разрешение воспроизводимых сборок в ESP-IDF]
Воспроизводимость ESP-IDF достигает следующими методами:
• Когда воспроизводимые сборки разрешены, в исходном коде ESP-IDF макросы __DATE__ и __TIME__ больше не используются. Обратите внимание, что если исходный код приложения использует эти макросы, то сборка не будет воспроизводимой.
• Система сборки ESP-IDF передает набор флагов -fmacro-prefix-map и -fdebug-prefix-map для замены базовых путей заполнителями:
- Путь до ESP-IDF заменяется на /IDF - Путь до проекта заменяется на /IDF_PROJECT - Путь до директории сборки заменяется на /IDF_BUILD - Пути до компонентов заменяются на /COMPONENT_NAME_DIR (где NAME это имя компонента) - Пути до тулчейна заменяются на /TOOLCHAIN
• Время и дата сборки не включается в структуру метаданных приложения (application metadata structure) структуру метаданных загрузчика (bootloader metadata structure, если разрешена опция CONFIG_APP_REPRODUCIBLE_BUILD.
• Система сборки ESP-IDF гарантирует, что списки исходных файлов, списки компонентов и другие последовательности сборки сортируются перед тем, как они передаются в CMake. Различные другие пути системы сборки, такие как генератор скрипта линкера, также выполняют сортировку для гарантии, что выходной результат будет воспроизводимым независимо от окружения.
[Воспроизводимые сборки и отладка]
Когда воспроизводимые сборки разрешены, имена файлов, включенные в секции отладочной информации, становятся измененными, как это было описано выше. Из-за этого факта отладчик (GDB) не может найти исходные файлы кода для соответствующих частей исполняемого кода.
Эту проблему можно решить с помощью GDB-команды set substitute-path. Например, добавлением следующей команды в скрипт инициализации отладчика (GDB init script), измененные пути могут быть возвращены в соответствующие оригинальные значения.
set substitute-path /COMPONENT_FREERTOS_DIR /home/user/esp/esp-idf/components/freertos
Система сборки ESP-IDF автоматически генерирует файл со списком таких команд set substitute-path. Этот файл называется prefix_map, и он находится в директории build/gdbinit. Если воспроизводимые сборки не разрешены, то этот файл пустой.
Когда idf.py gdb используется для запуска отладки, этот дополнительный gdbinit-файл передается GDB. Когда GDB запускается вручную или из IDE, передайте этот дополнительный gdbinit-скрипт в GDB, используя аргумент -x build/gdbinit/prefix_map его командной строки.
[Факторы, все еще влияющие на репродуктивность сборок]
Обратите внимание, что собираемое приложение зависит от:
• Версии ESP-IDF. • Версий инструментов сборки (CMake, Ninja) и кросс-компилятора.
Может использоваться IDF-образ докера [3], который гарантирует отсутствие влияния этих факторов на сборку.
