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 3% complete.
Outdated translations are marked like this.
Other languages:
Attention !
Mise en garde: la traduction de cet article est en cours, c'est brouillon et seul le début est commencé - passez votre chemin, pour l'instant. Voir page de discussion / see talk page.

Ce guide permet de débuter dans la création d' ebuild, pour utiliser la puissance de Portage, pour installer et gérer encore d'avantage de logiciels.

Écrivez un ebuild pour permettre d'installer un logiciel sur Gentoo, lorsqu'il n'y a pas d'ebuild préexistant. Il est relativement simple de créer un ebuild, et il s'agit du seul moyen d'installer la plupart des logiciels tiers pour qu'ils soient accessibles par tout le système. L'ebuild permet au gestionnaire de paquets de suivre chaque fichier installé sur le système, pour pouvoir faire les mises à jour et les désinstallations proprement.

Conseil
Selon l'article ebuild: Un fichier ebuild est un fichier texte, habituellement contenu dans un "repository"; qui identifie un paquet spécifique et indique au gestionnaire de paquets comment le prendre en charge. Les ebuilds utilisent un syntaxe proche du bash, et suivent un standard: le Package Manager Specification, en respectant un EAPI particulier.

Les ebuild contiennent des métadonnées concernant chaque version de chaque logiciel (nom, numéro de version, licence, site web...), les informations sur les dépendances (pour l’exécution et pour la construction), ainsi que les étapes à suivre pour construire et installer le logiciel (configuration, compilation, construction, installation, test...).

Une fois qu'un ebuild fonctionne, il peut être partagé soit en soumettant un pull request ou en le rendant publiquement accessible dans un ebuild repository.

Remarque
Voir le manuel du développeur sur l’écriture d'ebuild pour la documentation complète. Voir le guide de démarrage rapide du manuel du développeur pour plus d'exemples sur l'écriture d'ebuild. Voir l'article Ebuild pour des explications sur les ebuild eux-mêmes, l'article sur les répertoires ebuild concernant ceux-ci et l'article création de répertoire ebuild sur comment les créer.

Répertoires ebuild

Pour que les ebuild soient rendus disponibles à Portage, ils sont placés dans un ebuild repository qui est configuré avec Portage par le fichier /etc/portage/repos.conf (voir section sur gestion de repository pour plus d'informations sur ces répertoires).

Créez un répertoire pour les tests, pour pouvoir poursuivre ce guide. Le restant de cet article considère qu'il existe un répertoire dans /var/db/repos/example_repository.

La commande eselect repository rend simple la création de répertoire ebuild:

root #eselect repository create répertoire-exemple
Remarque
Les ebuild peuvent s'installer avec la commande ebuild, cependant ceci n'est pas recommandée - 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 répertoire à ebuild dans tous les autres cas.

Comment créer un ebuild

Les ebuild sont de simples fichiers texte, dans leur forme le plus basique. Tout ce qu'il faut pour commencer à écrire des ebuild, et à fournir à Gentoo de nouveaux paquets à installer, est un éditeur de texte.

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

Certains éditeurs ont des fonctionnalités d'édition d'ebuild spécifiques, dans ce cas référez-vous à la section appropriée. Autrement un "pochoir" peut être utilisé pour démarrer.

Démarrer avec un pochoir

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

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:

FILE scrub-2.6.1.ebuildvim editing a new file from template
# 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 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

The source can be patched at installation time, to adapt to Gentoo specificities for example, by setting up patches from an ebuild.

Put the patches in the right directory:

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

A patch can be created from the unpacked source code as explained in the Creating a patch article. Patches should then 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=1262305"