Начальное руководство по написание ebuild-файлов в Gentoo

From Gentoo Wiki
Jump to:navigation Jump to:search
This page is a translated version of the page Basic guide to write Gentoo Ebuilds and the translation is 98% complete.
Outdated translations are marked like this.
Other languages:

Это руководство о том, как начать писать ebuild-файлы, чтобы использовать возможности Portage для установки и управления ещё большим количеством программного обеспечения.

Вы можете написать ebuild-файл для установки какого-либо программного обеспечения в Gentoo, если нет подходящих существующих ebuild-файлов. Это относительно простая задача, и это единственный способ чисто и аккуратно установить большинство "сторонних" программ в системе. ebuild-файл позволяет менеджеру пакетов отслеживать каждый файл, установленный в систему, чтобы обеспечить корректное обновление и удаление.

Совет
Из статьи ebuild: ebuild-файл — это текстовый файл, обычно хранящийся в репозитории, который определяет конкретный программный пакет и указывает менеджеру пакетов Gentoo, как с ним работать. Ebuild-файлы используют bash-подобный стиль синтаксиса и стандартизированы путём Package Manager Specification, придерживаясь определённой версии EAPI.

Ebuild-файлы содержат информацию о каждой версии доступного программного обеспечения (название, версию, лицензию, домашнюю страницу...), информацию о зависимостях (как во время сборки, так и во время выполнения), а также инструкции по сборке и установке программного обеспечения (конфигурирование, компиляция, сборка, установка, тестирование...).

После того, как ebuild-файл заработал, им можно поделиться, отправив его в запросе на слияние, или в отдельный репозиторий ebuild-файлов и сделав его общедоступным. С небольшими усилиями можно добавлять и сопровождать ebuild-файлы в GURU репозитории.

Заметка
Полную справочную документацию смотрите в Руководстве разработчика по написанию ebuild-файлов. Более подробные примеры написания ebuild-файлов смотрите в Кратком руководстве по написанию ebuild-файлов. См. статью ebuild для объяснения самих ebuild-файлов, статью Репозиторий ebuild-файлов о том, что такое репозиторий ebuild-файлов, и статью Создание репозитория ebuild-файлов о том, как его создать.

Репозитории ebuild-файлов

Чтобы ebuild-файлы были видны Portage, они помещаются в репозиторий ebuild-файлов, который настроен для Portage через /etc/portage/repos.conf (общую информацию о работе с репозиториями ebuild-файлов см. в разделе Управление репозиторием).

Создайте репозиторий ebuild-файлов для экспериментов, следуя этому руководству. В данной статье будет использоваться пример репозитория в /var/db/repos/example_repository.

eselect repository упрощает создание репозитория:

root #emerge -a app-eselect/eselect-repository
root #eselect repository create example_repository
Заметка
Ebuild-файлы можно установить с помощью команды ebuild, однако это не рекомендуется — эта команда предназначена только для целей разработки. В этой статье будет использоваться команда ebuild с ebuild-файлом для тестирования во время разработки, но в других случаях обязательно используйте команду emerge с ebuild-файлом в репозитории.

Как создать ebuild-файл

Если кратко, ebuild-файлы — это просто текстовые файлы. Всё, что нужно, чтобы начать писать ebuild-файлы — это текстовый редактор, чтобы предоставить возможность устанавливать пакеты программ для Gentoo.

Заметка
В этом разделе {CATEGORY}, {PN} и {P} означают категория пакета, имя пакета и имя пакета с версией соответственно, и являются стандартными переменными, используемыми в ebuild-файлах. Эти переменные вместе составляют спецификатор версии.

Некоторые редакторы имеют опциональную функцию создания ebuild-файлов, в этом случае переходите к соответствующему разделу. В противном случае для более быстрого начала работы можно использовать каркас ("шаблон").

Начните с каркаса

Если в редакторе нет встроенного функционала для начала работы с ebuild-файлами, то существует каркас ebuild-файла (skel.ebuild), расположенный в Gentoo репозитории ebuild-файлов. Чтобы начать работу с этим файлом, просто скопируйте его в соответствующее место (в качестве текстового редактора в данном примере используется nano):

user $mkdir --parents /var/db/repos/example_repository/{CATEGORY}/{PN}
user $cp /var/db/repos/gentoo/skel.ebuild /var/db/repos/example_repository/{CATEGORY}/{PN}
user $cd /var/db/repos/example_repository/{CATEGORY}/{PN}
user $nano {P}.ebuild

Vim

Для vim существует плагин, который автоматически добавит каркас при создании пустого ebuild-файла.

После установки app-vim/gentoo-syntax, создайте подходящий каталог для ebuild-файла, а затем запустите vim с файлом "{P}.ebuild", чтобы он добавил каркас, который можно изменить и сохранить:

user $mkdir --parents /var/db/repos/example_repository/{CATEGORY}/{PN}
user $cd /var/db/repos/example_repository/{CATEGORY}/{PN}
user $vim {P}.ebuild

Emacs

Для пользователей Emacs существует похожий инструмент, предоставляемый пакетом app-emacs/ebuild-mode или app-xemacs/ebuild-mode, в зависимости от дистрибутива Emacs.

Поддержка LSP

LSP-сервер для Gentoo ebuild-файлов можно найти в этом репозитории.

Демонстрация на примере

В этом примере взята программа scrub, версии 2.6.1, чтобы показать типичный процесс написания ebuild-файла (если он ещё не существует).

Создайте каталог, который будет содержать ebuild-файл, в репозитории ebuild-файлов, созданном ранее:

user $mkdir -p /var/db/repos/example_repository/app-misc/scrub

Измените текущий рабочий каталог оболочки (shell working directory) на новый путь:

user $cd /var/db/repos/example_repository/app-misc/scrub
Совет
Некоторые оболочки, такие как Bash, сохраняют последний параметр предыдущей команды в переменную "$_". Это можно использовать, чтобы получить вновь созданный каталог, не указывая путь в командной строке, в последующей команде.
user $cd $_

В этом примере для создания ebuild-файла и добавления каркаса используется Vim, но можно использовать любой редактор (см. предыдущий раздел про Emacs, или шаблонный файл):

user $vim ./scrub-2.6.1.ebuild

Добавьте важную информацию о новом пакете путём выставления переменных ebuild-файлов: DESCRIPTION, HOMEPAGE, SRC_URI, LICENSE. Лицензии наподобии BSD-clause-3 (BSD с 3-мя пунктами), которых нет в репозитории, могут находиться в файле с метаданными:

ФАЙЛ scrub-2.6.1.ebuildРедактирование нового файла в vim с шаблона
# Copyright 1999-2024 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
 
EAPI=8
 
DESCRIPTION="Some words here"
HOMEPAGE="https://github.com/chaos/scrub"
SRC_URI="https://github.com/chaos/scrub/releases/download/2.6.1/scrub-2.6.1.tar.gz"
 
LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~amd64 ~x86"
IUSE=""
 
DEPEND=""
RDEPEND="${DEPEND}"
BDEPEND=""

Этой информации (строки с ="" можно пропустить) достаточно для начала работы. Ebuild-файлам, наследующим от определённых eclass-ов может понадобиться другой минимум информации, напр. ant-jsch-1.10.9.ebuild. Сохраните файл и вуаля — получился базовый ebuild-файл, всё просто!

Заметка
Использование переменной ${PN} внутри SRC_URI разрешено, это не всегда является оптимальным вариантом. Хоть оно и быстрее пишется, есть некоторые определённые причины не использовать её, которые надо иметь ввиду.

КОД Избегайте такого использования PN
SRC_URI="https://github.com/gentoo/${PN}/releases/download/${PV}/${P}.tar.gz"
# Читается хуже, чем, к примеру, этот вариант
SRC_URI="https://github.com/gentoo/gentoo/releases/download/${PV}/${P}.tar.gz"

См. страницу правил форматирования ebuild-файлов, чтобы получить больше рекомендаций.

Для тестирования загрузки и распаковки кода от upstream (авторов проекта) в новом ebuild-файле можно воспользоваться командой ebuild:

user $GENTOO_MIRRORS="" ebuild ./scrub-2.6.1.ebuild manifest clean unpack
Appending /var/db/repos/customrepo to PORTDIR_OVERLAY...
>>> Downloading 'https://github.com/chaos/scrub/releases/download/2.6.1/scrub-2.6.1.tar.gz'
--2023-03-03 23:35:13--  https://github.com/chaos/scrub/releases/download/2.6.1/scrub-2.6.1.tar.gz
Resolving github.com... 140.82.121.4
Connecting to github.com|140.82.121.4|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://objects.githubusercontent.com/github-production-release-asset-2e65be/23157201/405a65b8-2d4d-11e4-8f82-3e3a9951b650?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20230303%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230303T223513Z&X-Amz-Expires=300&X-Amz-Signature=7d7d925ff8392ee2ba12028c73c8d8c3b3a7086b5aec11bbfae335222a4f2eb0&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=23157201&response-content-disposition=attachment%3B%20filename%3Dscrub-2.6.1.tar.gz&response-content-type=application%2Foctet-stream [following]
--2023-03-03 23:35:13--  https://objects.githubusercontent.com/github-production-release-asset-2e65be/23157201/405a65b8-2d4d-11e4-8f82-3e3a9951b650?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20230303%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230303T223513Z&X-Amz-Expires=300&X-Amz-Signature=7d7d925ff8392ee2ba12028c73c8d8c3b3a7086b5aec11bbfae335222a4f2eb0&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=23157201&response-content-disposition=attachment%3B%20filename%3Dscrub-2.6.1.tar.gz&response-content-type=application%2Foctet-stream
Resolving objects.githubusercontent.com... 185.199.108.133, 185.199.109.133, 185.199.110.133, ...
Connecting to objects.githubusercontent.com|185.199.108.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 362536 (354K) [application/octet-stream]
Saving to: '/var/cache/distfiles/scrub-2.6.1.tar.gz.__download__'
 
/var/cache/distfiles/scrub-2.6.1. 100%[============================================================>] 354.04K  --.-KB/s    in 0.08s   
 
2023-03-03 23:35:13 (4.31 MB/s) - '/var/cache/distfiles/scrub-2.6.1.tar.gz.__download__' saved [362536/362536]
 
 * scrub-2.6.1.tar.gz BLAKE2B SHA512 size ;-) ...                                                                               [ ok ]
>>> Unpacking source...
>>> Unpacking scrub-2.6.1.tar.gz to /var/tmp/portage/app-misc/scrub-2.6.1/work
>>> Source unpacked in /var/tmp/portage/app-misc/scrub-2.6.1/work

Команда должна загрузить и распаковывать архив с исходным кодом без ошибок, а вывод должен совпадать с примером.

Для таких простых пакетов, как этот, можно не дополнять ebuild-файл патчами или другими продвинутыми вещами — он и так будет работать.

На этом этапе рекомендуется запустить наборы тестов, особенно в начале работы:

root #ebuild scrub-2.6.1.ebuild clean test install

Чтобы установить новый ebuild-файл в систему, запустите:

root #ebuild scrub-2.6.1.ebuild clean install merge

Добавления патча для исходного кода в ebuild-файл

Патч может быть создан из распакованного исходного кода, как показано в статье Создание патча. Патчи должны быть размещены в каталоге files и перечислены в массиве PATCHES, как показано в руководстве разработчика:

КОД Патчи применяются во время фазы src_prepare
PATCHES=(
	"${FILESDIR}"/${P}-foo.patch
	"${FILESDIR}"/${P}-bar.patch
)
 
src_prepare() {
    default
    ...
}

Тестирование контроля качества (QA testing)

Для проверки на ошибки контроля качества (QA errors) в ebuild-файле можно использовать pkgcheck (dev-util/pkgcheck):

user $pkgcheck scan

Смотрите также

Внешние ресурсы

Retrieved from "https://wiki.gentoo.org/index.php?title=Basic_guide_to_write_Gentoo_Ebuilds/ru&oldid=1302356"