Встроенная команда west системы Zephyr позволит вам работать с проектами (репозиториями Git) в общей директории рабочего пространства (workspace).
Если вы придерживались руководства по быстрому старту Zephyr [3], то ваше workspace может выглядеть примерно так:
zephyrproject/ # верхний каталог west ├── .west/ # помечает место размещения верхнего каталога │ └── config # локальный файл конфигурации, относящийся к каждому workspace │ │ # Репозиторий манифеста, который west никогда не изменяет после после создания: ├── zephyr/ # .git/ repo │ ├── west.yml # файл манифеста │ └── [... other files ...] │ │ # Проекты под управлением west: ├── modules/ │ └── lib/ │ └── zcbor/ # .git/ project ├── net-tools/ # .git/ project └── [ ... другие проекты ...]
[Концепция workspace]
Ниже даны определения базовых концепций, которые нужно усвоить, чтобы понимать структуру workspace (дополнительную информацию по workspace см. в [2]).
topdir. В примере рабочего пространства выше zephyrproject это имя директории верхнего уровня для workspace, или topdir (здесь имя zephyrproject дано только для примера, оно может быть любым).
Обычно вы сначала создаете пустую папку для topdir, и все другие файлы и директории в ней будут созданы командой west init.
Директогрия .west. В каталоге topdir находится директория с именем .west. Когда для west нужно найти topdir, он ищет каталог .west, и использует его родительскую директорию. Поиск начинается от текущей директории (и начнется снова от места, указанного в переменной окружения ZEPHYR_BASE, если поиск в текущей директории завершился неудачно).
Файл конфигурации. Файл .west/config это локальный файл конфигурации для workspace.
Репозиторий манифеста. В каждом рабочем пространстве west содержится ровно один репозиторий манифеста. Это репозиторий Git, содержащий файл манифеста (west.yml). Место расположения репозитория манифеста указывается опцией конфигурации manifest.path в локальном конфигурационном файле (т. е. в файле конфигурации находится раздел [manifest], в котором определена опция path).
Для примера выше каталог zephyr это репозиторий манифеста, но вы можете сконфигурировать west для использования любого репозитория Git в рабочем пространстве как репозитория манифеста. Единственное требование - в нем должен находиться корректный файл манифеста (для дополнительной информации: поддерживаемые топологии west см. в [5], формат файла манифеста описан в [6]).
Файл манифеста. Это файл в формате YAML, который определяет проекты. Проекты это дополнительные репозитории Git в пределах workspace, управляемом west. Файл манифеста по умолчанию носит имя west.yml; это можно изменить опцией manifest.file в локальной конфигурации.
Командой west update вы обновляете проекты в workspace на основе содержимого файла манифеста.
Проекты. Под проектами west подразумеваются репозитории Git, которые обслуживает west. Проекты определены в файле манифеста, и они могут находиться в любом месте внутри workspace. В приеденном выше примере папки проектов это zcbor и net-tools.
По умолчанию система сборки Zephyr использует west для получения мест размещения всех проектов в workspace, так что любой код, которые они содержат, могут быть использованы как модули (внешние проекты). Однако имейте в виду, что модули и проекты концептуально различаются.
Расширения. Любой репозиторий, который известен для west (либо репозиторий манифеста, или любой репозиторий проекта) может определить расширения (Extensions). Расширения это дополнительные команды west, которые вы можете запостить, используя это workspace.
Репозиторий zephyr использует эту фичу для предоставления специальных, относящихся к Zephyr команд наподобие west build. Определение таких функций как расширений сохраняет ядро west агностическим по отношению к любой версии workspace Zephyr, и т. п.
Игнорируемые файлы. В workspace могут находиться дополнительные репозитории Git или другие файлы и директории, которыми west не управляет. В основном west игнорирует все в каталоге workspace, кроме .west, репозитория манифеста и проектов, определенных в файле манифеста.
[west init и west update]
Две самые важные команды, относящиеся к workspace, это west init и west update.
west init. Эта команда создает рабочее пространство (workspace).
Важное замечание: west не меняет содержимое вашего репозитория манифеста после того, как была запущена команда west init. Для подгрузки новых версий используйте обычные команды Git, и т. п.
Обычно эта команда запускается один раз, примерно так:
$ west init -m https://github.com/zephyrproject-rtos/zephyr --mr v2.5.0 zephyrproject
Эта команда сделает следующее:
1. Создаст верхний каталог topdir, папку zephyrproject, вместе с подкаталогом .west и файлом .west/config.
2. Выполнит клонирование манифеста репозитория по ссылке https://github.com/zephyrproject-rtos/zephyr, поместив его в zephyrproject/zephyr.
4. Установит manifest.path для zephyr в .west/config.
5. Установит manifest.file в west.yml.
После этого workspace в общем готово к использованию; для завершения вам только понадобится запустить west для клонирования остальных проектов, чтобы они попали в workspace.
Более подробно west init описана в документации по встроенным командам west [7].
west init [-m URL] [--mr REVISION] [--mf FILE] [directory]
west init -l [--mf FILE] directory
Создает рабочее пространство (workspace) west.
С ключом -l будет создано workspace вокруг существующего локального репозитория;
без -l создаст workspace путем клонирования репозитория манифеста по указанному URL.
С ключом -m клонирует репозиторий по этому URL, и использует его как репозиторий
манифеста. Если ключ --mr не указан, то используется верка по умолчанию сетевого
репозитория, если она существует.
Если ни то, и ни это, то предполагается -m https://github.com/zephyrproject-rtos/zephyr.
Позиционные агументы:
directory с ключом -l путь до локального репозитория манифеста;
без него директория для создания в ней workspace
(в этом случае по умолчанию это текущая рабочая директория)
Опциональные аргументы:
-h, --help покажет это сообщение подсказки
-m MANIFEST_URL, --manifest-url MANIFEST_URL
URL репозитория манифеста для клонированияt; не может комбинироваться
с опцией -l
--mr MANIFEST_REV, --manifest-rev MANIFEST_REV
ревизия манифеста для проверки (check out) и использования; не может
комбинироваться с опцией -l
--mf MANIFEST_FILE, --manifest-file MANIFEST_FILE
используемый файл манифеста
-l, --local использует "directory" как существующий репозиторий манифеста вместо
того, чтобы клонировать его из MANIFEST_URL; в этом случае каталог
.west создается следующим для "directory", и manifest.path указывает
на "directory"
west update. Эта команда обеспечит восстановление (или обновление) содержимого вашего рабочего пространства. Команда гарантирует соответствие содержимого рабочего пространства проектам, описанным в файле манифеста.
Важное замечание: всякий раз когда вы проверяете (check out) другую версию в своем репозитории манифеста, вы должны запустить west update для гарантии, что репозитории проектов будут содержать ожидаемые новые ревизии.
Команда west update считывает содержимое файла манифеста следующим образом:
1. Она ищет topdir. В приведенном выше примере это значит, что она найдет каталог zephyrproject.
2. Загружается файл .west/config из topdir, чтобы прочитать содержимое опции manifest.path (например zephyr) и опции manifest.file (т. е. west.yml).
3. Загружается файл манифеста, указанный этими опциями (например zephyrproject/zephyr/west.yml).
Затем команда west update использует файл манифеста, чтобы обнаружить, каких проектов не хватает, чтобы поместить их в workspace, из каких URL-ов их клонировать, и какие ревизии должны быть проверены (check out) локально. Уже существующие репозитории проектов извлечения и взятия на изменение их соответствующих редакций Git в файле манифеста.
