An Introduction to Portage

Updated 4 June 2019

Welcome to Portage

Portage is one of the best software management tools available in Linux, due to its high flexibility and extremely rich features. Portage is written on Python and Bash.

Most users will use the emerge command to interact with Portage. Please note, however, that this doc does not cover all of the emerge man page. All available options of the emerge command can be viewed here.

Portage tree

Ebuild files

When speaking of packages, we often refer to software available to Calculate users through the Portage tree. The Portage tree is a set of ebuild files containing all the information that Portage needs to manage the software (for installation, search, extraction, etc.) By default, the ebuilds are located in /usr/portage/ and /var/lib/layman/calculate/. The second path points to the Calculate overlay, which also contains ebuilds.

When dealing with a package, Portage refers to its ebuild file, to be found on the system. Therefore, it is essential to regularly update the ebuilds, so that Portage stays aware of new software, security updates, etc.

Updating the Portage tree

The Portage tree is updated with the git command and runs whenever cl-update is called. To update the Portage tree without actually installing packages, run the following:

cl-update -s

Software maintenance

To search software in the Portage tree by name, you can use the built-in features of the emerge command. By default, emerge --search outputs the packages that match (either completely or partially) the specified search criteria.

For example, if you want to find all the packages that have "pdf " in their name, run the following:

emerge --search pdf

In addition, the --searchdesc (or -S) parameter can be used to search in the package description.

Существуют вспомогательные средства для ускорения и автоматизации стандартных задач типа поиска по дереву Portage, формирования списка установленных пакетов, принадлежащих какой-либо категории и т.д. Для выполнения быстрого поиска пакета используйте утилиту eix. To learn more, please refer to the manual.

Install

Once you have found an application that suits your needs, you can easily install it with emerge. Here is an example for app-office/gnumeric:

emerge gnumeric

Since many applications depend on each other, any attempt to install new software may involve installing additional packages. Keep calm and trust Portage. If you absolutely want to know what exactly Portage is going to install with the package you need, run the command with the -p (or --pretend) option. Such as in:

emerge -p gnumeric

После команды на установку пакета Portage загружает из интернета необходимый исходный код (при необходимости), и по умолчанию сохраняет его в каталоге /var/calculate/remote/distfiles/. После этого пакет распаковывается, компилируется и устанавливается. Если вы хотите, чтобы Portage только загрузил исходный код без его установки, добавьте к команде emerge параметр -f (или --fetchonly):

emerge -f gnumeric

Documentation

Many packages provide their own documentation. Sometimes, you can use the "doc" USE flag to define whether to install the package documentation. To check the status of this USE flag', run emerge -pv <name_package>.

Example:

emerge -pv eselect

Local copy of remote index is up-to-date and will be used.

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

Calculating dependencies  ... done!
[binary   R    ] app-admin/eselect-1.4.13::gentoo  USE="-doc -emacs -vim-syntax" 86 KiB

Total: 1 package (1 reinstall, 1 binary), Size of downloads: 86 KiB

USE-флаг doc можно включить или отключить как глобально в файле /etc/portage/make.conf/custom, так и для отдельных пакетов, создав файл в директории /etc/portage/package.use/ и указать в нём флаг. В главе USE-флаги этот вопрос описывается более подробно.

Documentation from the newly installed package can usually be found in the corresponding subdirectory of /usr/share/doc/.

Example:

# ls -l /usr/share/doc/eselect-1.4.13

итого 56
-rw-r--r-- 1 root root   309 фев 25 01:40 AUTHORS.bz2
-rw-r--r-- 1 root root 18961 фев 25 01:40 ChangeLog.bz2
-rw-r--r-- 1 root root  5373 фев 25 01:40 developer-guide.txt.bz2
-rw-r--r-- 1 root root  5062 фев 25 01:40 NEWS.bz2
-rw-r--r-- 1 root root   799 фев 25 01:40 README.bz2
-rw-r--r-- 1 root root   689 фев 25 01:40 release-guide.txt.bz2
-rw-r--r-- 1 root root   471 фев 25 01:40 TODO.bz2
-rw-r--r-- 1 root root  2088 фев 25 01:40 user-guide.txt.bz2

You can also list all the installed files with the equery command, as shown below.

Example:

# equery f eselect

/usr
/usr/bin
/usr/bin/eselect
/usr/bin/kernel-config
/usr/bin/profile-config
/usr/bin/rc-config
/usr/share
/usr/share/bash-completion
/usr/share/bash-completion/completions
/usr/share/bash-completion/completions/eselect
/usr/share/doc
/usr/share/doc/eselect-1.4.13
...

Remove

To remove a package from your system, use emerge -C (or --unmerge). Это приведет к удалению из системы всех файлов, установленных пакетом, кроме конфигурационных файлов приложения, изменявшихся после установки. Сохранение конфигурационных файлов позволяет вернуться к работе с пакетом, если вы когда-нибудь решите снова его установить.

emerge -C gnumeric

Warning

Note that Portage does not check whether the package that is being removed has installed dependencies. Однако вы получите предупреждение, если удаление пакета приведет к неработоспособности системы.

После удаления пакета из системы остаются пакеты, установленные по зависимостям. Чтобы Portage выявила все когда-то нужные пакеты, которые теперь можно удалить, используйте команду emerge -c (или --depclean). We shall get back to that later.

Другой способ удаления пакета - использовать команду emerge -cv (или --depclean --verbose). В этом случае пакетный менеджер выполнит удаление только в том случае, если у пакета нет зависимостей. If applicable, those will be displayed on the screen. Example:

# emerge -cv firefox

Calculating dependencies... done!
  www-client/firefox-67.0 pulled in by:
    www-plugins/firefox-ublock-1.19.3.11 requires www-client/firefox

>>> No packages selected for removal by depclean
Packages installed:   1189
Packages in world:    203
Packages in system:   43
Required packages:    1189
Number removed:       0

www-client/firefox was not removed, as it depends on the www-plugins/firefox-ublock package, still installed. Delete both of the packages, as shown below:

emerge -cv firefox firefox-ublock

System update

Чтобы система сохранялась в отличной форме (не говоря уже об установке свежайших обновлений, связанных с безопасностью), ее нужно регулярно обновлять. Так как Portage просматривает сборочные файлы только в локальном дереве портежей и оверлее, прежде всего потребуется обновить их. После обновления дерева Portage вы сможете обновить систему командой emerge -u world. В следующем примере мы также оперируем параметром -a (или --ask), который поручает Portage вывести список пакетов, которые она собирается обновить, и спросить пользователя, можно ли продолжать:

emerge -ua world

Portage будет искать более новые версии установленных приложений. Однако проверяются только версии приложений, явно установленных вами, а не тех, от которых они зависят. Если вы хотите обновить каждый пакет в системе, добавьте аргумент -D (или --deep):

emerge -uDa world

Поскольку обновления, относящиеся к безопасности, случаются и в пакетах, которые были установлены по зависимостям, рекомендуется время от времени запускать эту команду.

Если вы меняли какие-либо из USE-флагов, возможно, впоследствии вы также захотите добавить параметр -N (или --newuse). Then Portage will check if this modification requires installing new packages or recompiling existing ones:

emerge -uDNa world

В состав Calculate Linux входит утилита cl-update, при помощи которой можно выполнить обновление системы. Программа выполнит обновление Portage, установит обновление и в конце удалит неиспользуемые зависимости. To update, run:

cl-update

Meta-packages

У некоторых пакетов в дереве портежей нет содержимого как такового, так что они используются для установки набора других пакетов. Например, пакет kde полностью устанавливает среду KDE в вашей системе, привлекая различные KDE-пакеты в качестве зависимостей.

Если вы когда-либо захотите удалить из системы такой пакет, запуск emerge --unmerge не возымеет должного эффекта, поскольку пакеты, от которых он зависит, останутся в системе.

В Portage существует возможность удаления остаточных зависимосей, но, так как зависимости программ со временем меняются, прежде всего потребуется полностью обновить всю систему, включая реализацию изменений, произведенных путем модификации USE-флагов. После этого можно запустить emerge -c (или --depclean), чтобы удалить остаточные зависимости. Когда это будет сделано, вам потребуется пересобрать приложения, ранее динамически связанные с удаленными пакетами, в которых они теперь не нуждаются.

Only three commands are necessary to do this:

emerge -uDNa world

emerge -ca

revdep-rebuild

Когда Portage жалуется...

Слоты, виртуалы, ветви, архитектуры и профили

Как уже сказано, Portage - чрезвычайно мощная система, поддерживающая множество возможностей, не хватающих другим системам управления программами. Чтобы это стало понятно, разберем несколько аспектов Portage, не вникая в подробности.

С помощью Portage разные версии отдельного пакета могут сосуществовать в одной системе. В то время, как другие системы управления стремятся называть пакеты в соответствии с версией (например freetype и freetype2), в Portage используется технология слотов (SLOT), или областей. Пакет присваивает определенный слот своей версии. Пакеты с разными слотами способны сосуществовать в одной системе. Например, у пакета media-libs/freetype есть ebuild как со SLOT="1", так и со SLOT="2".

Существуют также пакеты, выполняющие одни и те же функции, но отличающиеся в реализации. Например metalogd, sysklogd и syslog-ng являются системными службами журналирования. Приложения, использующие "системный журнал", не могут зависеть от одной конкретной программы, например от metalogd, так как остальные программы ничем не хуже. В Portage предусмотрены виртуальные пакеты: каждая служба журналирования предоставляет virtual/syslog, и в результате в приложениях можно указывать зависимость от virtual/syslog.

Программное обеспечение может располагаться в различных ветвях дерева Portage. По умолчанию в системе разрешено только использование стабильных пакетов. Большинство новых программ при поступлении включаются в тестовую ветвь, что указывает на необходимость дополнительного тестирования перед тем, как включить их в стабильные. Хотя в дереве и видны сборочные файлы для таких программ, Portage не станет обновлять их до тех пор, пока они не будут помещены в стабильную ветвь.

Some software is not available for all architectures. Либо они не работают в определенных архитектурах, либо требуют дополнительного тестирования, или у разработчика нет возможности проверить, работает ли пакет в различных архитектурах.

Каждая установка Gentoo придерживается определенного профиля, который содержит, помимо прочего, список пакетов, необходимых для работоспособности системы.

Blocked packages

Пример предупреждения о заблокированных пакетах (с --pretend):

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

Ebuild files have fields to tell Portage about the dependencies. Возможны два вида зависимости: зависимость сборки, объявленная в переменной DEPEND, и зависимость выполнения, объявленная в переменной RDEPEND. Когда одна из этих зависимостей явно указывает на несовместимость пакета или виртуального пакета, это вызывает блокировку.

Для разблокировки можно отказаться от установки пакета или предварительно удалить конфликтующий пакет. In the example above, you can either choose to not install mail-mta/postfix after all, or remove mail-mta/ssmtp first.

Также возможно, что два пакета, подлежащие установке, блокируют друг друга. В этом редчайшем случае следует выяснить, действительно ли вам необходимо установить оба пакета: в большинстве случаев можно обойтись одним.

Masked packages

Пример предупреждения о замаскированных пакетах:

!!! 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)
- media-video/ati-gatos-4.3.0 (masked by: package.mask)
- sys-libs/glibc-2.3.2-r11 (masked by: profile)

Всякий раз, когда вы собираетесь установить пакет, не предназначенный для вашей системы, выдается ошибка маскировки. Нужно попытаться установить другую программу, существующую для вашей системы, или дождаться, пока пакет станет доступным. A package is always masked for a reason:

  • ключ ~arch: пакет недостаточно проверен для помещения в стабильную ветвь. Подождите несколько дней или недель и попробуйте установить его еще раз.
  • ключ -arch или ключ -*: пакет не работоспособен в вашей архитектуре. Если вы полагаете, что он работает, сообщите об этом в bugzilla.
  • ключ отсутствует: пакет еще не тестировался в вашей архитектуре. Попросите группу портирования в архитектуру проверить пакет, или протестируйте его за них и сообщите о своих изысканиях в bugzilla.
  • package.mask: обнаружено повреждение пакета, нестабильность или что-то худшее, и пакет заблокирован специально.
  • profile: пакет считается не предназначенным для вашего профиля. В случае установки приложение может вызвать сбой системы или просто несовместимо с используемым профилем.

Unavailable packages

Пример предупреждения об отсутствии пакета:

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.

Приложение, которое вы пытаетесь установить, зависит от другого пакета, недоступного вашей системе. Пожалуйста, проверьте, есть ли такой запрос в bugzilla, а если нет, сообщите об ошибке. If you are not mixing branches, this is clearly an error.

Ambiguous package name

Пример предупреждения о повторяющихся именах ebuild:

!!! The short ebuild name "aterm" is ambiguous.  Please specify
!!! one of the following fully-qualified ebuild names instead:

    dev-libs/aterm
    x11-terms/aterm

The name of the application you are going to install matches more than one package. You also have to specify the category. Portage предложит вам возможные варианты.

Circular dependencies

Пример предупреждения Portage о циклических зависимостях:

!!! 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

Два или более пакета, которые вы хотите установить, взаимно зависимы, и в результате их установка невозможна. This is most likely an error in the Portage tree. Update the Portage tree later and try again. Вы можете также проверить, есть ли эта ошибка в bugzilla, и если нет, то сообщить о ней.

Unpacking error

Пример предупреждения Portage об ошибке извлечения:

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

Portage не смогла загрузить исходный код данного приложения и попытается продолжить установку других приложений (если запланирована). Эта ошибка может произойти из-за неправильно синхронизированного зеркала или из-за того, что ebuild указывает на неверное место. Сервер, где находятся исходные коды, также может не работать по какой-либо причине.

Повторите действие через час, чтобы посмотреть, повторится ли эта ошибка.

System profile protection

Пример предупреждения Portage о пакете, защищенном профилем:

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

Вы попросили удалить пакет, входящий в состав базовых пакетов вашей системы. Он отмечен в вашем профиле как обязательный, и его не следует удалять из системы.