Guide de création d'Ebuild pour débuter

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 28% complete.
Outdated translations are marked like this.
Other languages:

Ceci est un guide pour commencer à écrire des ebuilds, afin d'exploiter la puissance de Portage, pour installer et gérer encore plus de logiciels.

Écrire un ebuild pour installer un logiciel sur Gentoo, lorsqu'il n'y a pas d'ebuilds appropriés pré-existants. C'est une tâche relativement simple et c'est le seul moyen pour installer proprement la plupart des logiciels-tiers à l'échelle du système. L'ebuild vas autoriser le gestionnaire de paquet à traquer tout les fichiers installés dans le système, pour autoriser leur mise à jours et leur suppression de manière propre.

Conseil
Selon l'article ebuild: Un ebuild est un fichier texte, généralement stocké dans un dépôt, qui identifie le paquet d'un logiciel spécifique et indique au gestionnaire de paquet de Gentoo comment s'en occuper. Les ebuilds utilisent une syntax proche de celle de bash et est standardisé à travers les Spécifications du gestionnaire de paquet, en adhérent à une version de l'EAPI spécifique.

Les ebuilds contiennent des metadata à propos de chaque version d'un logiciel disponible (nom, numéro de version, license, adresse de la page d'accueil (NdT: web)), les informations des dépendances (compilé durant la construction du paquet ou celles à l'exécution), ainsi que des instructions sur comment construire et installer un logiciel (configuration, compilation, construction, installation, test…).

Une fois qu'un ebuild est fonctionnel, il peut être partagé en le soumettant dans un pull request (NdT: ou vulgairement, une « demande de tirage ») ou dans un dépôt ebuild séparé et en le rendant publiquement accessible. Avec quelques efforts, les ebuilds peuvent être proposés et maintenus dans un dépôt GURU.

Remarque
Voir le manuel du développeur sur l’écriture d'ebuild pour une documentation de référence complète. Voir le guide de démarrage rapide du manuel du développeur pour plus d'exemples sur comment écrire des ebuilds. Voir l'article ebuild pour des explications sur les ebuilds eux-mêmes, l'article des dépôts des ebuilds pour un à-propos et ce qu'ils sont et l'article création d'un répertoire ebuild sur comment les créer.

Dépôts Ebuild

Afin que les ebuilds soient disponibles pour Portage, ils doivent être placés dans un dépôt ebuild qui est configuré pour Portage à travers /etc/portage/repos.conf (voir la section sur la gestion des dépôts pour des informations généralistes à propos du fonctionnement des dépôts ebuild).

Créer un dépôt ebuild pour expérimenter à l'intérieur, tout en suivant ce guide. Le reste de l'article vas considérer que le dépôt sera dans {Path|/var/db/repos/exemple_depot}}.

eselect repository permet de créer un dépôt simplement :

root #emerge -a app-eselect/eselect-repository
root #eselect repository create exemple_depot
Remarque
Les ebuild peuvent s'installer avec la commande ebuild, cependant ceci n'est pas recommandé - cette commande est réservé au processus de développement. Cette article utilisera la commande ebuild pour réaliser des tests au cours du processus de développement, mais soyez assuré d'utiliser la commande emerge avec un ebuild dans un dépôt ebuild dans tous les autres cas.

Comment créer un ebuild

Les ebuilds sont de simples fichiers texte, dans leur forme la plus basique. Tout ce qu'il faut pour commencer à écrire des ebuilds est un éditeur de texte, afin de procurer des paquets de logiciels installable pour Gentoo.

Remarque
Dans cette section, {CATEGORY}, {PN}, and {P} représentent catégorie du paquet, nom du paquet et nom du paquet et version, elles sont des standards de variables utilisés dans les ebuilds. Ensemble, ces variables peuvent représenter un {Link
.}}

Certains éditeurs ont des fonctionnalités optionnelles pour les ebuilds, dans ce cas-ci il peut être utile de se rendre à la section appropriée. Dans d'autres cas un squelette ("modèle") peut être utilisé pour démarrer plus rapidement.

Démarrer avec un squelette

Si l'éditeur n'a pas de fonctionnalités d'ebuilds intégrés pour assister au commencement, il y a un fichier squelette (skel.ebuild) localisé dans le dépôt ebuild de Gentoo. Pour commencer avec ce fichier comme base, copier simplement celui-ci dans l'emplacement approprié (nano est utilisé dans cet exemple en tant qu'éditeur):

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

There is a vim plugin to automatically start from a skeleton when creating an empty ebuild file.

After installing app-vim/gentoo-syntax, create the appropriate directory for the ebuild, then launch vim with a new "{P}.ebuild" filename provided on the command line, to be automatically met with a basic skeleton that can be modified and saved:

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

There is a language server for gentoo ebuild.

Demonstration by example

This example will create an ebuild for scrub, version 2.6.1 (if it didn't already exist), to show how a typical process might go.

Create a directory to house the ebuild, in the ebuild repository created earlier:

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

Change the shell working directory to the new path:

user $cd /var/db/repos/example_repository/app-misc/scrub
Conseil
Some shells, such as Bash, provide the last parameter of the previous command in the "$_" variable. This can be used to call the newly created directory without specifying the path on the command line, as long as this is used as the directly next command.
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 :

FILE scrub-2.6.1.ebuildvim editing a new file from template
# Copyright 1999-2025 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 its most basic form, it's that simple!

Remarque
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.

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

Patching upstream source in an ebuild

A patch can be created from the unpacked source code as explained in the Creating a patch article. Patches should then be put in the files directory and be listed in an array called PATCHES as explained in the devmanual:

CODE Patches will be applied during 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

See also

External resources

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