Настройка и сборка проекта на основе distortos

Предпосылки

distortos поставляется с полной структурой сборки, которая использует исключительно CMake . Итак, для проекта, основанного на искажениях, вам понадобятся только следующие инструменты для его настройки и сборки:

• CMake (версия 3.7 или новее);
• инструмент сборки, поддерживаемый CMake - наиболее рекомендуемый - Ninja ;
• arm-none-eabi bleeding-edge-toolchain (GCC версии 5 или новее);

Рабочий процесс CMake

Система сборки distortos соответствует типичному рабочему процессу кросс-компиляции CMake , что означает, что вы всегда должны использовать так называемый файл инструментальной цепочки . В distortos эти файлы служат еще одной важной цели - они выбирают плату, которая будет использоваться вашим приложением. Следовательно, файл инструментальной цепочки для distortos не зависит от архитектуры, как и следовало ожидать, а зависит от платы.

Если вы используете настраиваемую доску или если ваша плата еще не поддерживается дистрибутивами , вам нужно будет сгенерировать все необходимые файлы. Более подробная информация об этом процессе есть в отдельной статье о генерации плат .

Минимальный проект

Как минимум, проект с distortos должен содержать следующие три вещи:

• папка с исходниками distortos ,
• CMakeLists.txt файл,
• исходный файл с расширением main().

Таким образом, простейший проект на основе distortos будет выглядеть так:

Приведенный выше пример упрощен для краткости и ясности, но, очевидно, исходный файл не должен быть назван, main.cppи не нужно помещать искаженияmy-project/distortos . На самом деле он может быть расположен где угодно, даже вне папки вашего проекта - так что вместо my-project/distortosнего он может быть как внутри, так my-project/any/fancy/path/you/likeи внутри /home/freddie/distortos.

Но давайте перейдем к чему-то более важному, чем наименование - к содержимому этих файлов. Чтобы следовать духу примера, main.cppон сведен к абсолютному минимуму - просто цикл, который постоянно вызывает distortos::ThisThread::sleepFor():

Кратчайший из возможных (и все еще пригодный для использования) CMakeLists.txtтакже довольно лаконичен:

На самом деле он мог бы быть даже короче, но это затруднило бы его использование. Последние 6 строк - все те, что ниже # optional:комментария - можно безопасно удалить, если вам не нужно то, что они делают (соответственно: двоичный образ вашего исполняемого файла, дамп памяти приложения, файл Intel HEX с прошивкой, листинг сборки все приложение, файл карты памяти, созданный во время компоновки, и отчет об использовании памяти вашим кодом).

Настройка папки сборки

После того, как вы настроили проект, как показано выше, вы можете перейти к настройке папки сборки. Я использую эту фразу для описания процесса, в котором вы создаете папку сборки, инициализируете ее с помощью CMake и - необязательно - редактируете некоторые из доступных параметров конфигурации. После настройкив папку сборки, вы можете скомпилировать свое приложение в рабочий исполняемый файл.

Следует отметить несколько моментов.

Прежде всего, distortos явно запрещает сборки из исходных кодов . Вы всегда должны создавать в отдельном каталоге, практика называется (сюрприз!) Сборкой вне исходного кода .

Вы можете вызвать папку сборки как хотите и разместить ее в любом месте. Для простоты этой статьи я буду использовать my-project/output, но вы можете выбрать любое другое имя и / или путь, например my-project/whatever, my-project/very/long/build/folder/path, /tmp/compile/it/hereили /home/freddie/build.

Для одного проекта может быть несколько папок сборки, каждая с отдельной конфигурацией. Таким образом , вы можете иметь оба my-project/Debugи my-project/Releaseпапку одновременно. Или вы можете создать одно и то же приложение для нескольких разных плат. Или просто все, о чем вы думаете.

Настройка с помощью консоли

Запустите консоль и перейдите в каталог верхнего уровня проекта. Создайте пустую outputпапку сборки, затем измените текущий каталог на вновь созданную папку. Допустим, вы хотите настроить папку сборки для использования платы STM32F4DISCOVERY - в данном случае вызов CMake для ее инициализации cmake .. -DCMAKE_TOOLCHAIN_FILE=../distortos/source/board/ST_STM32F4DISCOVERY/Toolchain-ST_STM32F4DISCOVERY.cmake -GNinja. Этот вызов должен следовать cmake $PROJECT -DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN_FILE -GNinjaшаблону, где $PROJECT- это путь к каталогу верхнего уровня проекта и $TOOLCHAIN_FILEпуть к выбранному файлу цепочки инструментов, оба пути видны из папки сборки.

Настройка с помощью cmake-gui

https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-0-150x107.png 150w, https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-0.png 740w" alt="" width="300" height="213" class="wp-image-968" style="box-sizing: inherit; border: 0px; height: auto; max-width: 100%; vertical-align: middle; display: block;" loading="lazy" />

Вместо того, чтобы инициализировать папку сборки с помощью консоли, это также можно сделать напрямую с помощью CMake GUI ( cmake-gui). После запуска приложения убедитесь, что оно выглядит как на правом скриншоте - оба верхних текстовых поля должны быть пустыми. Если это не так, просто удалите их содержимое.

https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-1-150x107.png 150w, https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-1.png 740w" alt="" width="300" height="213" class="wp-image-969" style="box-sizing: inherit; border: 0px; height: auto; max-width: 100%; vertical-align: middle; display: block;" loading="lazy" />

Нажмите « Обзор источника…» и перейдите в каталог верхнего уровня проекта. Затем нажмите « Обзор сборки…» и перейдите в папку, в которой вы хотите создать проект (вам нужно будет создать его - в браузере будет кнопка для этого).

• https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-2-150x134.png 150w, https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-2-300x268.png 300w" alt="" width="337" height="301" class="wp-image-970" style="box-sizing: inherit; border: 0px; height: auto; max-width: 100%; vertical-align: middle; display: block; width: auto;" loading="lazy" data-id="970" data-link="https://distortos.org/?attachment_id=970" />

• https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-3-150x29.png 150w, https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-3-300x58.png 300w, https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-3-768x148.png 768w" alt="" width="887" height="171" class="wp-image-971" style="box-sizing: inherit; border: 0px; height: auto; max-width: 100%; vertical-align: middle; display: block; width: auto;" loading="lazy" data-id="971" data-link="https://distortos.org/?attachment_id=971" />

Когда указаны обе папки, нажмите « Настроить» . В появившемся диалоговом окне выберите генератор (рекомендуется Ninja) и убедитесь, что выбран параметр «Указать файл цепочки инструментов для кросс-компиляции» . На следующем шаге перейдите, например my-project/distortos/source/board/ST_STM32F4DISCOVERY/Toolchain-ST_STM32F4DISCOVERY.cmake, к файлу цепочки инструментов и нажмите « Готово» .

https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-4-112x150.png 112w, https://distortos.org/wp-content/uploads/2019/05/configuring-cmake-gui-a-4.png 740w" alt="" width="223" height="300" class="wp-image-972" style="box-sizing: inherit; border: 0px; height: auto; max-width: 100%; vertical-align: middle; display: block;" loading="lazy" />

Новые параметры проекта появятся в средней части окна (первоначально с красным фоном), а внизу вы увидите журнал состояния процесса. Нажмите кнопку «Создать», и если в журнале состояния не отображаются ошибки (последняя строка Generating done), вы можете закрыть окно.

Редактирование конфигурации

В любой момент вы можете отредактировать большинство параметров вашего проекта. Нет необходимости начинать с нуля, если вы просто хотите изменить некоторые параметры (например, размер стека для основного потока), оставив другие без изменений (например, конфигурацию часов).

Рекомендуемый способ изменения конфигурации проекта - через cmake-gui. Вы можете запустить его из папки сборки с помощью cmake-gui ..(или, в более общем смысле, с помощью cmake-gui $PROJECT, где $PROJECTэто путь к каталогу верхнего уровня проекта, как видно из папки сборки). Также можно запустить графический интерфейс CMake, а затем ввести пути к каталогу верхнего уровня проекта и создать папку в двух верхних текстовых полях ( Где находится исходный код и Где создавать двоичные файлы ) - вручную или с помощью Обзор источника… и Обзор Кнопки Build… соответственно.

После изменения параметра могут появиться новые параметры, а существующие могут быть удалены / изменены. Поэтому рекомендуется нажимать кнопку « Настроить» после каждого изменения. Новые элементы изначально отображаются сверху и имеют красный фон для их выделения.

Если вы не уверены в каком-либо из вариантов, просто наведите на него указатель мыши, cmake-guiчтобы увидеть (надеюсь) полезную подсказку.

Однако обратите внимание, что CMake позволяет вам изменять некоторые параметры, которые вы действительно не хотите изменять. Основным примером является файл toolchain ( CMAKE_TOOLCHAIN_FILE) - даже если его можно изменить для настроенного проекта, никогда не делайте этого. Это означает, что если вы хотите перенастроить свой проект для использования другой платы, вам придется начать все заново с пустой папкой сборки.

CMake также имеет концепцию расширенных параметров , которые видны, только если установлен флажок Дополнительно в cmake-gui. Некоторые из них можно безопасно изменить (при условии, что вы знаете, что делаете):

• CMAKE_BUILD_TYPE,
• CMAKE_..._FLAGSи CMAKE_..._FLAGS_...,
• CMAKE_EXPORT_COMPILE_COMMANDS,
• CMAKE_VERBOSE_MAKEFILE.

Другие расширенные параметры, не перечисленные выше, никогда не следует изменять - либо потому, что это приведет к нарушению конфигурации, либо потому, что они ничего не делают для встроенного проекта.

Строим проект

Чтобы собрать приложение, просто выполните его ninjaиз папки сборки. Если вы хотите видеть все команды, выполняемые во время сборки, используйте ninja -v.

Сохраненная конфигурация

Каждый раз, когда вы изменяете какой-либо параметр проекта, CMake сохраняет полную конфигурацию $BUILD/$DISTORTOS/distortosConfiguration.cmake, где $BUILDэто путь к папке сборки и $DISTORTOS(в большинстве случаев) относительный путь к distortos в проекте. В случае примера проекта из этой статьи это будет my-project/output/distortos/distortosConfiguration.cmake). Этот файл можно использовать для простого резервного копирования (т. Е. Вы можете скопировать его, зафиксировать в своей системе контроля версий и отправить вместе с проектом) и восстановить конфигурацию проекта. Таким образом, любому, кто хочет создать ваш проект, вообще не придется иметь дело ни с одним из параметров конфигурации.

Допустим, содержимое релиза вашего проекта выглядит так:

Вся процедура восстановления конфигурации my-project/distortosConfiguration.cmakeи сборки проекта выглядит так:

• Создайте пустую my-project/outputпапку для сборки.
• Изнутри папки сборки выполнить cmake -C../distortosConfiguration.cmake .. -GNinja(аннотированный вызовом является cmake -C$SAVED_CONFIGURATION $PROJECT -GNinja, где $SAVED_CONFIGURATIONпуть к distortosConfiguration.cmakeфайлу и $PROJECTпуть к каталогу верхнего уровня проекта, оба пути , как видно из папки сборки).
• Постройте проект.

Также можно использовать конфигурацию из одного проекта в другом, предполагая, что оба они используют одну и ту же плату (то есть один и тот же файл инструментальной цепочки). Это может быть полезно, когда, например, вы не хотите снова думать о правильной конфигурации часов и просто хотите начать быстрее или импортировать некоторые из существующих конфигураций тестов прямо из distortos/configurationsпапки.

Процесс прост, если относительный путь к искажениям в обоих проектах идентичен. В противном случае это становится немного сложнее - например, когда исходный проект имел, source-project/external/distortosа целевой проект имел target-project/3rd-party/distortos. Единственный поворот в том, что вам нужно указать путь к distortos в проекте через DISTORTOS_PATHпеременную окружения. Один из способов сделать это - добавить вызов CMake к назначению переменной следующим образом DISTORTOS_PATH=3rd-party/distortos cmake -C....

Распространенная ошибка CMake

При использовании сохраненных конфигураций ( distortosConfiguration.cmake) для настройки папки сборки CMake НЕ выдаст ошибку сразу же, если не сможет найти этот файл. Вместо этого он продолжит настройку папки сборки и завершится с ошибкой ближе к концу процесса, так как файл инструментальной цепочки не был предоставлен. Если сохраненная конфигурация будет найдена, в ней будет указан файл цепочки инструментов и все другие важные настройки.

При более внимательном рассмотрении вы заметите, что вместо обнаружения arm-none-eabi-gccкомпилятора CMake обнаружил собственный компилятор вашей системы /usr/bin/cc. Даже если вы сейчас укажете правильный путь к сохраненной конфигурации, процесс не завершится успешно - на этом этапе CMake игнорирует этот файл.

Такая частично инициализированная папка сборки не подлежит ремонту и не может быть исправлена ​​никаким образом. Единственное решение - удалить его и начать с нуля.