Версия 14:52, 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-файле.

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

Управление локальным кэшем репозиториев.

Console client tends to maintain a database of local projects: while any interaction with your local git repository via abf-console-client, it stores the path to this repository. After that you can call abfcd [<project_group>/]<project_name> (omit group_name to use your default) to change your current working directory to the project's path (if it had been stored before). If you just want to get a project path without changing directory, use abf locate -p <имя_проекта>.

You can also add projects to this database by manually. To add only one project call abf locate update -d /path/to/project. To scan directory recursively and add all the found projects, call abf locale update-recursive -d /path/to/directory.

Запуск и опции:

abf locate [<action>] [--project <имя_проекта>] [--directory <directory>]

• <action>: одно из действий "update" или "update-recursive". update will update
• -p/--project <имя_проекта>: Project to show information for (if needed). Format: "[group/]name". If no group specified, your default group will be used.
• -d/--directory <directory>: Directory to update locations for. It should be a git repository for "update" and any directory for "update-recursive". If not specified - the current directory will be used.

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>: architectures to build for. Can be set more than once. If not set - use all the available architectures for the project given.
• --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:

• Only one of --branch, --tag or --commit options can be used at once.
• If you've specified commit hash - it will be used "as is".
• If you've specified branch or tag name - commit hash will be resolved automatically using ABF API. (the hash of top commit in the branch will be used for branch)
• If you've specified a project name - you have to specify a branch, tag or commit manually.
• If you've specified no branch, tag or commit hash and you've not specified a project name (you have to be in a git repository) - the top remote commit of your current branch will be used.

Other options resolving:

• if no --arch specified, use all the available project architectures.
• 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

Copy files from one git branch to another. Be careful: all the files from destination branch will be removed, and replaced by the files from a source branch.

This command can be useful to keep sources of the project in one branch and build package in another. Just execute abf

Запуск и опции:

• <src_branch>: A branch to copy files from.
• <dst_branch>: A branch to copy files to. If not specified, it's assumed to be the current branch.
• -p/--pack: Create a tar.gz from the <src_branch> and put this archive and spec file to <dst_branch>.

pullrequest

Send a pull request from SRC_BRANCH to DST_BRANCH

Запуск и опции:

abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body

Positional arguments:

• <from_ref>: source ref or branch
• <to_ref>: destination ref or branch
• <title>: Request title
• <body>: Request body

Optional arguments:

• -p PROJECT, --project PROJECT: project name (group/project). By default, the project is used in whose folder this command is launched

-v, --verbose: be verbose, display even debug messages

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.

clean

Analyze spec file and show missing and unnecessary files from the current git repository directory.

Запуск и опции:

abf clean [--auto-remove]

• -a/--auto-remove: автоматически удалять все ненужные файлы.

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