Консольный клиент ABF
Содержание
Введение
Консольный клиент ABF предназначен для поддержки работы с ABF из командной строки и поддерживает наиболее часто выполняемые действия с проектами на ABF - модификацию, сборку и публикацию.
В РОСЕ консольный клиент ABF входит в пакет abf-console-client и запускается из командной строки командой abf.
Первый запуск и настройки
При первом запуске, консольный клиент попросит вас задать параметры настройки и значения для некоторых опций, которые будут использоваться по умолчанию. Все эти настройки будут сохранены в файл .abfcfg в вашей домашней директории. Для изменения настроек, отредактируйте этот файл либо удалите его и запустите команду abf. Обратите внимание, что в этом файле также хранятся определения псевдонимов (см. секцию ниже), и при удалении файла они будут потеряны.
Getting Started
Типичные действия с проектами посредством консольного клиента выполняются следующим образом:
- Клонирование репозитория проекта
abf get <имя_проекта>
Имя проекта может включать его владельца (в формате <владелец>/<имя_проекта> - например, import/gcc). Если владельца не указывать, то используется значение по умолчанию из настроек клиента.
Эта команда эквивалентна вызову "git clone" со ссылкой на репозиторий проекта.
- Применить все изменения, сделанные локально в git-репозитории, и отправить их в git-репозиторий на ABF
abf put -m <сообщение>
Эта команда сначала ищет в текущей директории бинарные файлы (например, архивы с исходным кодом), которые упомянуты в spec-файле, и помещает их в файловое хранилище ABF, прописывая соответствующий файлу идентификатор в файл .abf.yml. Затем клиент определяет, какие из файлов, уже присутсвующие в .abf.yml, больше не используются в spec-файле проекта и не нужны при сборке. Такие файлы перемещаются в секцию "removed sources" файла .abf.yml; они не будут загружаться из файлового хранилища при сборке на ABF. После этих дейтсивй, "abf put" запускает последовательность команд "git add --all; git commit -m MSG; "git push".
- Запустить сборку
abf build
при запуске без аргументов, эта команда смотрит на текущую ветку Git-репозитория, запрашивает у сервера ABF информацию о привязке этой ветки к репозиториям дистрибутивов и запускает сборку проекта с использованием текущей ветки для целевого репозитория дистрибутива. Ветку Git и целевой репозиторий дистрибутива можно указать с помощью дополнительных параметров.
- Узнать статус сборки
abf status ID
Эта команда выводит информацию о состоянии сборочного задания с заданным идентификатором. Если идентификатор опущен, будет напечатан статус последней запущенной вами сборки.
- Опубликовать результаты сборки в репозиторий
abf publish ID
Если сборка завершилась успешно, то с помощью этой команды можно опубликовать собранные пакеты в целевой репозиторий дистрибутива. Заметьте, что можно попросить ABF автоматически публиковать пакет в случае успеха, указав при вызове "abf build" опцию "--auto-publish". Однако для этого автоматическая публикация должна быть разрешена настройками репозитория, а также в целевом репозитории дистрибутива не должно содержаться пакета с таким же именем, версией и релизом, как собранный.
Пример
Давайте склонируем проект import/gcc project модифицируем его (например, положим новый архив с исходным кодом и обновим spec-файл) и пересоберем пакет.
- Cклонировать репозиторий проекта и перейти в его папку
abf get import/gcc -b rosa2012.1 cd gcc
- <производим действия по модификации пакета - кладем новый архив с исходным кодом, модифицируем spec-файл и так далее>
- Загрузить новый архив с исходным кодом в файловое хранилище ABF, прописать ссылку на него в файл .abf.yml и отправить все изменения в git-репозиторий на ABF
abf put -m "Обновленная версия gcc"
- Запустить сборку обновленного проекта на ABF
abf build
(заметьте, что эта команда печатает идентификаторы запущенных задач - они могут вам пригодиться позже, для запроса статуса сборок. Эти идентификаторы также записываются в файл ~/.abf_projects)
- Узнать статус сборки
- эта команда выведет статус последней запущенной вами сборки:
abf status
- а также можно узнать статус сборочных заданий с заданными идентификаторами:
abf status <ID1> <ID2> ...
- Если сборка завершилась успешно, то можно опубликовать ее в репозиторий:
abf publish <ID1> <ID2> ...
Описание команд
Ниже дан список команд, официально поддерживаемых последней версией консольного клиента ABF. Вы можете запустить abf --help или abf help' для получения описаний команд, поддерживаемых вашей вресией клиента.
help
Получение детальной справки по конкретной команде (обратите внимание, что наряду с abf help <имя_команды> вы можете использовать abf <имя_команды> -h/--help)
Запуск и опции:
abf help <имя_команды>
- <имя_команды>: Имя команды, для которой необходимо вывести справку.
alias
Управление псевдонимами консольного клиента. Псевдонимы используются для краткой записи часто используемых команд, сокращая время на их вызов.
Например, если вы в большинстве ваших проектов работаете в git-веткой rosa2012.1, то вам приходится ихз клонировать командой "abf get -b rosa2012.1" (или выполнять сначала "abf get", а потом переходить в директори склонированного проекта и выполнять там "git checkout rosa2012.1").
Однако вместо этого, вы можете определить псевдоним на сочетание опций "get -b rosa2012.1". Например, назвав этот псевдоним одной буквой "g", вы сможете просто запускать команду "abf g" и получать тот же эффект, что и при запуске "abf get -b rosa2012.1".
Заметьте, что псевдоним может замещать только часть опций и использоваться в любом месте в строке вызова. Например, можно назначить псевдоним "pack" для сочетания "rosa2012.1 build_branch -p" и запускать "abf copy pack" для копирования содержимого ветки rosa2012.1 в ветку build_branch со сжатием.
Запуск и опции:
abf alias <action> param1 [param2] [...]
- <action>: Одно из действий: list, add, remove.
list
Вывести перечень доступных псевдонимов. По умолчанию доступны следующие псевдонимы:
b: build
sp: search projects
su: search users
st: status
s: store
spl: search platforms
sg: search groups
add
Добавить псевдоним. Необходимо указать как минимум два аргумента - первый является именем псевдонима, а все остальные образуют его тело. Например, abf alias add sg search groups добавит псевдоним sg, который при вызове клиента будет заменяться на "search groups".
remove
Удалить псевдоним. В качестве аргумента необходимо передать имя псевдонима, например abf alias remove sg.
clean
Провести анализ spec-файла и файла .abf.yml на пердмет ошибок. в первую очередь, команда "abf clean" проверяет доступность всех файлов с исходным кодом и патчей, перечисленных в spec-файле - эти файла должны либо присутсвовать в локальной директории, либо быть указаны в основной секции .abf.yml, либо для них должны быть указаны ссылки в сети Интернет. Также осуществляется проверка корректности spec-файла - если его не удается обработать средствами RPM, то выводится соответствующая ошибка.
Отметим, что эти проверки (доступность исходных файлов и корректность spec-файлов) производятся автоматически перед запуском каджой сборки посредством "abf build". Если эти проверки находят ошибки, то консольный клиент откажется запускать сборку проекта (это поведение может быть переопределено опцией "--skip-spec-check").
В дополнение косновным проверкам, "abf clean" выводит предупреждения о файлах, которые одновременно прописаны в .abf.yml и для которых указаны Интернет-адреса в spec-файле.
Запуск и опции: abf clean [--auto-remove]
- -a/--auto-remove: автоматически удалять все ненужные файлы.
get
Склонировать удаленный git-репозиторий по его владельцу и имени на локальную машину. Например, abf get import/gcc склонирует проект gcc из группы import. Проект будет склонирован в текущую директорию. Если в директории уже есть поддиректория, чье имя совпадает с именем проекта, консольный клиент откажется выполнять клонирование и выдаст соответсвующее предупреждение.
Запуск и опции:
abf get <имя_проекта> [--branch <имя_ветки>]
- <имя_проекта>: имя проекта для клонирования в формате <владелец>/<название> (например, import/gcc). Если имя владельца не указывать, то используется значение по умолчанию из настроек консольного клиента.
- -b/--branch <имя_ветки>: имя ветки git-репозитория, которая будет автоматически сделана активной после клонирования (то есть после клонирования abf дополнительно вызовет команду "git checkout <имя_ветки> внутри директории проекта").
put
Загрузить изменения в проекте, сделанные локально, на сервер ABF.
Первым шагом комагда "abf put" загружает бинарные файлы из текущей директории на файловый сервер ABF и добавляет их идентификаторы в файл .abf.yml. После этого определяются файлы, указанные в .abf.yml, которые больше не нужны для сборки (не упоминаются в spec-файле проекта). Такие файлы перемещаются в секцию removed_sources файла .abf.yml; они не будут извлекаться при сборке проекта на ABF. после этого все изменения в проекте, сделанные локально применяются и отправляются в удаленный git-репозиторий (аналогично командам "git add --all", "git commit" и "git push"). По умолчанию бинарные файлы, загруженные на файловый сервер ABF, из текущей директории удаляются.
Запуск и опции:
abf put [--message <сообщение>] [--minimal-file-size <size>] [--do-not-remove-files]
- -m/--message <сообщение>: комментарий к изменениям (передается команде "git commit")
- -s/--minimal-file-size <size>: минимальный размер бинарного файла, при превышении которого файл загружается на файловый сервер. По умолчанию используется 0, то есть на файловый сервер загружаются все бинарные файлы.
- -n/--do-not-remove-files: Не удалять бинарные файлы из текущей директории после их загрузки на файловый сервер ABF.
Замечание: Консольный клиент использует легковесный анализатор spec-файлов и не всегда может корректно определить, нужен тот или иной бинарный файл для сборки или нет. В случае неопределенности считается, что файл нужен, и он остается в основной секции файла .abf.yml. Поэтому имеет смысл периодически просматривать .abf.yml и производить их ручную чистку от ненужных файлов - это позволит ускорить сборку проектов за счет снижения расходов на исвлечение ненужных файлов из файлового хранилища.
store
Загрузить заданный файл на файловое хранилище ABF. В случае успеха, клиент напечатает идентификатор файла (sha1-сумму).
Если файл с такой же хэш-суммой уже присутствует в файловом хранилище, но он не будет перезаписан.
Запуск и опции: abf store <path>
- <path>: Путь к файлу для загрузки.
fetch
Загрузить все файлы, указанные в основной секции файла .abf.yml, в текущую директорию. Файлы, указанные в секции "removed_sources", не загружаются.
Запуск и опции:
abf fetch [--only <file_name>]
- -o/--only <file_name>: Limit the list of downloaded files to this file name(s). This option can be specified more than once.
show
Показать детальные сведения о проекте. Эта команда используется для автодополнения в оболочке Bash.
Запуск и опции:
abf show <target> [--project <имя_проекта>]
- <target>: Какую именно информацию показывать. Доступные варианты:
- build-repos - репозитории, которые можно подключать при сборке проекта
- build-platforms - платформы, репозитории которых можно подключать при сборке проекта
- save-to-repos - репозитории, в которые можно публиковать результаты сборки проекта (пакеты)
- save-to-platforms - платформы, в репозитории которых можно публиковать результаты сборки проекта (пакеты)
- -p/--project <имя_проекта>: Имя проекта, о котором необходимо показать информацию. Если вы находитесь внутри git-репозитория проекта, то можно эту опцию не указывать, в этом случае будут выведены данные о текущем проекте.
Замечание: в имя репозитория всегда включается имя платформы, к которой он относится - например, "rosa2012.1/main" соответствует репозиторию "main" платформы "rosa2012.1".
locate
Управление базой данных о локальных репозиториях.
Консольный клиент поддерживает локальную базу данных (в виде текстового файла .abf_projects в вашей домашней директории), в которой содержатся пути (в локальной файловой системе) к репозиториям, которые вы клонировали с помощью клиента abf, и идентификатор последнего сборочного задания, относящегося к этому проекту. Эта база используется командой abfcd для быстрого перехода в директории проектов (см. раздел "Дополнительные возможности").
"abf locate" может быть использована для просмотра и изменения информации о локальных репозиториях проектов.
Запуск и опции:
abf locate [<action>] [--project <имя_проекта>] [--directory <директория>]
- <action>: одно из действий "update" или "update-recursive". Эти действия заставляют abf просканировать директорию, указанную с помощью опции "-d", на предмет наличия в них клонированных проектов, и добавить найденные проекты в базу данных. update добавит проект только в случае, если указанная директория и является директорией с клонированным проектом. "update-recursive" рекурсивно просканирует все директории в указанной и добавит в базу данных все найденные там проекты. Если действие не указано, то команда выведет путь к локальному репозиторию для заданного проекта
- -p/--project <имя_проекта>: имя проекта, о котором надо вывести информацию, в формате <владелец>/<имя>. Если владелец не задан, используется значение по умолчанию из настроек клиента.
- -d/--directory <директория>: директория, которая будет просканирована на предмет наличия в ней проектов, при указании действий "update" или "update-recursive".
build
Запустить сборку проекта на ABF.
Обратите внимание, что несмотря на большое количество доступных опций, консольный клиент способен автоматически определять все необходимые параметры сборки при условии, что вы вызываете "abf build" из директории проекта, который хотите собрать, и активна та ветка git-репозитория, которую необходимо использовать для сборки.
Запуск и опции: abf build [--project <имя_проекта>] [--branch <ветка> | --tag <тэг> |--commit <коммит>] [--save-to-repository <repository>] [--repository <repository>] [--arch <arch>] [--auto-publish] [--update-type <type>] [--skip-spec-check]
- -p/--project <имя_проекта>: Имя проекта в формате <владелец>/<название>. Если имя не указано, но вы запускаете команду "abf build" из директории некоторого проекта, то на будет запущена сборка этого проекта.
- -b/--branch <ветка>: ветка git-репозитория, которую надо использовать для сборки
- -t/--tag <тэг>: тэг в git-репозитории, который надо использовать для сборки
- -c/--commit <коммит>: хэш коммита в git-репозитории, который надо использовать для сборки
- -s/--save-to-repository <repository>: целевой репозиторий, для которого будет производиться сборка, в формате "<платформа>/<имя_репозитория>". Если платформа не указана, используется персональная платформа для группы по умолчанию ("<default_group>_personal"). Если эта попция не указана, но вы находитесь в git-репозитории проекта, то будет выбрана платформа, которой соответсвует текущая ветка в вашем git-репозитории, и репозиторий этой платформы, к которому этот проект привязан. Вы можете использовать команду "abf show" чтобы узнать, какие значения будут выбраны для этой опции автоматически.
- -r/--repository <repository>: репозитории, которые необходимо подключить в дополнение к целевому для сборки проекта, в формате "<платформа>/<имя_репозитория>". Эта опция может быть указана несклько раз. Если в имени репозитория опущена платформа, то выбирается целевая платформа по умолчанию ("<default_build_platform>" в файлах настроек консольного клиента ABF). Если эта опция вообще не указана, то ее значение определяется автоматически на основе сведений от ABF.
- -a/--arch <arch>: аппаратная архитектура, под которую должна производиться сборка. Опцию можно указать несколько раз. Если опция не задана, то сборка производится для архитектур i586 и x86_64.
- --auto-publish: в случае успешной сборки, автоматически публиковать собранные пакеты в целевой репозиторий.
- --update-type <type>: Тип обновления. Допустимые значения: security, bugfix, enhancement, recommended, newpackage. По умолчанию используется "bugfix".
- --skip-spec-check: Не осуществлять проверки spec-файла и .abf.yml (см. описание команды clean).
Выбор версии исходного кода и Git-репозитория
- Одновременно можно указать только одну из опций "--branch", "--tag" или "--commit".
- Если вы указали хэш коммита в git-репозиторий, то он будет использован "как есть" - из репозитория будет извлечен исходный код, соответсвующий этому коммиту.
- Если вы указали имя ветки или тэга, то для них с помощью ABF API будет автоматически определен хэш последнего коммита, относящегося к ветке или тэгу, и для него будет запущена сборка.
- Если вы не указали ни одной из опций "--branch", "--tag" или "--commit", не указали имени проекта с помощью опции "-p", но находитесь в директории проекта, то сборка будет запущена для последнего коммита текущего проекта, отправленного на сервер.
- Если вы указываете имя проекта с помощью опции "-p", то вам необходимо обязательно указать одну из опций "--branch", "--tag" или "--commit".
Обработка остальных опций:
- Если не указана опция --arch, то сборка производится для архитектур i586 и x86_64.
- Целевая платформа определяется на основе имени текущей ветки git-репозиотрия. Если существует платформа, имя которой совпадает с именем текущей ветки, то выбирается она. Также в клиенте есть несколько предопределенных значений (например, для проектов из группы openmandriva ветка master проассоциирована с платформой cooker).
- Целевой репозиторий определяется посредством запроса к ABF - консольный клиент запрашивает сервер, к какому репозиторию прикреплен проект на целевой платформе. Если такого репозитория нет (проект никуда не прикреплен), то клиент откажется запускать сборку и выдаст сообщение об ошибке.
Примеры:
- Запустить сборку проекта, в директории которого мы находимся. Использовать текущую ветку, все параметры определить автоматически:
abf build
- Запустить сборку проекта, отсутсвующего в локальной файловой системе, из заданной ветки. Целевой репозиторий и репозитории, которые необходимо подключить дополнительно, будут определены автоматически
abf build --project import/gcc --branch rosa2012.1
- Собрать проект под конкретную платформу; репозитории, которые необходимо подключить дополнительно, будут определены автоматически:
abf build --project import/gcc --branch rosa2012.1 --save-to-repository rosa2012lts/contrib
mock-urpm
Собрать проект локально с использованием mock-urpm. Для сборки используется текущее состояние локального репозитория.
Запуск и опции:
abf mock-urpm [-c <config>]
- -c/--config <config>: A config template to use. Specify one of the config names from /etc/abf/mock-urpm/configs/. Directory path and extension (".cfg") should be omitted. If no config specified, "default.cfg" will be used. Autocompletion worsk for config names.
Замечание:
- Перед сборкой пакета вызывается "abf fetch". При этом если вы в текущей директории модифицировали какой-то файл, который прописан в .abf.yml, то ваш файл будет перезаписан версией из файлового хранилища.
- Сборка с помощью mock-urpm производится в директории /var/lib/abf/mock-urpm.
rpmbuild
Собрать проект локально с использованием rpmbuild. Для сборки используется текущее состояние локального репозитория.
Запуск и опции:
abf rpmbuild [-h] [-b {b,s,a}] [-v]
- -b {b,s,a}, --build {b,s,a} - собрать SRPM-пакет (s), бинарный RPM-пакет (b) или оба (a)
publish
Опубликовать успешно завершенное сборочное задание.
Запуск и опции:
abf publish <task_id> [<task_id>] [...]
- <task_id>: идентификатор сборочного задания
copy
Копировать файлы из одной ветки git-репозитория в другую. Также возможно копирование между ветками различных проектов. Будьте осторожны, существующие файлы в целевой ветке будут перезатерты!
Запуск и опции:
- <src_branch>: Исходная ветка, из которой копируются файлы
- <dst_branch>: Целевая ветка, в которую копируются файлы. Если этот аргумент пропущен, файлы копируются в текущую ветку
- -p/--pack: Создать архив в формате tar.gz из файлов исходной ветки и скопировать в целевую ветку этот архив, а не сами файлы
pullrequest
Отправить запрос на перенос изменений ("pull request") из ветки или метки SRC_BRANCH git-репозитория проекта в ветку DST_BRANCH этого же проекта.
Запуск и опции:
abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body
- <from_ref>: ветка-источник
- <to_ref>: целевая ветка
- <title>: название запроса
- <body>: комментарий к запросу
- -p <имя_проекта>, --project <имя_проекта>: имя проекта в формате "владелец/название" (например, "import/gcc"). По умолчанию используется проект, в директории которого выполняется команда
status
Показать информацию о сборочном задании. Выводит сведения в следующем виде:
Buildlist ID: 944492 User: akirilenko Project: import/mock-urpm Status: build has been published Build for platform: rosa2012.1 Save to repository: rosa2012.1/main Build repositories: [rosa2012.1/main] Architecture: i586 Created at: 2013-02-12 15:25:09 Updated at: 2013-02-12 15:43:16
Запуск и опции:
abf status [--project <имя_проекта>] [--short]
- -p/--project <имя_проекта>: Если не указан идентификатор сборочного задания, но указано имя проекта с помощью этой опции, то консольный клиент извлечет идентификатор последнего запущенного сборочного задания для этого проекта из локальной базы данных (если такое хначение там есть) и отобразит его статус.
- -s, --short: показать информацию в сжатом виде (одна строка - идентификатор сборки, имя проекта, архитектура и статус).
search
Поиск по ABF.
Запуск и опции:
abf search <target> "<query>"
- <target>: область поиска; допустимые значения:
- users - пользователи
- groups - группы
- platforms - платформы
- projects - проекты
- <query>: Строка для поиска. Регулярные выражения и шаблоны не поддерживаются.
test
Запустить набор внутренних тестов.
Эта команда может быть использована для проверки исправности консольного клиента и окружения. В штатном режиме работы, тесты не должны выявлять никаких проблем и должны печатать результирующую фразу "Datamodel seems to work fine".
Дополнительные возможности
Кэш локального местоположения проектов
Консольный клиент ABF запоминает метоположение в файловой системе всех репозиториев, склонированных с его помощью. За счет этого, вы можете быстро перемещаться между склонированными проектами с помощью команды "abfcd":
abfcd <имя_проекта>
Эта информация хранится в файле .abf_projects в вашей домашней директории.
Узнать местоположение проекта в вашей файловой системе можно с помощью следующей команды:
abf locate -p <имя_проекта>
Если у вас есть набор репозиториев, отсутствующих в кэше консольного клиента (например, если они были склонированы непосредственно с помощью команды git, или если вы удалили файл .abf_projects), вы можете заставить консольного клиента просканировать заданную директорию и поместить в кэш все проекты, которые он там найдет:
abf locate update-recursive -d <путь_к_директории_с_проектами>
Помимо команды "abfcd", информация из файла .abf_projects используется при перемещении файлов между различными проектами с помощью консольного клиента ABF.
Автодополнение в Bash
Консольный клиент ABF предоставляет богатые возможности по автоматическому дополнению команд и опций при использовании в оболочке Bash. В частности, он способен предлагать варианты дополнения для имен опций, веток git, целевых репозиториев для сборки (параметров build и save-to команды "abf build") и множества других команд. Это существенно облегчает работу с клиентом, поскольку отпадает необходимость в ручном вводе длинных имен и запоминании большого количества опций. В некоторых случаях автоматическое дополнение может работать более 1 секунды, однако все результаты обращения к автоматическому дополнению кэшируются и последующие вызовы проходят гораздо быстрее.
