Gear/gear-uupdate

Назначение gear-uupdate

gear-uupdate(1) (uu, два u) --- утилита для автоматического обновления gear репозитория из архива с исходниками "правильным образом". Она умеет читать .gear-rules, находить место и ветвь, где хранятся распакованные исходники, обновлять их, мержить результат в ветви с патчами и в главную ветвь.

Не путать с утилитой gear-update, предназначенной для распаковки архива с исходниками в указанный каталог с регистрацией результата в git. gear-uupdate вызывает gear-update в процессе своей работы.

Утилита является аналогом для ALT Linux утилиты uupdate(1) из Debian, предназначенной для обновления .deb пакетов с помощью watch файлов совместно с утилитой uscan(1), и совместима с ней по аргументам и формату вызова.

В ALT Linux gear-uupdate(1) может неявно вызываться утилитами rpm-uscan(1) или gear-cronbuild-apply-hooks(1) для автоматизированного обновления gear репозитория, либо же ее можно использовать вручную для облегчения процесса обновления gear репозитория.

принцип работы и поддерживаемые репозитории.

gear-uupdate c помощью библиотеки perl-Gear-Rules читает .gear[-/]rules, изучая директивы tar и diff, вычисляет, в какой ветке (и каком подкаталоге если есть) находятся исходники, есть ли отдельные ветви для патчей, если исходники в отдельной ветке, то как ее потом мержить в ветку с .gear (просто или с -s ours).

Поддерживаются все основные разумные схемы gear, в частности, описанные в статье Руководство по gear

Проверить, поддерживается ли конкретная схема gear репозитория, можно с помощью утилиты gear-rules-verify.

gear-rules-verify 

выдаст подробную диагностику, совместим ли репозиторий с gear-uupdate(1). В частности, если в репозитории есть коммиты, автор которых не состоит в team, то gear-uupdate откажется работать. Логика здесь в том, что похоже, репозиторий ранее обновлялся из апстримного git/svn/otherVCS, а теперь мы хотим обновить его из тарбола. как правило, так делать не надо. Вместо полученного треш-репозитория лучше завести новый git репозиторий или залить обновление как srpm.

Дополнение. subtree merge

Начиная с версий perl-Gear-Rules-0.196 gear-uupdate-0.26 ограниченно поддерживается схема gear репозитория, в которой upstream репозиторий мержится в поддерево (subtree merge). Поддерживается только схема, у которой в .gear/rules есть команда diff:. К примеру,

$ cat .gear/rules 
tar: @version@:.
diff: @version@:. @name@

gear репозиторий, в которой upstream репозиторий мержится в поддерево (subtree merge), но нет diff, не поддерживается. Это не рекомендуемый формат: вы упаковываете в src.rpm "грязные" исходники; рекомендуется упаковывать "чистые" исходники из апстримного тега и отдельно ваш(и) патч(и). Но такой репозиторий легко преобразовать к поддерживаемому, просто заменив в .gear/rules

tar: @name@

на схему с тегом

tar: @version@:.
diff: @version@:. @name@

или схему с названием апстримной ветви

tar: upstream:.
diff: upstream:. @name@

и добавив по необходимости в спек сгенерированный патч, если он не пуст.

запуск утилиты вручную

gear-uupdate(1) -- это обертка над парой утилит gear-uupdate-prepare(1) и gear-uupdate-execute.

Руками gear-uupdate запускают так:

gear-uupdate --upstream-version 6.8.9.3 ImageMagick-6.8.9-3.tar.xz

либо так

gear-uupdate ImageMagick-6.8.9-3.tar.xz 6.8.9.3

При первом запуске лучше не запускать сразу gear-uupdate, а запустить

gear-uupdate-prepare --upstream-version 6.8.9.3 ImageMagick-6.8.9-3.tar.xz

gear-uupdate-prepare сначала выполнит проверки из gear-rules-verify.

Затем, gear-uupdate-prepare (ничего не меняя в репозитории) генерирует набор shell скриптов. Эти скрипты могут быть созданы в корне gear репозитория, если апстрим в подкаталоге в текущей ветке. в остальных случаях скрипты надо прятать от git, поэтому они создаются в папке .git/uupdate/.

После выполнения gear-uupdate-prepare в .git/uupdate/ будет что-то вроде

__~.uupdate-step-001-checkout-and-update-upstream-branch.sh
__~.uupdate-step-002-merge-upstream-to-patch1-branch.sh
...
__~.uupdate-step-006-merge-upstream-to-patch5-branch.sh
__~.uupdate-step-007-merge-upstream-to-master.sh
__~.uupdate-step-008-update-spec-and-tags.sh

Эти скрипты можно просмотреть и убедиться еще раз, что робот понял структуру репозитория правильно. После чего их можно выполнить с помощью gear-uupdate-execute.

Утилита gear-uupdate-execute по очереди выполняет сгенерированные скрипты, удаляя скрипт, если он отработал нормально. Во многих схемах устройства gear репозитория изменения автора и изменения майнтайнера мержатся с помощью git, при чем, возможно, ветвь с оригинальными исходниками необходимо будет мержить в несколько ветвей. Для таких операций достаточно часто возникают конфликты.

Если конфликт при merge произошел, то gear-uupdate-execute остановится на скрипте, который завершился с ошибкой. git при этом будет в той ветви, в которой происходил merge. В таком случае майнтайнеру необходимо будет вручную разрешить конфликт в исходных файлах, и закоммитить изменения в git. При этом скрипт __~.uupdate-step-*, на котором произошел сбой, можно использовать в качестве готового шаблона команд. Затем можно удалить этот скрипт, и опять запустить gear-uupdate-execute, который выполнит оставшиеся скрипты.

Если убедиться, что gear-uupdate-prepare/gear-uupdate-execute отрабатывают нормально, далее уже сразу можно запускать gear-uupdate.

запуск gear-uupdate из-под других утилит

rpm-uscan (и gear-cronbuild) обучены запускать gear-uupdate самостоятельно.

rpm-uscan с обычным watch файлом по умолчанию только проверяет наличие обновлений и скачивает их. gear-uupdate при этом не вызывается.

Есть 2 варианта, как заставить rpm-uscan сразу после скачивания вызвать gear-uupdate, чтобы тут же обновить gear репозиторий скачанным файлом:

1) вызвать rpm-uscan с опцией --force-action <user action>:

rpm-uscan --force-action gear-uupdate

2) добавить в watch файл магию <user action>.

В формате watch файла (см. rpm-uscan(1)) предусмотрена дополнительная колонка для <user action> -- вызова команды, указанной пользователем. В Debian, как правило, если эта колонка используется, то в ней написано uupdate.

uupdate(1) -- это магическая утилита из debian, которая обновляет debian репозиторий. У нас же gear репозиторий, поэтому ей на замену я написал gear-uupdate, которая обновляет gear репозиторий, так, чтобы она была полностью совместима с debian --- все, что написано о watch файлах и uupdate в uscan(1) (тж. rpm-uscan(1)) будет работать и у нас.

Как следствие, можно добавить еще одну колонку для <user action>, т.е. команды, указанной пользователем, в которой написать gear-uupdate (можно писать uupdate, rpm-uscan при этом все равно вызовет gear-uupdate) и после скачивания новой версии gear-uupdate будет вызван автоматически.

gear-cronbuild при наличии watch файла и отсутствии cronbuild скриптов просто молча запускает rpm-uscan с опцией --force-action gear-uupdate, что дает эффект принудительного вызова gear-uupdate при наличии обновления.