Консольный клиент ABF — различия между версиями

Материал из Rosalab Wiki
Перейти к: навигация, поиск
(copy: translate)
(pullrequest: translate)
Строка 272: Строка 272:
  
 
==pullrequest==
 
==pullrequest==
Send a pull request from SRC_BRANCH to DST_BRANCH
+
Отправить запрос на перенос изменений ("pull request") из ветки или метки SRC_BRANCH git-репозитория проекта в ветку DST_BRANCH этого же проекта.
  
 
'''Запуск и опции:'''
 
'''Запуск и опции:'''
  
 
''abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body
 
''abf pullrequest [-h] [-p PROJECT] [-v] from_ref to_ref title body
 
+
* '''<from_ref>''': ветка-источник
'''Positional arguments:'''
+
* '''<to_ref>''':  целевая ветка
* '''<from_ref>''': source ref or branch
+
* '''<title>''':    название запроса
* '''<to_ref>''':  destination ref or branch
+
* '''<body>''':    комментарий к запросу
* '''<title>''':    Request title
+
* '''-p <имя_проекта>, --project <имя_проекта>''': имя проекта в формате "владелец/название" (например, "import/gcc"). По умолчанию используется проект, в директории которого выполняется команда
* '''<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==
 
==status==

Версия 15:20, 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

Копировать файлы из одной ветки 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.


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