Пакет Zephyr CMake это удобный способ создания приложений на основе Zephyr [2].

Пакет Zephyr CMake гарантирует, что CMake может автоматически выбрать инсталляцию Zephyr для использования в сборке приложения, независимо от того, является ли оно приложением из репозитория Zephyr, приложением рабочего пространства Zephyr, либо отдельным приложением Zephyr.

Примечание: раздел "Типы приложений" документации [3] дает информацию от типах приложений, используемых в этом описании.

При разработке приложений на основе Zephyr разработчику всего лишь надо написать find_package(Zephyr) в начале файла приложения CMakeLists.txt.

Для использования пакета Zephyr CMake он должен быть сначала экспортирован в так называемый регистр пакетов пользователя (User Package Registry [4]). Это означает создание ссылки не текущую инсталляцию Zephyr внутри регистра пакетов пользователя CMake.

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

Экспорт пакета Zephyr CMake. Когда Zephyr устанавливается с помощью west, рекомендуется делать экспорт Zephyr командой:

west zephyr-export

Без west пакет Zephyr CMake экспортируется в регистр пакетов пользователя CMake следующими командами:

cmake -P < путь-до-Zephyr>/share/zephyr-package/cmake/zephyr_export.cmake

Эта команда выполнит экспорт текущей Zephyr в регистр пакетов пользователя CMake.

Дополнительно, чтобы также экспортировать пакет Zephyr Unittest CMake, запустите следующую команду:

cmake -P < путь-до-Zephyr>/share/zephyrunittest-package/cmake/zephyr_export.cmake

Настройка базового окружения Zephyr. Функционал поиска пакета Zephyr CMake позволяет явно указывать базу Zephyr, используя переменную окружения. Для этого используйте следующий синтаксис find_package():

find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})

Этот синтаксис инструктирует CMake сначала искать Zephyr, используя настройку базы Zephyr из переменной окружения ZEPHYR_BASE, и затем использовать нормальные пути поиска.

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

● Приложение репозитория Zephyr будет использовать ту инсталляцию Zephyr, в которой оно расположено. Например:

< projects>/zephyr-workspace/zephyr
└── samples
    └── hello_world

В этом примере приложение hello_world будет использовать < projects>/zephyr-workspace/zephyr.

● Приложение рабочего пространства Zephyr будет использовать ту инсталляцию Zephyr, с которой оно делит общее рабочее пространство. Например:

< projects>/zephyr-workspace
├── zephyr
├── ...
└── my_applications
     └── my_first_app

В этом примере приложение my_first_app будет использовать < projects>/zephyr-workspace/zephyr в качестве Zephyr, потому что эта инсталляция Zephyr находится в том же рабочем пространстве, что и приложение.

Примечание: корень рабочего пространства Zephyr идентичен директории верхнего уровня west, если рабочее пространство было инсталлировано с помощью west.

● Отдельное приложение Zephyr будет использовать тот Zephyr, который был зарегистрирован в регистре пакетов пользователя CMake. Например:

< projects>/zephyr-workspace-1
└── zephyr                       (не экспортировано для CMake)

< projects>/zephyr-workspace-2
└── zephyr                       (экспортировано для CMake)

< home>/app
├── CMakeLists.txt
├── prj.conf
└── src
    └── main.c

В этом примере только < projects>/zephyr-workspace-2/zephyr экспортировано для регистра пакетов CMake, и поэтому эта инсталляция Zephyr будет использоваться отдельным Zephyr-приложением < home>/app.

Если пользователь захочет проверить приложение с < projects>/zephyr-workspace-1/zephyr, то это можно сделать путем настройки переменной окружения базы Zephyr, подразумевающее установку ZEPHYR_BASE=< projects>/zephyr-workspace-1/zephyr перед запуском CMake.

Примечание: выбранный пакет Zephyr при первом использовании CMake будет использоваться для всех последующих сборок. Чтобы изменит пакет Zephyr, например для тестирования приложения, используя настройку базы Zephyr через переменную окружения, то необходимо выполнить сначала сборку pristine (см. секцию "Повторная сборка приложения" документации [3]).

[Версия пакета Zephyr CMake]

Когда пишут приложение, можно указать номер версии Zephyr x.y.z, который должен использоваться для сборки приложения.

Указание версии особенно полезно для отдельного приложения Zephyr, поскольку гарантирует, что приложение будет собрано с минимальной версией Zephyr.

Это также помогает CMake выбрать корректную версию Zephyr для сборки, когда в системе есть несколько инсталляций Zephyr.

Например:

find_package(Zephyr 2.2.0)
project(app)

Здесь будет требоваться сборка приложения с минимальной версией Zephyr 2.2.0. CMake будет искать подходящую версию среди всех экспортированных кандидатов, чтобы найти ту инсталляцию Zephyr, которая соответствует критерию этой версии.

Таким образом, имеется возможность содержать несколько инсталляций Zephyr, и CMake будет автоматически выбирать между ними, основываясь на предоставленном номере версии [5].

Например:

< projects>/zephyr-workspace-2.a
└── zephyr                       (экспортировано для CMake)

< projects>/zephyr-workspace-2.b
└── zephyr                       (экспортировано для CMake)

< home>/app
├── CMakeLists.txt
├── prj.conf
└── src
    └── main.c

В этом случае 2 релиза Zephyr с разными версиями установлены в своих отдельных рабочих пространствах 2.a и 2.b, соответствующих версиям Zephyr. Чтобы гарантировать сборку приложения с минимальной версией 2.a, может использоваться следующий синтаксис find_package:

find_package(Zephyr 2.a)
project(app)

Обратите внимание, что этому требованию удовлетворяют обе инсталляции, 2.a и 2.b.

CMake также поддерживает ключевое слово EXACT, чтобы гарантировать, что будет использоваться точно та версия, что указана. В этом случае файл приложения CMakeLists.txt должен быть написан так:

find_package(Zephyr 2.a EXACT)
project(app)

В случае, когда не было найдено ни одной инсталляции Zephyr, которая удовлетворяет требуемой версии, например когда приложение задает:

find_package(Zephyr 2.z)
project(app)

... тогда будет выведена ошибка наподобие следующей:

Could not find a configuration file for package "Zephyr" that is compatible
with requested version "2.z".

The following configuration files were considered but not accepted:

< projects>/zephyr-workspace-2.a/zephyr/share/zephyr-package/cmake/ZephyrConfig.cmake, version: 2.a.0
< projects>/zephyr-workspace-2.b/zephyr/share/zephyr-package/cmake/ZephyrConfig.cmake, version: 2.b.0

Примечание: может быть полезным также указать номер версии для репозитория приложений Zephyr и приложений рабочего пространства Zephyr. Указание версии в этих случаях гарантирует, что приложение будет собрано только если было совпадение с репозиторием или рабочим пространством Zephyr. Это может быть полезным, чтобы избежать случайных сборок, когда была обновлена только часть рабочего пространства.

[Несколько инсталляций (Zephyr workspace)]

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

Например:

< projects>/zephyr-workspace
├── zephyr
├── zephyr-vendor
├── zephyr-custom
├── ...
└── my_applications
     └── my_first_app

В этом примере установки у find_package(Zephyr) следующий порядок предпочтения при выборе, какой Zephyr использовать:

● Имя проекта: zephyr
● Первый проект, когда проекты Zephyr упорядочены лексикографически, как в этом случае.
   zephyr-custom
   zephyr-vendor

Это означает, что my_first_app будет использовать < projects>/zephyr-workspace/zephyr.

Можно в приложении указать список преференций Zephyr, примерно так:

set(ZEPHYR_PREFER "zephyr-custom" "zephyr-vendor")
find_package(Zephyr)

project(my_first_app)

Здесь ZEPHYR_PREFER это список, позволяющий перечислить несколько инсталляций Zephyr. Если Zephyr указан в списке, но не найден в системе, то он просто игнорируется, и find_package(Zephyr) продолжит выбор следующего кандидата.

Это позволяет временное создание нового релиза Zephyr для тестирования, без того, чтобы трогать текущий Zephyr. Когда тестирование завершено, папка zephyr-test может быть просто удалена. Подобный CMakeLists.txt может выглядеть так:

set(ZEPHYR_PREFER "zephyr-test")
find_package(Zephyr)

project(my_first_app)

[Пакет CMake конфигурации сборки Zephyr]

Пакет CMake конфигурации сборки Zephyr (Zephyr Build Configuration CMake package) предоставляет возможность проекту, основанному на Zephyr, традиционным способом управлять настройками сборки Zephyr.

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

Пакет Zephyr Build Configuration CMake будет загружен в код шаблона Zephyr после определения начальных свойств и ZEPHYR_BASE, но перед выполнением кода CMake. Это позволяет пакету Zephyr Build Configuration CMake настроить расширенные свойства, такие как DTS_ROOT, BOARD_ROOT, TOOLCHAIN_ROOT / другие настройки тулчейна, фиксированные оверлеи и любое другое свойство, которым можно управлять. Это также включает код дополнительного шаблона.

Для предоставления пакета Zephyr Build Configuration CMake создайте файл ZephyrBuildConfig.cmake, и поместите его в папку верхнего уровня рабочего пространства Zephyr:

< projects>/zephyr-workspace
├── zephyr
├── ...
└── zephyr application (может быть любое имя)
     └── share/zephyrbuild-package/cmake/ZephyrBuildConfig.cmake

Пакет Zephyr Build Configuration CMake не будет искаться в любом пути поиска по умолчанию CMake, и поэтому это не может быть установлено в регистре пакета CMake. Для пакета Zephyr Build Configuration не будет проверки версии.

Примечание: файл share/zephyrbuild-package/cmake/ZephyrBuildConfig.cmake использует ту же структуру папок, что и пакет Zephyr CMake.

Можно поместить ZephyrBuildConfig.cmake прямо в папку < приложение Zephyr>/cmake или другую папку, пока эта папка соблюдает алгоритм поиска пакета CMake.

Ниже показан пример ZephyrBuildConfig.cmake.

# Пример кода ZephyrBuildConfig.cmake

# Для гарантии, что конечный путь абсолютный, и не содержит

# в переменной ..

get_filename_component(APPLICATION_PROJECT_DIR
                       ${CMAKE_CURRENT_LIST_DIR}/..
                       ABSOLUTE
)

# Добавьте этот проект к списку корневых каталогов плат

list(APPEND BOARD_ROOT ${APPLICATION_PROJECT_DIR})

# Default to GNU Arm Embedded toolchain if no toolchain is set

if(NOT ENV{ZEPHYR_TOOLCHAIN_VARIANT})
   set(ZEPHYR_TOOLCHAIN_VARIANT gnuarmemb)
   find_program(GNU_ARM_GCC arm-none-eabi-gcc)
   if(NOT ${GNU_ARM_GCC} STREQUAL GNU_ARM_GCC-NOTFOUND)
      # Корень тулчейна находится выше пути до компилятора.
      get_filename_component(GNUARMEMB_TOOLCHAIN_PATH ${GNU_ARM_GCC}/.. ABSOLUTE)
   endif()

endif()

[Пакет Zephyr Build Configuration CMake в случае отдельного приложения]

Пакет Zephyr Build Configuration CMake может находиться вне рабочего пространства Zephyr например в отдельном приложении Zephyr.

Создайте конфигурацию сборки, как было описано в предыдущей секции, и затем ссылайтесь на место вашего пакета Zephyr Build Configuration CMake, используя CMake-переменную ZephyrBuildConfiguration_ROOT.

1. В командной строке CMake:

cmake -DZephyrBuildConfiguration_ROOT=< путь-до-конфигурации-сборки> ...

2. В файле верхнего уровня CMakeLists.txt приложения:

set(ZephyrBuildConfiguration_ROOT < путь-до-конфигурации-сборки>)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})

Если выбрана эта опция, то убедитесь, что установили переменную перед вызовом find_package(Zephyr ...), как показано выше.

3. В отдельном скрипте CMake, который предварительно загружается для заполнения кэша CMake:

# Поместите это в файл, который называется наподобие "zephyr-settings.cmake":
set(ZephyrBuildConfiguration_ROOT < path-to-build-config>
    CACHE STRING "pre-cached build config"
)

Вы можете указать системе сборки использовать этот файл путем добавления -C zephyr-settings.cmake в командную строку CMake. Этот принцип полезен, когда не используется west, поскольку обе эти установки и модули Zephyr могут быть указаны с использованием одного и того же файла. См. раздел "Without West" документации [6].

[Исходный код пакета Zephyr CMake]

Исходный код пакета Zephyr CMake в < путь-до-Zephyr>/share/zephyr-package/cmake содержит пакет CMake config, используемую CMake-функцией find_package. Это также содержит код для экспорта Zephyr в качестве пакета CMake config. Ниже приведен обзор этих файлов.

CMakeLists.txt Файл для системы сборки CMake, который отвечает за экспорт Zephyr в качестве пакета для пользовательского регистра пакетов CMake.

ZephyrConfigVersion.cmake Файл версии пакета Zephyr. Этот файл вызывается CMake, чтобы определить, соответствует ли эта инсталляция требованиям, которые указал пользователь при вызове find_package(Zephyr ...). Это также отвечает за определение инсталляций - репозиторий Zephyr, или только рабочее пространство.

ZephyrUnittestConfigVersion.cmake То же самое, что и ZephyrConfigVersion.cmake, но для unit-тестов. Включает ZephyrConfigVersion.cmake.

ZephyrConfig.cmake Файл пакета Zephyr. Этот файл вызывается CMake для удовлетворения требований, указанных пользователем при вызове find_package(Zephyr ...). Этот файл отвечает за выбор источника кода шаблона.

ZephyrUnittestConfig.cmake То же самое, что и ZephyrConfig.cmake, но для unit-тестов. Включает ZephyrConfig.cmake.

zephyr_package_search.cmake Общий файл для детектирования кандидатов репозитория и рабочего пространства Zephyr. Используется для общего кода ZephyrConfigVersion.cmake и ZephyrConfig.cmake.

pristine.cmake Файл чистой пересборки для удаления всех файлов, созданных CMake во время конфигурирования и во время генератора, когда экспортируется пакет Zephyr CMake. Запуск pristine сохраняет все упомянутые выше файлы, относящиеся к пакету.

[Ссылки]

1. Zephyr CMake Package site:zephyrproject.org.
2. Zephyr: быстрый старт.
3. Zephyr: разработка приложения.
4. User Package Registry site:cmake.org.
5. Config Mode Version Selection site:cmake.org.
6. Zephyr Modules (External projects) site:zephyrproject.org.