Начальное руководство по написание ebuild-файлов в Gentoo
Это руководство о том, как начать писать 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
разрешено, это не всегда является оптимальным вариантом. Хоть оно и быстрее пишется, есть некоторые определённые причины не использовать её, которые надо иметь ввиду.
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, как показано в руководстве разработчика:
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
См. также
- GitHub Pull Requests — how to contribute to Gentoo by creating pull requests on GitHub.
- java-ebuilder — an experimental package being developed by Gentoo Java developers to generate initial ebuilds from Maven
pom.xml
files. - Notes on ebuilds with GUI
- Project:GURU — an official repository of new Gentoo packages that are maintained collaboratively by Gentoo users
- Project:Proxy_Maintainers/User_Guide/Style_Guide
- Project:Python — страницы проекта Python содержат информацию про создание ebuild-файлов для пакетов, написанных на Python
- Project:X11/Ebuild_maintenance
- Proxied Maintainer FAQ
- Test environment
- Writing go Ebuilds — a short reference, intended to be read alongside Basic guide to write Gentoo Ebuilds and the go-module.eclass documentation
Внешние ресурсы
- Gentoo Policy Guide
- Quickstart Ebuild Guide
- Gentoo Development guide
- Michał Górny: Category: Ebuild writing
- Michał Górny: The ultimate guide to EAPI 7
- Michał Górny: The ultimate guide to EAPI 8
- man 1 ebuild — The ebuild command's man page.
- man 5 ebuild — The ebuild file format man page.
- The skel.ebuild
- Adding new packages via proxy-maint project