Проект Zephyr включает в себя очень полезную утилиту командной строки west. West разрабатывается в своем отдельном репозитории [2].
Примечание: Zephyr это английское имя латинского Zephyrus, греческого античного бока западного ветра (west wind).
Встроенные команды west предоставляют управление несколькими репозиториями. Предоставляются функции, вдохновителями которых послужили Google Repo tool и Git submodules. West также обладает возможностью расширения: Вы можете написать свои собственные команды расширения, которые добавляют функции для west. Zephyr использует west для предоставления удобной сборки приложений, их прошивки и отладки, и многое другое.
Наподобие git и docker, высокоуровневая команда west дает некоторые общие опции (common-opts), субкоманду для запуска с опциями (command, opts), и аргументы для этой субкоманды (args):
west [common-opts] < command> [opts] < args>
Начиная с версии west v0.8 вы также можете запускать west примерно так:
python3 -m west [common-opts] < command> [opts] < args>
Вы можете запустить west --help (или west -h) для получения подсказки верхнего уровня по доступным командам west, а также west < command> -h для подробной подсказки по каждой команде.
На страничке [1] приводится ссылки на документы релиза west v0.14.x, и предоставляется дополнительная контекстная информация по использованию west и Zephyr.
[Инсталляция west]
Утилита west написана на Python 3, и распространяется с помощью PyPI. Используйте pip3 для установки или обновления west.
На Linux:
pip3 install --user -U west
На Windows и macOS:
pip3 install -U west
Примечание: см. Python и pip для дополнительной информации по использованию ключа --user.
Впоследствии вы можете запустить pip3 show -f west для получения информации о том, где находятся установленные бинарники west и связанные с ним файлы.
Как только west установлен, вы можете использовать его для клонирования репозиториев Zephyr.
Структура west. Код west распространяется через PyPI в пакете Python с именем west. Эта дистрибьюция включает исполняемый лаунчер, который также носит имя west (или west.exe на Windows).
Когда west установлен, pip3 поместил лаунчер куда-нибудь в файловую систему пользователя (это полностью зависит от операционной системы, однако все равно файл лаунчера должен быть в переменной окружения PATH). Лаунчер представляет собой точку входа командной строки для запуска встроенных команд наподобие west init, west update, вместе с любыми расширениями, найденными в рабочем пространстве (workspace).
В дополнение к интерфейсу командной строки вы можете также напрямую использовать west Python API [4].
Автозавершение команд для west. В настоящий момент поддерживает автозавершение команд (shell completion) на следующих комбинация платформы/шелла:
Linux/bash macOS/bash
Windows в настоящее время shell completion не поддерживает.
Чтобы разрешить shell completion, необходимо получить соответствующий completion-скрипт, и обращаться к нему каждый раз, когда входите в новую сессию шелла.
Для получения completion-скрипта вы можете использовать команду west completion:
cd /path/to/zephyr/
west completion bash > ~/west-completion.bash
Примечание: когда обновляете Zephyr, помните о необходимости обновления своей локальной копии completion-скрипта, используя команду west completion.
После этого нужно импортировать west-completion.bash в ваш bash shell. На Linux есть следующие опции:
● Копирование west-completion.bash в /etc/bash_completion.d/. ● Копирование west-completion.bash в /usr/share/bash-completion/completions/. ● Копирование west-completion.bash в локальную папку, и обращаться к нему из вашего ~/.bashrc.
На macOS есть следующие опции:
● Копирование west-completion.bash в локальную папку, и обращаться к нему из вашего ~/.bash_profile. ● Установка пакета bash-completion с помощью brew:
brew install bash-completion
После чего ввести основной bash completion-скрипт в свой ~/.bash_profile:
Если вы следовали рекомендациям быстрого старта Zephyr, то ваше рабочее пространство может выглядеть примерно так:
zephyrproject/ # верхняя директория west ├── .west/ # пометка, обозначающая верхнюю деректорию │ └── config # локальный файл конфигурации, который есть в каждом workspace │ │ # Папка манифеста, никогда не модифицируется west после создания: ├── zephyr/ # .git/ repo │ ├── west.yml # файл манифеста │ └── [... other files ...] │ │ # Проекты, которые обслуживает west: ├── modules/ │ └── lib/ │ └── tinycbor/ # .git/ проект ├── net-tools/ # .git/ проект └── [ ... другие проекты ...]
Концепция workspace. Здесь описываются основные термины, которые помогут понять структуру рабочего пространства west. Дополнительную информацию см в документации [8].
topdir
Как было показано выше во врезке "Пример workspace", zephyrproject это имя директории верхнего уровня рабочего пространства, (top level directory, или topdir. Здесь имя zephyrproject приведено просто для примера, и оно может быть любым.
Обычно с помощью команды west init вы создаете topdir и некоторые другие файлы и директории.
Директория .west
Каталог topdir содержит директорию .west. Когда west должен найти topdir, он ищет .west, и использует её как свою родительскую директорию. Поиск начинается с текущей рабочей директории (и запускается снова из места, обозначенного переменной окружения ZEPHYR_BASE в качестве отката, если поиск в текущей рабочей директории закончился неудачей).
Файл конфигурации
Файл .west/config это локальный для workspace файл конфигурации’s (local configuration file).
Репозиторий манифеста
Каждое west workspace содержит ровно один репозиторий манифеста репозитория. Это репозиторий Git, содержащий файл манифеста. Место нахождения репозитория манифеста указывается опцией конфигурации manifest.path в локальном файле конфигурации.
Для текущего проекта Zephyr папка zephyr является репозиторием манифеста, но вы можете конфигурировать west для использования любого репозитория Git в рабочем пространстве в качестве репозитория манифеста. Единственное требование - этот репозиторий должен содержать корректный файл манифеста. См. "Topologies supported" документации [8] для информации по другим опциям, и [9] для информации по формату файла манифеста.
Файл манифеста
Файл манифеста это файл YAML, который определяет проекты, которые в свою очередь дополнительные репозитории Git в рабочем пространстве, которое обслуживает west. Файл манифеста по умолчанию называется west.yml. Это может быть переназначено опцией локальной конфигурации manifest.file.
Вы используете команду west update, чтобы обновить проекты workspace, основываясь на содержимом файла манифеста.
Проекты
Под проектами здесь понимаются репозитории Git, которые обслуживает west. Проекты определяются в файле манифеста, и могут находиться в любом месте внутри workspace. В примере рабочего пространства врезки "Пример workspace" это проекты tinycbor и net-tools.
По умолчанию система сборки Zephyr использует west для получения мест расположения всех проектов в workspace, так что любой код, который они содержат, может использоваться в качестве модулей [10].
Extensions
Любой репозиторий, о котором знает west (либо репозиторий манифеста, либо любой репозиторий проекта) может определять расширения, Extensions [11]. Расширения это дополнительные команды west, которые вы можете запускать, когда используете это workspace.
Репозиторий zephyr использует эту функцию для предоставления относящихся к Zephyr команд, наподобие west build. Определение таких команд в качестве расширений оповещает ядро west о специфике любого рабочего пространства, независимо от версии Zephyr.
Игнорируемые файлы
Workspace может содержать любые дополнительны репозитории Git, или другие файлы и директории, которые west не обслуживает. West в основном игнорирует всё внутри workspace, кроме .west, репозитория манифеста и проектов, указанных в файле манифеста.
[west init и west update]
Две наиболее важные команды, связанные с workspace, это west init и west update.
west init. Эта команда создает west workspace. Важное замечание: west не изменяет ваш репозиторий манифеста после запуска west init. Используйте обычные команды Git, чтобы сделать pull новых версий, и т. п..
Обычно команда west init будет запущена вами только один раз, примерно так:
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. 3. Проверит git-тег v2.5.0 в вашем локальном клоне zephyr. 4. Установит manifest.path для zephyr в .west/config. 5. Установит manifest.file в west.yml.
Теперь ваше workspace практически готово к использованию. Для завершения вам нужно всего лишь выполнить west update для клонирования остальных проектов в workspace.
Для дополнительной информации см. описание встроенных команд [11].
west update. Эта команда синхронизирует содержимое репозиториев Git соответствующих проектов, указанных в файле манифеста.
Важная информация: всякий раз, когда вы берете изменение другой ревизии (checkout) в своем репозитории манифеста, необходимо запустить west update, чтобы гарантировать, что ваше workspace содержит репозитории проектов, которые ожидаются с новыми ревизиями.
Команда west update читает файл манифеста следующим образом:
1. Поиск topdir. В примере west init, приведенном выше, это означает поиск zephyrproject.
2. Загрузка .west/config в topdir для чтения опций manifest.path (например zephyr) и manifest.file (например west.yml).
3. Загрузка файла манифеста, на который указывают эти опции (например zephyrproject/zephyr/west.yml).
Затем используется файл манифеста, чтобы решить, где должны быть помещены с рабочем пространстве отсутствующие проекты, из каких URL их клонировать, и какие ревизии должны быть проверены (checkout) локально. Репозитории проектов, которые уже существуют в рабочем пространстве, будут обновлены по месту путем проверки их ревизий Git на соответствие файлу манифеста.
Для дополнительной информации см. описание встроенных команд [11].
Проблема запуска west update. Хороший способ узнать о причине проблемы - запустить west update в режиме подробного вывода диагностических сообщений (verbose mode):
west -v update
Вывод будет включать вывод команд Git, запущенных west, и его собственный вывод. Это будет выглядеть примерно так:
=== updating your_project (path/to/your/project):
west.manifest: your_project: checking if cloned
[...other west.manifest logs...]
--- your_project: fetching, need revision SOME_SHA
west.manifest: running 'git fetch ... https://github.com/your-username/your_project ...' in /some/directory
В этом примере вывод команды git fetch показывает, что необходимо для успешного завершения west update.
Одна из стратегий решения проблемы - перейти в директорию /some/directory, сделать copy/paste и выполнить запуск всей команды git fetch command, и затем выполнить её отладку с помощью документации по помощнику по хранению ваших учетных данных.
Если вы находитесь за корпоративным сетевым брандмауэром, и наблюдаете проблему с прокси или другие проблемы сетевого доступа, то может помочь curl -v FETCH_URL (для HTTPS URL) или ssh -v FETCH_URL (для SSH URL).
Если вы можете успешно запустить команду git fetch без запроса пароля, когда запускаете команду напрямую, то можно запустить west update без ввода пароля в том же самом shell.
"'west' is not recognized as an internal or external command, operable program or batch file." На Windows это сообщение означает, что либо west не установлен, либо переменная окружения PATH не содержит директорию, куда pip установил лаунчер west.exe.
Сначала проверьте, установлен ли west (см. выше "Инсталляция west"). Затем попробуйте запустить west из нового окна командной строки cmd.exe.
Если проблема с запуском west все еще наблюдается, то нужно найти папку, содержащую west.exe, затем добавить эту папку в свою переменную окружения PATH.
Запустите следующую команду в приглашении cmd.exe:
pip3 show west
1. Найдите строку в выводе наподобие C:\python\python38\lib\site-packages. Точное место расположения west может отличаться, в зависимости от операционной системы и установки на вашем компьютере.
2. Найдите файл west.exe в директории скриптов C:\python\python38\scripts.
Обратите внимание, как lib\site-packages в выводе pip3 show поменялось на scripts!
3. Если вы видите west.exe в директории scripts, то добавьте полный путь до папки scripts в свою переменную окружения PATH, используя команду наподобие следующей:
setx PATH "%PATH%;C:\python\python38\scripts"
Закройте текущее окно cmd.exe, и откройте новое. Теперь west должен запускаться нормально, без необходимости указания полного пути до него.
"Error: unexpected keyword argument 'requires_workspace'". Такая ошибка происходит на некоторых дистрибутивах Linux после обновления 0.6.x до west 0.7.0 или более свежей версии. Например:
$ west update
[... stack trace ...]
TypeError: __init__() got an unexpected keyword argument 'requires_workspace'
Это вероятно происходит из-за проблемы с дистрибутивом pip, подробнее см. комментарий west issue 373 [5]. Известна эта проблема с некоторыми версиями Ubuntu и Linux Mint. Есть сообщение о такой проблеме от некоторых пользователей на Fedora.
Ни на macOS, ни на Windows пользователи с такой проблемой не сталкиваются. Также нет сообщений о проблеме на других дистрибутивах Linux, таких как Arch Linux.
Решение 1. Удалите старую версию, и сделайте апгрейд:
Решение 2. Установите west в виртуальном окружении Python. Одна из опций решения проблемы - использовать модуль venv [6], который является частью стандартной библиотеки Python 3. Некоторые дистрибутивы удаляют этот модуль из своих базовых пакетов Python 3, тогда понадобится добавить модуль venv в вашу систему.
"invalid choice: `build`" (или 'flash', и т. п.). Если вы наблюдаете неожиданную ошибку наподобие этой, по попробуйте запустить команду расширения Zephyr (наподобие west flash, west build, и т. д.):
$ west build [...]
west: error: argument < command>: invalid choice: 'build' (choose from 'init', [...])
$ west flash [...]
west: error: argument < command>: invalid choice: 'flash' (choose from 'init', [...])
Самое вероятное, что вы запускаете команду вне рабочего пространства west. Для west нужно знать, где находится ваше workspace, чтобы найти расширения [7].
Чтобы исправить это, у вас есть 2 варианта:
1. Запустить команду из директории workspace (например, из директории zephyrproject, которую вы создали в самом начале работы с Zephyr).
Например, создайте директорию build внутри workspace, или запустите west flash --build-dir YOUR_BUILD_DIR из директории workspace.
2. Установить переменную окружения ZEPHYR_BASE, и заново запустить команду расширения west. Если эта переменная окружения установлена, то west будет использовать ZEPHYR_BASE, чтобы найти ваше workspace.
Если вы не уверены в том, какая имеется встроенная команда или расширение, запустите west из директории своего workspace. Вывод напечатает команды расширения по отдельности, что для основного проекта Zephyr будет выглядеть примерно так:
$ west help
usage: west [-h] [-z ZEPHYR_BASE] [-v] [-V] < command> ...
The Zephyr RTOS meta-tool.
optional arguments:
-h, --help get help for west or a command
-z ZEPHYR_BASE, --zephyr-base ZEPHYR_BASE
Override the Zephyr base directory. The default is
the manifest project with path "zephyr".
-v, --verbose Display verbose output. May be given multiple times
to increase verbosity.
-V, --version print the program version and exit
built-in commands for managing git repositories:
init: create a west workspace
update: update projects described in west manifest
list: print information about projects
manifest: manage the west manifest
diff: "git diff" for one or more projects
status: "git status" for one or more projects
forall: run a command in one or more local projects
other built-in commands:
help: get help for west or a command
config: get or set config file values
topdir: print the top level directory of the workspace
extension commands from project zephyr (path: zephyr):
completion: output shell completion scripts
boards: display information about supported boards
build: compile a Zephyr application
sign: sign a Zephyr binary for bootloader chain-loading
flash: flash and run a binary on a board
debug: flash and interactively debug a Zephyr application
debugserver: connect to board and launch a debug server
attach: interactively debug a board
zephyr-export: export Zephyr installation as a CMake config
package
spdx: create SPDX bill of materials
blobs: work with binary blobs
extension commands from project hal_espressif (path: modules/hal/espressif):
espressif: Espressif tools for west framework.
Run "west help < command>" for help on each < command>.
"invalid choice: 'post-init'". Если вы видите эту ошибку, когда запускаете west init:
То у вас установлена старая версия west, и вы пытаетесь использовать её в workspace, которое требует более новую версию. Самый простой способ решить проблему это сделать апгрейд west, и попробовать следующее:
1. Инсталлируйте последний west с опцией -U для pip3 install, как было показано выше в разделе "Инсталляция west".
2. Сделайте бекап любого содержимого zephyrproject/.west/config, которое вы хотите сохранить. Если у вас нет установленных параметров конфигурации, то этот шаг можно пропустить.
3. Полностью удалите директорию zephyrproject/.west (если этого не сделать, то получите сообщение об ошибке "already in a workspace", которое обсуждается далее).
4. Снова запустите west init.
"already in an installation". Вы можете встретить эту ошибку, когда запускаете west init с версией west 0.6:
FATAL ERROR: already in an installation (< некая директория>), aborting
Если это неожиданное сообщение, и вы действительно пытаетесь создать новое west workspace, то вероятно west использует переменную окружения ZEPHYR_BASE, чтобы найти workspace, находящееся где-то в вашей системе. Такое поведение west преднамеренное, что позволяет вам поместить приложения Zephyr в любую директорию, и все еще иметь возможность использовать west, например для сборки (build), прошивки (flash), и их отладки.
Для исправления этой проблемы отмените установку переменной окружения ZEPHYR_BASE.
[Ссылки]
1. West (Zephyr’s meta-tool) site:zephyrproject.org. 2. zephyrproject-rtos / west. 3. Python and pip site:zephyrproject.org. 4. West APIs site:zephyrproject.org. 5. Error: unexpected keyword argument 'requires_workspace' #373 site:github.com. 6. venv — Creation of virtual environments python.org. 7. Zephyr Extensions site:zephyrproject.org. 8. Workspaces site:zephyrproject.org. 9. West Manifests site:zephyrproject.org. 10. Modules (External projects) site:zephyrproject.org. 11. west Extensions site:zephyrproject.org. 12. west Built-in commands site:zephyrproject.org.
