Grundlegende Anleitung zum Schreiben von Gentoo Ebuilds

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 45% complete.
Outdated translations are marked like this.

Dies ist eine Anleitung zum Einstieg in das Schreiben von Ebuilds, um die Leistungsfähigkeit von Portage zu nutzen, um noch mehr Software zu installieren und zu verwalten.

Write an ebuild to install a piece of software on Gentoo, when there are no suitable preexisting ebuilds. It's a relatively straight forward task, and is the only way to cleanly install most "third party" software system-wide. The ebuild will allow the package manager to track every file installed to the system, to allow clean updates and removal.

Tipp
From the ebuild article: An ebuild file is a text file, usually stored in a repository, which identifies a specific software package and tells the Gentoo package manager how to handle it. Ebuilds use a bash-like syntax style and are standardized through the Package Manager Specification, by adhering to a specific EAPI version.

Ebuilds contain metadata about each version of a piece of available software (name, version number, license, home page address...), dependency information (both build-time and run-time), and instructions on how to build and install the software (configure, compile, build, install, test...).

Once an ebuild is working, it can be shared by submitting it in a pull request or in a separate ebuild repository and making it accessible publicly. With a little effort, ebuilds can be proposed and maintained in the GURU repository.

Hinweis
See the dev manual on writing ebuilds for full reference documentation. See the quick start to writing ebuilds in the dev manual for further examples of how to write ebuilds. See the ebuild article for explanations about ebuilds themselves, the ebuild repository article about what an ebuild repository is, and the creating an ebuild repository article on how to create them.

In order for ebuilds to be available to Portage, they are placed in an ebuild repository that is configured for Portage through /etc/portage/repos.conf (see the section on repository management for general information about working with ebuild repositories).

Create an ebuild repository to experiment in, while following on with this guide. The rest of the article will consider a repository in /var/db/repos/example_repository.

eselect repository macht die Erstellung eines Repositoriums einfach:

root #eselect repository create example_repository
Hinweis
Ebuilds can be installed with the ebuild command, however this is not recommended - this command is for development purposes only. This article will use the ebuild command with the ebuild file for testing during development, but be sure to use the emerge command with an ebuild in a repository otherwise.

Wie erstellt man ein Ebuild

Ebuilds sind in ihrer einfachsten Form Textdateien. Alles, was man braucht um Ebuilds zu schreiben, ist ein Texteditor, um installierbare Softwarepakete für Gentoo bereitzustellen.

Hinweis
In this section, {CATEGORY}, {PN}, and {P} represent package category, package name, and package name and version, and are standard variables used in ebuilds. Together, these variables can represent a version specifier.

Some editors have optional ebuild functionality, in that case there skip to the appropriate section. Otherwise a skeleton ("template") may be used to get started quicker.

Start with the skeleton

If the editor does not have integrated ebuild functionality to help to start off, there is a skeleton ebuild file (skel.ebuild) located in the Gentoo ebuild repository. To start with that file as a base, simply copy it to an appropriate location (nano is used as the text editor in this example):

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

Es gibt ein Vim-Plugin, das beim Erstellen einer leeren Ebuild-Datei automatisch mit einem Skelett beginnt.

Benutzer von vim erhalten das Grundgerüst automatisch (bereitgestellt von app-vim/gentoo-syntax):

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

Emacs

A similar tool is available for users of Emacs, provided by app-emacs/ebuild-mode or app-xemacs/ebuild-mode, depending on Emacs distribution.

Language server

Demonstration am Beispiel

In diesem Beispiel wird ein Ebuild für scrub, Version 2.6.1, erstellt (falls noch nicht vorhanden), um zu zeigen, wie ein typischer Prozess ablaufen könnte.

Legen Sie ein Verzeichnis für das Ebuild an, und zwar in dem zuvor angelegten Ebuild-Repositorium:

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

Ändern Sie das Arbeitsverzeichnis der Shell in den neuen Pfad:

user $cd /var/db/repos/example_repository/app-misc/scrub
Tipp
Einige Shells, wie z.B. Bash, stellen den letzten Parameter des vorherigen Befehls in der Variablen "$_" zur Verfügung. Dies kann dazu verwendet werden, das neu erstellte Verzeichnis aufzurufen, ohne den Pfad auf der Kommandozeile anzugeben, sofern dies als direkt folgender Befehl verwendet wird.
user $ cd $_

This example will use Vim to create the ebuild file and provide a skeleton to serve as a basis to write the ebuild on, but use editor of choice (see previous section about using Emacs, or the skeleton file):

user $vim ./scrub-2.6.1.ebuild

Add important information about the new package by setting the ebuild-defined variables: DESCRIPTION, HOMEPAGE, SRC_URI, LICENSE. Licenses like BSD-clause-3 which are not found in the tree might be mapped in metadata :

DATEI scrub-2.6.1.ebuildBearbeiten einer neuen Datei aus einer Vorlage
# Copyright 1999-2024 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
 
EAPI=8
 
DESCRIPTION="Einige Worte hier"
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 its most basic form, it's that simple!

Hinweis
Using the ${PN} variable inside SRC_URI is allowed, though this is not necessarily best practice. While it may be shorter to type, there is some reasoning on why not to use it that may be worth consideration.

CODE avoid using PN as such
SRC_URI="https://github.com/gentoo/${PN}/releases/download/${PV}/${P}.tar.gz"
# Reads better as, e.g.
SRC_URI="https://github.com/gentoo/gentoo/releases/download/${PV}/${P}.tar.gz"

See this ebuild file format policy guide page for more recommendations.

Es ist möglich, das Holen und Entpacken der Upstream-Quellen durch das neue Ebuild zu testen, indem man den Befehl ebuild verwendet:

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

Dies sollte den Quell-Tarball ohne Fehler herunterladen und entpacken, wie in der Beispielausgabe zu sehen ist.

Für einige außergewöhnlich einfache Pakete wie dieses, die nicht gepatcht oder anderweitig weiter behandelt werden müssen, kann das Ebuild genau so funktionieren - ohne weitere Anpassungen.

Im Sinne einer optimalen Vorgehensweise kann die Testsuite bereits in dieser Phase durchgeführt werden - dies gilt insbesondere für die Anfangsphase:

root #ebuild scrub-2.6.1.ebuild clean test install

Um das neue Ebuild tatsächlich auf dem System zu installieren, führen Sie aus:

root #ebuild scrub-2.6.1.ebuild clean install merge

Patching von Upstream-Quellen in einem Ebuild

Der Patch wird dann in einem Array namens PATCHES aufgelistet, wie es im Devmanual erklärt wird.

CODE Patches werden während src_prepare angewandt
PATCHES=(
	"${FILESDIR}"/${P}-foo.patch
	"${FILESDIR}"/${P}-bar.patch
)
 
src_prepare() {
    default
    ...
}

QA-Tests

Verwenden Sie pkgcheck (dev-util/pkgcheck), um nach QA-Fehlern in einem Ebuild zu suchen:

user $pkgcheck scan

Siehe auch

Externe Ressourcen