Начальное руководство по написание 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 85% complete.

Это руководство о том, как начать писать 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 #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.

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

В этом примере взята программа 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:

ФАЙЛ scrub-2.6.1.ebuildРедактирование нового файла в vim с шаблона
# Copyright 1999-2023 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=""

This— with the omission of those lines with =""— is the minimum information necessary to get something that will work. Ebuilds inheriting certain eclasses might come with a different set of minimal information, e.g. ant-jsch-1.10.9.ebuild. Save the file - voila an ebuild, in it's most basic form,it's that simple!

Заметка
Использование переменной ${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-файлов, чтобы получить больше рекомендаций.

It is possible to test fetching and unpacking the upstream sources by the new ebuild, using the ebuild command:

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

This should download and unpack the source tarball, without error, as in the example output.

For some exceptionally simple packages like this one, that do not need patching or other more advanced treatment, the ebuild may work just so - with no further adjustments needed.

For best practice, the test suite may be run at this stage - this is particularly true when starting out:

root #ebuild scrub-2.6.1.ebuild clean test install

To actually install the new ebuild on the system, run:

root #ebuild scrub-2.6.1.ebuild clean install merge

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

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

Добавьте патчи в правильный каталог:

user $cd /var/tmp/portage/app-misc/scrub-2.6.1/work/scrub-2.6.1/

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

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

QA testing

Use pkgcheck (dev-util/pkgcheck) to check for QA errors in an ebuild:

user $pkgcheck scan

См. также

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