Introduction à Portage

Updated 7 Novembre 2026

Cette page s'applique à Portage 3.0.82 et Calculate Utilities 3.8.

Cette page ouvre la série Working with Portage : elle réunit les concepts de base - dépôts et ebuild, synchronisation de l'arborescence, recherche, installation et suppression de paquets, licences, et messages typiques de Portage.

Bienvenue à Portage

Portage est le système de gestion de logiciels que Calculate Linux a repris de Gentoo. Grâce à sa flexibilité et à son riche ensemble de fonctionnalités, il est souvent présenté comme l'un des meilleurs outils de gestion de paquets sous Linux. Portage est entièrement écrit en Python et en Bash - des langages de script - son fonctionnement est donc ouvert et compréhensible pour l'utilisateur.

La plupart des utilisateurs interagissent avec Portage par l'intermédiaire de la commande emerge. Cette page ne duplique pas sa référence : la liste complète des options est donnée par la page de manuel :

Le dépôt d'ebuild

Qu'est-ce qu'un ebuild

Quand la documentation parle de "paquets", elle désigne des programmes mis à la disposition de l'utilisateur par l'intermédiaire de dépôts - des collections de fichiers ebuild. Chaque fichier de ce type contient toutes les informations dont Portage se sert pour installer, rechercher et contrôler un programme : ses versions, ses dépendances, ses drapeaux de construction et ses adresses de code source. La principale collection de recettes est le dépôt gentoo situé dans /var/db/repos/gentoo; le dépôt calculate, avec les paquets, les eclasses et les modèles du projet Calculate, se trouve dans /var/db/repos/calculate.

Lorsque vous demandez à Portage d'agir sur un programme, il s'appuie sur les fichiers ebuild disponibles dans le système. C'est pourquoi l'arborescence doit être mise à jour régulièrement - sinon Portage ne sera pas au courant des nouveaux programmes et des mises à jour de sécurité.

Les cinq dépôts de Calculate

Contrairement à Gentoo 'pur', la distribution Calculate est configurée pour fonctionner avec cinq dépôts à la fois :

• gentoo - un miroir de l'arborescence de Gentoo ; il ne se synchronise pas directement avec les serveurs de Gentoo mais par l'intermédiaire des miroirs du projet Calculate (type de synchronisation calculate);
• calculate - les paquets, les eclasses et les modèles de Calculate elle-même;
• distros - les profils de la distribution (CLD, CLDX, CDS et d'autres);
• container - un dépôt pour la construction de conteneurs dans /var/calculate/repos/container;
• custom - un dépôt utilisateur dans /var/calculate/repos/custom avec les masters calculate et gentoo - une base prête à l'emploi pour vos propres paquets, sans gestionnaires d'overlays tiers.

Le dépôt gentoo est désigné comme le principal (main-repo). Voici comment Portage voit ce réglage - la section Repositories de la sortie de emerge --info :

Repositories:

custom
    location: /var/calculate/repos/custom
    masters: calculate gentoo
    volatile: True

calculate
    location: /var/db/repos/calculate
    sync-type: calculate
    sync-uri: https://github.com/calculatelinux/calculate
    masters: gentoo
    priority: 50
    volatile: False

container
    location: /var/calculate/repos/container
    sync-type: git
    sync-uri: https://github.com/calculatelinux/container
    masters: calculate gentoo
    priority: 50
    volatile: True

distros
    location: /var/db/repos/distros
    sync-type: calculate
    sync-uri: https://github.com/calculatelinux/distros
    masters: calculate gentoo
    priority: 50
    volatile: False

gentoo
    location: /var/db/repos/gentoo
    sync-type: calculate
    sync-uri: https://github.com/calculatelinux/gentoo
    priority: 50
    volatile: False

La configuration des dépôts se trouve dans les fichiers du répertoire /etc/portage/repos.conf/, créés par la distribution; ils ne devraient pas être modifiés à la main. Ajoutez votre propre dépôt avec un fichier NOUVEAU dans ce répertoire - détails sur la page Se tourner vers une source tierce. La carte complète des répertoires de travail de Portage se trouve dans la section Fichiers et répertoires.

Mise à jour de l'arborescence

La méthode standard pour mettre à jour les dépôts est la commande cl-update -s, qui n'effectue que la synchronisation :

La même synchronisation s'exécute automatiquement lors de chaque cl-update complet. Séparément, vous pouvez choisir les dépôts à synchroniser (l'option -r) et activer une mise à jour forcée de la base de recherche (--force-eix-update). La sortie d'aide affiche l'ensemble complet des options :

usage: cl-update [--stable [ON/OFF]] [--scan [ON/OFF]]
                 [--with-bdeps [ON/OFF/AUTO]] [-m MIRROR_URL]
                 [--repo-update REPOSITORY URL] [-o [ON/OFF/AUTO]]
                 [-s [ON/OFF]] [-p [ON/OFF]] [-r REPOSITORIES] [-e [ON/OFF]]
                 [-C [ON/OFF]] [--force-fix [ON/OFF]]
                 [--ignore-level [ON/OFF]] [--force-level LEVEL]
                 [--rebuild-world | --merge-world | --update-world]
                 [--force-check-sign | --skip-check-sign | --auto-check-sign]
                 [--force-egencache | --skip-egencache | --auto-egencache]
                 [--force-eix-update | --skip-eix-update | --auto-eix-update]
                 [-R [ON/OFF]] [--wait-another-update [ON/OFF]]
                 [--schedule [ON/OFF]] [-1 [ON/OFF/AUTO]]
                 [--clean-pkg [ON/OFF]] [--branch REFS] [-T TEMPLATES]
                 [-v [ON/OFF]] [--usenew-conf | --skip-conf | --dispatch-conf]
                 [--exclude exclude] [-f]

Installation et suppression de programmes

Recherche de programmes

Le plus simple est la recherche intégrée d'emerge : par défaut, --search trouve les paquets dont le nom correspond totalement ou partiellement à la requête. Par exemple, la recherche des paquets contenant le mot "nano" :

[ Results for search key : nano ]
Searching...

*  app-editors/nano
      Latest version available: 9.2
      Latest version installed: [ Not Installed ]

*  www-apps/nanoc-spec [ Masked ]
      Latest version available: 0.0.2-r1
      Latest version installed: [ Not Installed ]
      Size of files: 7 KiB
      Homepage:      https://nanoc.app/
      Description:   Provides Nanoc::Spec, containing functionality for writing tests for Nanoc
      License:       MIT

[ Applications found : 15 ]

Pour rechercher à la fois les noms et les descriptions, utilisez l'option --searchdesc (forme courte -S) :

La réponse pour chaque résultat énumère les versions disponibles et installées, la taille, la page d'accueil, la description et la licence - les champs sont libellés explicitement. Pour une recherche rapide dans l'arborescence, l'utilitaire eix est plus commode - il a sa propre page, Recherche rapide avec eix.

Installation

Une fois le programme dont vous avez besoin trouvé, l'installation n'est plus qu'à un pas. Comme beaucoup de programmes dépendent les uns des autres, l'installation d'un seul paquet peut entraîner des dizaines de dépendances. Ne vous inquiétez pas : Portage s'en charge lui-même. Il est d[HTML_REMOVED]abord utile de consulter le plan d[HTML_REMOVED]installation sans rien installer : l[HTML_REMOVED]option -p (--pretend) affiche les paquets qui seront installés, dans l[HTML_REMOVED]ordre de construction :

These are the packages that would be merged, in order:

Calculating dependencies ... done!
Dependency resolution took 2.39 s (backtrack: 0/20).

[binary  N g   ] app-editors/nano-9.2::gentoo  USE="ncurses nls (unicode) -debug -justify -magic -minimal -spell -verify-sig" 694 KiB

Total: 1 package (1 new, 1 binary), Size of downloads: 694 KiB

Lecture de la sortie : dans une ligne de paquet, les drapeaux USE suivent le nom - les activés sans préfixe, les désactivés avec un moins; la taille du téléchargement est indiquée en fin de ligne. La dernière ligne récapitule le nombre de paquets et le volume des téléchargements.

Pour installer le paquet, retirez -p et ajoutez -a (--ask) - Portage demandera une confirmation avant de commencer :

Pendant l'installation, Portage télécharge les sources depuis Internet quand il en a besoin et les conserve dans le répertoire /var/calculate/distfiles (la variable DISTDIR), puis extrait, compile et installe le paquet. Si vous avez seulement besoin de télécharger les sources, sans installation, ajoutez -f (--fetchonly) :

Documentation des paquets installés

Beaucoup de programmes sont livrés avec leur propre documentation; son installation dépend souvent du drapeau USE doc. Vous pouvez vérifier si un paquet porte ce drapeau dans la ligne USE= de la sortie de emerge -pv montrée plus haut.

Il vaut mieux activer le drapeau pour des paquets individuels dans /etc/portage/package.use/ plutôt que globalement - sinon la documentation sera entraînée dans chaque compilation. Ceci est décrit en détail dans la section Variables USE.

Après l'installation, la documentation se trouve généralement dans un sous-répertoire de /usr/share/doc/ nommé d'après le paquet et sa version :

La méthode fiable pour obtenir la liste exacte de la documentation est une requête à la base des fichiers installés avec equery (du paquet app-portage/gentoolkit) :

/usr/share/doc/eselect-1.4.32/AUTHORS.bz2
/usr/share/doc/eselect-1.4.32/ChangeLog.bz2
/usr/share/doc/eselect-1.4.32/NEWS.bz2
/usr/share/doc/eselect-1.4.32/README.bz2

L'option --filter peut afficher aussi d'autres catégories de fichiers; les détails sont donnés dans la section Autres fonctionnalités de Portage.

Suppression de programmes

La suppression sûre d'un programme commence par signaler à Portage que vous n'en avez plus besoin :

La commande retire le paquet de la liste des installations explicites, après quoi il devient candidat pour depclean. En soi, --deselect ne supprime aucun fichier; l'option --depclean (forme courte -c) débarrasse le système du paquet et des dépendances devenues inutiles :

La liste des paquets installés explicitement est conservée dans le fichier /var/lib/portage/world. Dans Calculate, son contenu n'est pas formé par l'utilisateur seul : la liste est assemblée par les modèles de la distribution depuis /var/db/repos/calculate/profiles/templates/6_ac_update_sync/world/create/, c'est pourquoi le fichier commence par un en-tête de service énumérant les modèles traités. Un tel modèle ressemble à ceci :

# Calculate name=world format=world

#?in(os_linux_pkglist, calculate)!=#
media-fonts/terminus-font
sys-apps/busybox
sys-apps/calculate-toolkit
#sys-apps/ifplugd
sys-apps/less

Les lignes qui commencent par # ne sont pas ajoutées à la liste. Le mécanisme des modèles est décrit sur la page Templates.

Mise à jour système

Pour que le système reste en ordre et continue de recevoir les mises à jour de sécurité, il doit être mis à jour régulièrement. La voie standard de Calculate est la commande cl-update : elle synchronise les dépôts, met à jour les paquets, applique les modèles et protège les fichiers de configuration contre l[HTML_REMOVED]écrasement :

Pour un contrôle ciblé, vous pouvez travailler avec les outils de Portage lui-même. Pour mettre à jour les paquets installés, utilisez emerge avec les options -u (--update), -D (--deep) et -N (--newuse) :

Avec -D, Portage cherche aussi des versions plus récentes des dépendances installées; sans lui, seules les versions des paquets installés explicitement sont vérifiées - ceux qui sont répertoriés dans /var/lib/portage/world - tandis que leurs dépendances sont laissées en l'état. C'est pourquoi -D est appliqué presque toujours. L'option -N force la recompilation des paquets dont les drapeaux USE ont changé depuis l'installation - vous en avez besoin après une modification de USE. Les deux variantes (cl-update et emerge -uDN @world) fonctionnent; pour les mises à jour régulières de la distribution, cl-update est le choix standard.

Meta-paquets

Certains paquets de l'arborescence ne contiennent pas de programme de travail propre - ils existent pour qu'un ensemble de composants liés puisse être installé par une seule commande. Par exemple, kde-plasma/plasma-meta installe l'environnement Plasma, en entraînant les paquets Plasma comme dépendances.

Supprimer un meta-paquet par un simple emerge --deselect donne peu de résultat : ses dépendances restent dans le système. Portage peut nettoyer les dépendances orphelines, mais la disponibilité des programmes est déterminée dynamiquement, donc avant le nettoyage vous devez mettre le système entièrement à jour (avec toutes les modifications apportées par l'édition des drapeaux USE), puis supprimer les paquets orphelins et, si nécessaire, recompiler les applications qui étaient liées dynamiquement aux paquets supprimés et n'en ont plus besoin. Les deux commandes :

Licences

Chaque ebuild indique la licence du paquet dans la variable LICENSE - vous pouvez aussi la voir dans la sortie de recherche. Un avertissement important : LICENSE dans un ebuild est un repère pour les développeurs et les utilisateurs, pas une déclaration juridique; elle ne garantit pas une correspondance exacte avec la licence de chaque fichier installé.

La variable ACCEPT_LICENSE gère les licences autorisées. Dans Calculate, elle vaut * par défaut, c'est-à-dire que les licences ne sont absolument pas restreintes - l'installation d'un paquet sous n'importe quelle licence est permise. Le mécanisme lui-même reste standard pour Portage.

La valeur de ACCEPT_LICENSE est une liste de licences acceptées et rejetées : un nom préfixé d'un moins interdit l'installation. Les groupes de licences s'écrivent avec le préfixe @ :

• @FREE - les licences libres approuvées par les organisations du logiciel libre ou conformes à la définition du logiciel libre;
• @BINARY-REDISTRIBUTABLE - les licences qui permettent la distribution de paquets binaires;
• @EULA - les licences qui exigent d'accepter le texte du contrat de licence utilisateur final.

Les textes des licences se trouvent dans le répertoire /var/db/repos/gentoo/licenses/, et la composition des groupes dans le fichier /var/db/repos/gentoo/profiles/license_groups : chaque ligne commence par le nom du groupe en majuscules, suivi des licences séparées par des espaces; un groupe peut en inclure d'autres - ils sont répertoriés avec le préfixe @.

Vous pouvez durcir la politique, par exemple pour tout autoriser sauf les accords EULA - pour cela, la ligne est ajoutée au fichier utilisateur /etc/portage/make.conf/custom : ACCEPT_LICENSE="* -@EULA". Un tel paramétrage acceptera aussi les programmes non libres et la documentation non libre. Comment définir les variables de construction et où se trouvent les fichiers de configuration - voir la section Configuring through variables.

Les exceptions individuelles s'écrivent dans le fichier /etc/portage/package.license (créé par l'utilisateur) : d'abord le nom complet du paquet, puis la licence ou le groupe. Par exemple, voici comment la licence du firmware est acceptée :

# Autoriser le firmware linux-firmware sous la licence de redistribution
sys-kernel/linux-firmware @BINARY-REDISTRIBUTABLE

Remarque : autoriser une licence pour un paquet ne s'étend pas aux autres paquets ayant la même licence - chacun est indiqué séparément.

Quand Portage se plaint

La formulation des messages de Portage et les versions des paquets dans les exemples de cette section sont illustratives : le texte et les chiffres exacts sur votre système peuvent différer.

Slots, paquets virtuels, branches, architectures, profil

Portage prend en charge de nombreuses fonctionnalités que les autres gestionnaires de paquets n'offrent pas. Ce qui suit présente les concepts de base, sans les détails.

Différentes versions d'un même paquet peuvent coexister dans le système. Là où d'autres distributions créent pour cela des noms versionnés (gtk+2 et gtk+3), Portage utilise les slots (SLOT) : un ebuild déclare un slot pour sa version, et les ebuilds de slots différents ne sont pas en conflit. Par exemple, le paquet gtk+ a des ebuilds avec SLOT="2" et SLOT="3".

Certains paquets offrent la même fonctionnalité dans différentes implémentations : metalogd, sysklogd et syslog-ng sont tous des services de journalisation système. Une application qui a besoin de "l'un des services de journalisation" ne peut pas dépendre d'une implémentation concrète : les autres ne valent pas mieux. Pour ces cas, Portage dispose des virtuals : chaque journaliseur est répertorié comme alternative du paquet virtuel virtual/logger, et les applications dépendent de ce dernier. Installer un paquet virtuel entraîne l'une des implémentations, que Portage choisit ; si un journaliseur est déjà installé, le paquet virtuel est considéré comme satisfait.

Les programmes de l'arborescence sont répartis entre les branches. Par défaut, le système n'accepte que les paquets marqués stables. La plupart des programmes nouvellement ajoutés à l'arborescence aboutissent dans la branche de test (~arch) : leurs ebuilds sont visibles dans l'arborescence, mais Portage ne les installera pas tant que le paquet n'aura pas été déplacé vers la branche stable. L'activation de paquets de test individuels est décrite dans la section Mélanger des branches.

Tous les programmes ne sont pas disponibles pour toutes les architectures : certains peuvent ne pas fonctionner sur certaines, nécessiter des tests supplémentaires, ou n'avoir tout simplement jamais été vérifiés par un mainteneur.

Tout système suit un profile - un ensemble de paramètres qui conserve, entre autres, la liste des paquets requis pour un fonctionnement normal. Dans Calculate, le profil est défini par le dépôt distros (pour CLD, c'est distros:CLD/amd64/20), qui se situe au-dessus du profil Gentoo de base. Vous ne pouvez pas basculer le profil avec eselect : les paquets binaires du miroir et les modèles world en dépendent, et un basculement endommagerait la distribution. La configuration se fait à l'aide des drapeaux USE, des mots-clés et des masques dans les fichiers sous /etc/portage/.

Paquets bloqués

Un ebuild possède des champs de dépendances : une dépendance de construction est déclarée dans DEPEND, une dépendance d'exécution dans RDEPEND. Si l'une des dépendances marque explicitement un paquet ou un paquet virtuel comme incompatible, un blocage apparaît. L'avertissement ressemble à ceci (il est généralement visible avec --pretend) :

[ebuild  N     ] <package-A>
[blocks B      ] <package-A> ("<package-A>" is blocking <package-B>)

* Error: The above package list contains packages which cannot be
 * installed at the same time on the same system.

(<package-A>:0/0::gentoo, ebuild scheduled for merge) pulled in by
    <package-A>

(<package-B>:0/0::gentoo, installed) pulled in by
    <package-B> required by @selected

Les nouvelles versions de Portage viennent à bout seules des blocages mineurs, mais certains conflits exigent une décision manuelle. Les options : renoncer à installer le paquet litigieux, ou supprimer le paquet en conflit par emerge --deselect …. Il vaut mieux ne pas supprimer de force mais signaler à Portage que le paquet n'est plus nécessaire : alors, après depclean, il quitte à la fois la liste world et le système.

Parfois, le blocage est défini par un atome de version exact, par exemple <media-video/mplayer-1.0_rc1-r2; dans ce cas, le blocage est levé en mettant à jour le paquet en conflit vers une version plus récente. Cas rare : deux paquets pas encore installés qui se bloquent mutuellement : cherchez pourquoi les deux sont nécessaires - en général, un seul suffit. Si les deux sont vraiment nécessaires, signalez-le aux développeurs de la distribution.

Paquets masqués

Lorsque vous essayez d'installer un paquet indisponible pour le système, Portage signale le masquage :

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

Le masquage a toujours une raison :

Vous pouvez lever le masque d'un paquet donné à l'aide de vos propres mots-clés et masques dans /etc/portage/package.accept_keywords/ et /etc/portage/package.unmask/ - voir Mélanger des branches.

Modifications requises des drapeaux USE

Il arrive que le paquet en cours d'installation exige qu'une dépendance soit compilée avec un drapeau USE précis. Dans Calculate, --autounmask est déjà activé dans EMERGE_DEFAULT_OPTS, donc Portage propose lui-même une ligne prête pour le fichier package.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

Sans --autounmask, la même situation devient une erreur signalant l'absence de variantes compilées :

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])

Dans l'exemple, le paquet app-text/happypackage a besoin d'app-text/feelings compilé avec USE="test", alors que le système n'a pas ce drapeau d'activé. La solution : ajoutez le drapeau requis au paquet dans /etc/portage/package.use/ (le fichier stub custom y est déjà) ou, plus rarement, globalement à la variable USE dans le fichier /etc/portage/make.conf/custom. En détail - la section Variables USE.

Paquet inexistant

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 en cours d'installation dépend d'un paquet indisponible pour le système. Si le système ne mélange pas les branches, cela ne devrait pas se produire - c'est une erreur dans l'arborescence : vérifiez par rapport à la liste des erreurs connues et, si nécessaire, signalez-en une nouvelle aux développeurs.

Nom de paquet ambigu

[ 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 nom choisi correspond à plusieurs paquets de catégories différentes. Les options sont déjà énumérées dans le message ci-dessus - précisez le nom complet avec la catégorie.

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 à installer dépendent l'un de l'autre, et ne peuvent donc pas être installés. En général, c'est une erreur dans l'un des paquets de l'arborescence : après un moment, mettez à jour l'arborescence et réessayez; vérifiez par rapport à la liste des erreurs connues et signalez-en une nouvelle si nécessaire.

Erreur de 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 du paquet indiqué et essaiera de poursuivre l'installation du reste (là où c'est possible). Les causes : un miroir a été mal synchronisé, l'ebuild pointe vers une adresse erronée, ou le serveur de sources est indisponible. Répétez la tentative dans une heure - si l'erreur persiste, signalez-la aux développeurs.

Protection du profil système

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

Vous demandez la suppression d'un paquet de l'ensemble de base du système : il est marqué comme obligatoire dans le profil et ne devrait pas être supprimé.

Échec de la vérification du digest

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

C'est le signe d'un problème dans l'arborescence elle-même - le plus souvent une erreur lors de l'ajout de l'ebuild. N'essayez pas de recréer le manifeste vous-même : appeler l'utilitaire ebuild avec la commande manifest ne corrigera pas la situation et risque plutôt de l'aggraver (cet utilitaire de bas niveau est décrit en détail dans la section Utiliser ebuild). Attendez une heure ou deux : l'erreur a probablement déjà été remarquée, et le correctif parviendra bientôt aux miroirs. Si cela ne suffit pas - signalez-la aux développeurs, et après le correctif, mettez à jour l'arborescence pour obtenir les bonnes sommes de contrôle.

Voir aussi

• Variables USE
• Fonctionnalités Portage
• Variables d'environnement
• Fichiers et répertoires
• Configuring through variables
• Mélanger des branches
• Autres fonctionnalités de Portage
• Se tourner vers une source tierce
• Utiliser ebuild