Версия 15:57, 20 февраля 2014

Введение

Консольный клиент ABF предназначен для поддержки работы с 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

Initiate a build task on ABF. There are lots of options, but in most cases it works great with no options at all. abf-console-client tries to automatically resolve all the options needed. How does it work: read notes and examples.

Запуск и опции: abf build [--project <имя_проекта>] [--branch <branch>] [--tag <tag>] [--commit <commit>] [--save-to-repository <repository>] [--repository <repository>] [--arch <arch>] [--auto-publish] [--update-type <type>] [--skip-spec-check]

• -p/--project <имя_проекта>: project name ([group/]project). If the option is not specified and you are in a git repository directory - a project name will be resolved automatically.
• -b/--branch <branch>: git branch name to build. Read notes.
• -t/--tag <tag>: git tag to build. Read notes.
• -c/--commit <commit>: git commit sha hash to build. Read notes.
• -s/--save-to-repository <repository>: repository to save results to. If no platform part specified, it is assumed to be "<default_group>_personal". If this option is not specified at all and you are in a git repository, it will be resolved automatically (read notes).
• -r/--repository <repository>: repositories to build with. Can be set more than once. If no platform part specified, it is assumed to be your "<default_build_platform>". If no repositories were specified at all, it will be resolved automatically (read notes).
• -a/--arch <arch>: аппаратная архитектура, под которую должна производиться сборка. Опцию можно указать несколько раз. Если опция не задана, то сборка производится для архитектур i586 и x86_64.
• --auto-publish: в случае успешной сборки, автоматически публиковать собранные пакеты в целевой репозиторий.
• --update-type <type>: Тип обновления. Допустимые значения: security, bugfix, enhancement, recommended, newpackage. По умолчанию используется "bugfix".
• --skip-spec-check: Не осуществлять проверки spec-файла и .abf.yml (см. описание команды clean).

Notes:

Console client tries to automatically resolve all the options without taking into account anything except --branch. If it fails - use only user-given options. If succeeds, but user specified other parameters - discard everything we've resolved and use only user-given options.

Git hash resolving:

• Одновременно можно указать только одну из опций "--branch", "--tag" или "--commit".
• Если вы указали хэш коммита в git-репозиторий, то он будет использован "как есть".
• Если вы указали имя ветки или тэга, то для них с помощью ABF API будет автоматически определен хэш последнего коммита, относящегося к ветке или тэгу, и для него будет запущена сборка.
• Если вы не указали ни одной из опций "--branch", "--tag" или "--commit", не указали имени проекта с помощью опции "-p", но находитесь в директории проекта, то сборка будет запущена для последнего коммита текущего проекта, отправленного на сервер.
• Если вы указываете имя проекта с помощью опции "-p", то вам необходимо обязательно указать одну из опций "--branch", "--tag" или "--commit".

Обработка остальных опций:

• если не указана опция --arch, то сборка производится для архитектур i586 и x86_64.
• build repository can usually be resolved from a git branch name. If there is a build platform with the name of your current git branch exists - it will be used.
• save-to repository: if some repository from a build platform can be used as save-to repository - it will be used.

You can execute abf build (with no options) when you've specified a branch name (or it's resolved automatically) and there is a platform on ABF having the same name. In this case a save-to repository will be selected from a list of available save-to repositories for this platform. Build repositories are repositories of this platform too("main" and one another repository if needed for selected save-to repository).

Примеры:

• Build a current branch of a local cloned project. Build and save-to repositories can be resolved from branch name: abf build
• Build a project without a local git repository. Build and save-to repositories can be resolved from branch name: abf build --project import/gcc --branch rosa2012.1
• Build a project to another platform: abf build --project import/gcc --branch rosa2012.1 --save-to-repository rosa2012lts/contrib. Build repositories will be rosa2012lts/main and 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

Показать информацию о сборочном задании. It will print something like that:

 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 <имя_проекта>: Project. If last IDs for this project can be found in local database - use them. Otherwise, print error message end exit.
• -s, --short: Show only one-line information including id, project, arch and status.

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 секунды, однако все результаты обращения к автоматическому дополнению кэшируются и последующие вызовы проходят гораздо быстрее.