1.  Bienvenue dans le monde de Portage

Portage est probablement l'innovation de Gentoo la plus remarquable en ce qui concerne la gestion des logiciels. Sa grande flexibilité et ses nombreuses fonctionnalités font parfois dire de Portage qu'il est le meilleur outil de gestion des logiciels pour Linux.

Portage a été écrit en langage Python et en langage Bash qui sont tous les deux des langagages scriptés, c'est-à-dire que 100 % du code source est installé et consultable sur tous les systèmes Gentoo.

La plupart des utilisateurs interagiront avec Portage via la commande emerge. Ce chapitre n'a pas pour vocation de dupliquer toute l'information disponible dans la page manuel de emerge. Pour consulter la page man, faites :

$ man emerge

1.  L'arbre Portage

Les ebuilds

Quand nous parlons de paquets, nous faisons souvent allusion aux logiciels qui sont disponibles dans Gentoo grâce à l'arbre de Portage. Celui-ci est un ensemble d'ebuilds qui sont en fait des fichiers qui donnent toutes les informations nécessaires à Portage pour maintenir les logiciels (les installer, les rechercher, etc.). Par défaut, ces ebuilds se trouvent dans le dossier /usr/portage.

Dès que vous employez Portage pour une action relative aux paquets, il utilisera les ebuilds de votre système. Il est donc important de maintenir les ebuilds de votre système à jour pour que Portage soit informé de l'apparition de nouvelles versions des logiciels que vous utilisez ou de correctifs de failles de sécurité.

Mise à jour de l'arbre Portage

L'arbre Portage est généralement mis à jour avec rsync qui est un outil de transfert de fichiers incrémental et rapide. La mise à jour se fait simplement avec la commande emerge. L'utilisation de rsync est tout à fait transparente :

# emerge --sync

Si vous ne pouvez pas utiliser rsync à cause, par exemple, d'un pare-feu, vous pouvez quand même mettre votre arbre Portage à jour avec la commande emerge-webrsync. Celle-ci télécharge le dernier instantané de l'arbre Portage et l'installe sur votre système. Un instantané est généré automatiquement chaque jour sur les miroirs de Gentoo.

# emerge-webrsync

Un avantage supplémentaire qu'apporte emerge-webrsync réside dans le fait que ceci permet à l'administrateur de n'installer que des instantanés de l'arbre Portage authentifiés par la clé GPG de la « Gentoo release engineering team ». Des informations complémentaires sons disponibles dans la section (Recherche d'instatanés validés de l'arbre Portage) de la page (Portage et ses fonctionnalités).

1.  Maintenir vos logiciels

Rechercher un paquet

Pour rechercher un logiciel dans l'arbre Portage, vous pouvez utiliser emerge. En effet, la commande emerge --search affiche la liste des paquets dont le titre correspond plus ou moins au terme recherché.

Par exemple, pour trouver tous les paquets dont le nom contient « pdf », utilisez :

$ emerge --search pdf

Si vous voulez aussi chercher dans les descriptions, utilisez l'option --searchdesc (ou -S) :

$ emerge --searchdesc pdf

La liste des paquets affichés contient quelques informations utiles pour chaque paquet. Les libellés sont explicites et se passent de commentaires supplémentaires.

*  net-print/cups-pdf
      Latest version available: 1.5.2
      Latest version installed: [ Not Installed ]
      Size of downloaded files: 15 kB
      Homepage:    http://cip.physik.uni-wuerzburg.de/~vrbehr/cups-pdf/
      Description: Provides a virtual printer for CUPS to produce PDF files.
      License:     GPL-2

Installer des logiciels

Une fois que vous avez identifié un paquet que vous voulez installer, il vous suffit d'utiliser la commande emerge suivie du nom du paquet pour l'installer. Par exemple, pour installer gnumeric :

# emerge gnumeric

Comme de nombreuses applications dépendent les unes des autres, il se peut que, lorsque vous essayez d'en installer une, d'autres applications dont cette application dépend (dépendances) soient installées en même temps. Ne vous inquiétez pas, Portage gère très bien les dépendances. Si vous voulez connaitre la liste des paquets que Portage installerait si vous installiez un paquet donné, vous pouvez utiliser l'option --pretend. Voici un exemple :

# emerge --pretend gnumeric

Quand vous installez un paquet avec Portage, il télécharge les sources nécessaires et les sauvegarde dans le répertoire /usr/portage/distfiles. Ensuite, Portage décompresse l'archive, compile son contenu et installe le logiciel. Si vous voulez télécharger les sources sans installer le paquet, utilisez l'option --fetchonly. Par exemple, pour télécharger les sources de gnumeric :

# emerge --fetchonly gnumeric

Trouver la documentation d'un paquet installé

De nombreux paquets sont fournis avec leur propre documentation. Parfois l'option USE doc indique si la documentation d'un paquet doit être installée ou non. Vous pouvez vérifier l'existence de l'option USE doc avec la commande emerge -vp <nom du paquet>.

(L'utilisation d'alsa-lib n'est qu'un exemple bien sûr.)
# emerge -vp alsa-lib
[ebuild  N    ] media-libs/alsa-lib-1.0.14_rc1  -debug +doc 698 kB

La meilleure façon d'activer l'option USE doc est de le faire paquet par paquet via /etc/portage/package.use, afin de n'avoir la documentation que pour les paquets qui vous intéressent. L'activation de manière globale de cette option est connue pour causer des problèmes de dépendances circulaires. Pour plus d'informations, veuillez lire le chapitre (La variable USE).

Une fois le paquet installé, la documentation se trouve généralement dans un sous-répertoire au nom du paquet dans le répertoire /usr/share/doc. Vous pouvez également lister tous les fichiers installés avec l'outil equery qui fait partie du paquet app-portage/gentoolkit .

# ls -l /usr/share/doc/alsa-lib-1.0.14_rc1
total 28
-rw-r--r--  1 root root  669 May 17 21:54 ChangeLog.gz
-rw-r--r--  1 root root 9373 May 17 21:54 COPYING.gz
drwxr-xr-x  2 root root 8560 May 17 21:54 html
-rw-r--r--  1 root root  196 May 17 21:54 TODO.gz

(Autre méthode, avec equery :)
# equery files alsa-lib | less
media-libs/alsa-lib-1.0.14_rc1
* Contents of media-libs/alsa-lib-1.0.14_rc1:
/usr
/usr/bin
/usr/bin/alsalisp
(etc.)

Supprimer un paquet

Pour désinstaller un paquet de votre système, utilisez emerge --unmerge. Cette commande supprime les fichiers qui avaient été installés par Portage, mais ne supprime pas les fichiers de configuration si vous les avez modifiés après l'installation. Cela vous permet de réutiliser vos fichiers de configuration si vous réinstallez le paquet plus tard.

Cependant, un avertissement est de mise :Portage ne vérifie pas que le paquet que vous supprimez est nécessaire au bon fonctionnement d'un autre paquet. Toutefois, un message s'affichera si vous essayez de supprimer un paquet important dont la disparition causerait de graves problèmes.

# emerge --unmerge gnumeric

Quand vous supprimez un paquet, les paquets dont il dépend qui avaient été installés initialement ne seront pas désinstallés automatiquement. Pour que Portage recherche les dépendances qui peuvent être supprimées, utilisez l'option depclean. Nous en reparlerons plus loin.

Mettre votre système à jour

Pour maintenir votre système en bon état et disposer des correctifs de failles de sécurité, vous devriez le mettre à jour régulièrement. Puisque Portage ne se base que sur les ebuilds de votre machine, vous devez vous assurez que votre arbre Portage est à jour. Une fois votre arbre Portage à jour, vous pouvez mettre votre système à jour avec la commande emerge --update world. Dans l'exemple ci-dessous, on utilise aussi l'option --ask pour que Portage affiche la liste des paquets qu'il va mettre à jour et pour qu'il demande une confirmation.

# emerge --update --ask world

Portage recherche alors des versions plus récentes des logiciels que vous avez installés explicitement et uniquement ceux-là (ceux qui sont listés dans /var/lib/portage/world). Il ne prendra pas en compte de manière exhaustive leurs dépendances. Si vous voulez que ces dépendances soient aussi mises à jour, utilisez aussi l'option --deep :

# emerge --update --deep world

Mais cela ne veut pas dire pour autant tous les paquets; certains paquets de votre sysème ne sont nécessaires que durant la phase de compilation des paquets, mais une fois ces paquets installés, ces dépendances ne sont plus nécessaires. Portage les reconnait comme dépendances de compilation. Pour les prendre en compte dans le cycle de mise à j*our, ajoutez   --with-bdeps=y

# emerge --update --deep --with-bdeps=y world

Étant donné que des mises à jour qui corrigent des failles de sécurité sont apportées à des paquets que vous n'avez pas explicitement installés, mais qui ont été installés parce que d'autres paquets en dépendent, il est recommandé d'exécuter la commande ci-dessus de temps en temps.

Si vous avez modifié les (options de la variable USE), vous devriez également ajouter l'option --newuse pour que Portage vérifie si certains paquets ne doivent pas être recompilés. Par exemple :

# emerge --update --deep --with-bdeps=y --newuse world

Les méta-paquets

Certains paquets ne contiennent aucun logiciel, mais servent à installer un ensemble de paquets. Par exemple, le paquet kde-meta sert à installer un environnement KDE complet et provoque l'installation d'un grand nombre de paquets relatifs à KDE.

Supprimer un tel paquet avec la commande emerge --unmerge n'aurait aucune influence sur votre système puisque tous les paquets dépendants resteraient installés.

Portage permet de supprimer les dépendances orphelines, mais, pour cela, vous devez d'abord mettre votre système complètement à jour en tenant compte d'éventuelles modifications apportées à votre variable USE. Vous pouvez ensuite utiliser emerge --depclean pour supprimer les dépendances orphelines. Par la suite, vous devriez recompiler les applications qui étaient liées dynamiquement avec les paquets que vous venez de supprimer. Les paquets désinstallés ne sont plus nécessaires à la bonne marche de ces applications.

Tout cela peut être résumé en trois commandes :

# emerge --update --deep --newuse world
# emerge --depclean
# revdep-rebuild

La commande revdep-rebuild fait partie du paquet gentoolkit ; n'oubliez pas de l'installer :

# emerge gentoolkit

1.  Licences

Depuis la version 2.1.7 de Portage, vous pouvez accepter ou refuser l'installation de paquets en fonction de leur licence. Tous les paquets de l'arbre de Portage ont une entrée LICENCE dans leur ebuild. La commande emerge --search nomdupaquet vous permet de voir cette licence.

Par défaut, Portage autorise toutes les licencees, sauf les Contrats de Licence Utilisateur Final (CLUF) ou End User Licence Agreement (EULA) en anglais, qui réclament une lecture et la signature d'un accord.

La variable qui définit les licences acceptées est ACCEPT_LICENSE, dont on peut fixer la valeur dans /etc/portage/make.conf:

ACCEPT_LICENSE="* -@EULA"

Avec cette configuration, les paquets qui requièrent une interaction pendant l'installation pour que leur CLUF soit approuvé ne seront pas installés. Les paquets sans CLUF seront installés.

Vous pouvez définir ACCEPT_LICENSE globalllement dans /etc/portage/make.conf, ou vous pouvez la définir paquet par paquet dans le fichier /etc/portage/package.license.

Par exemple, si vous voulez autoriser la licence truecrypt-2.7 pour app-crypt/truecrypt, ajoutez ce qui suit à /etc/portage/package.license:

app-crypt/truecrypt truecrypt-2.7

Ceci autorise l'installation de versions de truecrypt qui relèvent de la licence truecrypt-2.7 , mais pas de versions qui relèvent de la licence truecrypt-2.8.

Les groupes de licences définis dans ACCEPT_LICENSE sont préfixés par un signe @. Voici un exemple de système qui autorise globalement les licences compatibles GPL ainsi que d'autres groupes et licences individuelles.

ACCEPT_LICENSE="@GPL-COMPATIBLE @OSI-APPROVED @EULA atheros-hal BitstreamVera"

Si vous ne voulez autoriser que des logiciels et des documentations libres dans votre système, utilisez la variable suivante :

ACCEPT_LICENSE="-* @FREE"

Dans cet exemple, le mot "free" fait référence à la définition donnée par la FSF et par l'OSI. Tout paquet dont la licence ne respecte pas les exigences qui y sont mentionnées ne sera pas installé.

1.  Quand Portage se plaint...

À propos des « SLOTs », paquets virtuels, branches, architectures et profils

Comme nous l'avons déjà dit, Portage est très puissant et offre de nombreuses fonctionnalités que d'autres gestionnaires de logiciels n'ont pas. Survolons les différents aspects de Portage.

Portage permet à plusieurs versions d'un même paquet de cohabiter sur le même système. D'autres distributions ont tendance à renommer les paquets en fonction de la version (par exemple freetype et freetype2) alors que Portage utilise des « SLOTs ». Un ebuild peut placer chaque version du logiciel dans un slot et des versions qui sont dans des slots différents peuvent être installées en même temps. Par exemple, le paquet freetype a des versions avec SLOT="1" et SLOT="2".

Dans certains cas, différents paquets installent la même fonctionnalité. Par exemple, metalogd, sysklogd et syslog-ng gèrent tous le jounal du système, mais un logiciel qui dépendrait du journal système ne peut pas dépendre directement de metalogd ou d'un autre. Le système doit aussi fonctionner si l'utilisateur a choisi un autre gestionnaire de journal. Portage permet de définir des paquets virtuels. Les trois paquets cités ci-dessus fournissent la fonctionnalité virtual/syslog et les paquets qui ont besoin d'un journal système dépendent de celle-ci.

Portage classe les paquets dans plusieurs branches. Par défaut, votre système n'accepte que les paquets que Gentoo considère stables. Bien souvent, quand une nouvelle version d'un logiciel sort, elle est d'abord ajoutée à la branche dite « instable », ce qui signifie que plus de tests sont nécessaires avant de considérer le logiciel comme stable. Vous verrez les paquets dits instables dans votre arbre, mais Portage ne les installera pas automatiquement avant qu'ils ne soient stabilisés.

Certains logiciels ne sont disponibles que pour certaines architectures ou ne fonctionnent pas du tout sur d'autres. Parfois, un logiciel a besoin de plus de tests sur une architecture donnée ou les développeurs responsables d'un paquet n'ont pas la possibilité de le valider pour d'autres processeurs.

Chaque installation de Gentoo se conforme à un profil qui contient la liste des paquets qui forment un système cohérent et fonctionnel.

Paquets bloqués

[blocks B     ] mail-mta/ssmtp (is blocking mail-mta/postfix-2.2.2-r1)

!!! Error: the mail-mta/postfix package conflicts with another package.
!!!        both can't be installed on the same system together.
!!!        Please use 'emerge --pretend' to determine blockers.

Les ebuilds contiennent des informations relatives aux dépendances des logiciels entre eux. Il y a deux sortes de dépendances : les dépendances à l'installation définies par DEPEND et les dépendances à l'utilisation définies dans RDEPEND. Un blocage peut se produire quand un paquet est considéré incompatible avec une dépendance.

Bien que les versions récentes de Portage viennent à bout d'incompatibilités mineures sans intervention de l'utilisateur, il arrive que vous deviez régler le problème vous-même comme nous l'expliquons tout de suite.

Pour résoudre un tel blocage, vous pouvez soit ne pas installer le logiciel dont l'installation était envisagée, soit désinstaller le paquet qui bloque. Dans l'exemple ci-dessus, vous auriez le choix entre ne pas installer postfix ou d'abord désinstaller ssmtp.

Un blocage peut être provoqué par une version spécifique d'un logiciel, par exemple : <media-video/mplayer-bin-1.0_rc1-r2. Dans ce cas, il suffit de mettre à jour le logiciel en question vers une version plus récente pour supprimer le blocage.

Il se peut que deux paquets qui ne sont pas encore installés se bloquent entre eux. Dans ce rare cas, vous devez trouver pourquoi les deux paquets veulent s'installer car normalement un seul suffit. Si le problème persiste, veuillez remplir un rapport de bogue sur notre système de gestion de bogues.

Les paquets masqués

!!! all ebuilds that could satisfy "bootsplash" have been masked.

!!! possible candidates are:

- gnome-base/gnome-2.8.0_pre1 (masked by: ~x86 keyword)
- lm-sensors/lm-sensors-2.8.7 (masked by: -sparc keyword)
- sys-libs/glibc-2.3.4.20040808 (masked by: -* keyword)
- dev-util/cvsd-1.0.2 (masked by: missing keyword)
- games-fps/unreal-tournament-451 (masked by: package.mask)
- sys-libs/glibc-2.3.2-r11 (masked by: profile)
- net-im/skype-2.1.0.81 (masked by: skype-eula license(s))

Quand vous essayez d'installer un paquet qui n'est pas disponible pour votre système, vous recevez ce type d'erreur. Vous devriez essayer d'installer une autre application qui est disponible pour votre environnement ou attendre que le paquet devienne disponible. Un paquet est toujours masqué pour une bonne raison :

• ~arch keyword indique que le paquet n'a pas été suffisamment testé et n'est pas encore dans la branche stable. Vous devriez essayer à nouveau quelques jours ou quelques semaines plus tard.
• -arch keyword ou -* keyword indique que l'application ne fonctionne pas sur votre architecture. Si vous pensez le contraire, veuillez le signaler via bugzilla.
• missing keyword indique que l'application n'a pas été testée sur votre architecture. Vous pouvez demander à l'équipe en charge de celle-ci de tester l'application qui vous intéresse ou la tester vous-même et soumettre vos résultats sur bugzilla.
• package.mask indique que le paquet est cassé, instable, voire pire et qu'il a été masqué pour que vous ne l'utilisiez pas.
• profile indique que le paquet n'est pas compatible avec votre profil. L'application pourrait abimer votre système.
• license signifie que la licence du paquet n'est pas autorisée par la variable ACCEPT_LICENSE. Vous devez l'autoriser explicitement (individuellement ou dans un groupe) dans /etc/portage/make.conf ou dans /etc/portage/package.license. Reportez-vous à Licences pour obtenir l'information nécessaire.

Changements demandés de la variable USE

The following USE changes are necessary to proceed:
#required by app-text/happypackage-2.0, required by happypackage (argument)
>=app-text/feelings-1.0.0 test

Ce message d'erreur peut aussi apparaître comme ce qui suit si la variable --autounmask n'est pas définie :

emerge: there are no ebuilds built with USE flags to satisfy "app-text/feelings[test]".
!!! One of the following packages is required to complete your request:
- app-text/feelings-1.0.0 (Change USE: +test)
(dependency required by "app-text/happypackage-2.0" [ebuild])
(dependency required by "happypackage" [argument])

Un tel avertissement ou erreur apparaît lorsque vous voulez installer un paquet qui, non seulement dépend d'un autre paquet, mais nécessite aussi que ce paquet soit compilé avec une option (ou un jeu d'options) bien particulière dans la variable USE. Dans l'exemple cité, le paquet app-text/feelings requiert d'être compilé avec USE="test", mais cette option n'est pas déclarée dans USE.

Pour résoudre ce problème, vous pouvez, ajouter l'option requise à la variable USE, soit globalement dans /etc/portage/make.conf, soit spécifiquement pour le paquet dans /etc/portage/package.use.

Dépendances manquantes

emerge: there are no ebuilds to satisfy ">=sys-devel/gcc-3.4.2-r4".

!!! Problem with ebuild sys-devel/gcc-3.4.2-r2
!!! Possibly a DEPEND/*DEPEND problem.

L'application que vous essayez d'installer dépend d'autres paquets qui ne sont pas disponibles pour votre système. Veuillez vérifier sur bugzilla si le problème est déjà connu et veuillez le signaler dans le cas contraire. À moins que vous ne mélangiez les branches stables et instables, cela de doit pas arriver et peut être considéré comme un bogue.

Noms d'ebuilds ambigus

[ Results for search key : listen ]
[ Applications found : 2 ]

*  dev-tinyos/listen [ Masked ]
      Latest version available: 1.1.15
      Latest version installed: [ Not Installed ]
      Size of files: 10,032 kB
      Homepage:      http://www.tinyos.net/
      Description:   Raw listen for TinyOS
      License:       BSD

*  media-sound/listen [ Masked ]
      Latest version available: 0.6.3
      Latest version installed: [ Not Installed ]
      Size of files: 859 kB
      Homepage:      http://www.listen-project.org
      Description:   A Music player and management for GNOME
      License:       GPL-2

!!! The short ebuild name "listen" is ambiguous. Please specify
!!! one of the above fully-qualified ebuild names instead.

Le paquet que vous essayez d'installer a un nom qui désigne plusieurs paquets dans des catégories différentes. Vous devez mentionner la catégorie du paquet que vous voulez installer. Portage affiche les différentes possibilités.

Dépendances circulaires

!!! Error: circular dependencies:

ebuild / net-print/cups-1.1.15-r2 depends on ebuild / app-text/ghostscript-7.05.3-r1
ebuild / app-text/ghostscript-7.05.3-r1 depends on ebuild / net-print/cups-1.1.15-r2

Deux (ou plus) paquets dépendent l'un de l'autre et ne peuvent pas être installés. Il est très probable que cela soit un bogue. Veuillez synchroniser votre arbre Portage. Si le problème persiste, veuillez vérifier si le problème est connu dans bugzilla et le signaler dans le cas contraire.

Problèmes lors du téléchargement

!!! Fetch failed for sys-libs/ncurses-5.4-r5, continuing...
(...)
!!! Some fetch errors were encountered.  Please see above for details.

Portage n'a pas pu télécharger les sources de l'application et essaie éventuellement d'installer les autres paquets que vous auriez spécifiés avec la commande emerge. Ce problème peut être dû à un miroir qui n'est pas encore synchronisé ou à un ebuild qui référence un serveur de sources incorrect. Il se peut aussi que le serveur soit momentanément indisponible.

Veuillez réessayer après quelques heures.

Protection des paquets du profil système

!!! Trying to unmerge package(s) in system profile. 'sys-apps/portage'
!!! This could be damaging to your system.

Vous avez demandé à Portage de supprimer un paquet qui fait partie du profil système. Le supprimer pourrait rendre votre système inutilisable.

Échecs à la vérification des sommes de contrôle (Digest)

Parfois, quand vous essayez d'installer un paquet, cela échoue avec le message :

>>> checking ebuild checksums
!!! Digest verification failed:

Ceci est le signe d'une erreur dans l'arbre de Portage et souvent il se peut qu'un développeur ait fait une erreur lors de l'envoi d'une mise à jour d'un paquet dans l'arbre.

Quand la vérification de la somme de contrôle échoue, n'essayez pas de régénérer le fichier Digest vous-même. Exécuter ebuild toto manifest ne réglera pas le problème, au contraire !

Attendez plutôt une heure ou deux que l'arbre soit corrigé. Il est probable que l'erreur ait été déjà signalée, mais cela peut prendre un petit moment pour la correction et la propagation dans l'arbre de Portage. Vous pouvez, pendant ce temps, vérifier dans Bugzilla si quelqu'un a déjà signalé le problème. Si ça n'est pas le cas, envoyez un rapport de bogue pour un paquet cassé.

Dès que vous voyez que le bogue est corrigé, vous pouvez mettre à jour votre arbre de Portage pour récupérer le fichier Digest corrigé.