Gentoo Binary Host Quickstart

This page contains changes which are not marked for translation.

Resources

Gentoo systematically provides binary packages through the Gentoo binary package host (aka Gentoo binhost), using mirrors hosted by the Gentoo project. Binary packages from the Gentoo binhost can make installation and updates easier and quicker, especially on less performant hardware.

For many years Portage has included support for binary packages, and a few binary "-bin" packages have been provided in the Gentoo ebuild repository. With the new Gentoo binary package host, binary package availability has been widened even more, and installing and updating software on Gentoo is now quicker and easier than ever! See the news item for more information.

For amd64 (x86-64) and arm64 (aarch64), the Gentoo binhost includes many packages used on desktop systems, from KDE Plasma to Gnome and from LibreOffice to TeXLive, and these binary packages are updated daily. For other architectures and system types, the package directories contain just the core packages, and the binary packages for these arches are updated approximately once a week.

There are advantages to using the pre-built binary packages, though building packages locally from source also has value for some cases. For a given system, the choice between binary or source-based packages might depend on things like the specific use-case, and user-preference. Gentoo aims to provide users with the choice to use the distribution in the way that suits them best (see here for further information), so Portage can default to binary packages, and fall back on source-builds when requested or required.

This article describes using the fully-supported Gentoo binary package host for amd64 and arm64 with the settings the packages are compiled with. Further documentation shows what is supported on other architectures and profiles.

See also
The binary package guide has more general information on binary packages and binary package hosts on Gentoo. The binhost project page has information about the development of the Gentoo binhost.

Advantages of using the Gentoo binhost and what isn't available with it

There are several key benefits to using the Gentoo binary package host:

Ease and speed of getting a full installation up and running from scratch
Fast package installation and upgrades
Storage or RAM availability is no longer an issue when installing larger packages (i.e., some packages need X GB of RAM for their compilation)
Older systems can be set up rapidly and maintained without waiting longer than needed for packages to build (compile)
Fast updates and fast set-up time for cloud instances

The main downside of using binary packages from the Gentoo binhost, over compiling locally, is that -march=native or similar optimizations are not available, which can reportedly give up to a 5% boost on x86-64 processors for some cases. Of course if these optimizations are required, packages can always be built locally, even when mixing binary packages into the installation.

The Gentoo binhost can only provide binary packages if the locally-requested USE flag combination is not changed from the default setting(s) used for the creation of the binary packages. If the user requests non-default USE flags for a package, then the package will need to be compiled locally. Portage can automatically either install from a binary package by default, or build a package locally when needed.

Configuration

binrepos.conf

Files in the directory /etc/portage/binrepos.conf tell Portage where to find binary packages. New Stage3 files already come with a suitable binrepos.conf configuration; in existing installations it will need to be added.

Using a local Gentoo mirror is highly recommend to reduce server load and to speed up downloads on the local end:

FILE /etc/portage/binrepos.conf/gentoobinhost.confCDN Mirror Example, amd64

[binhost]
priority = 9999
sync-uri = https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64/

FILE /etc/portage/binrepos.conf/gentoobinhost.confUK Mirror Example, amd64

[binhost]
priority = 9999
sync-uri = https://www.mirrorservice.org/sites/distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64/

FILE /etc/portage/binrepos.conf/gentoobinhost.confCN Mirror Example, arm64

[binhost]
priority = 9999
sync-uri = https://mirrors.aliyun.com/gentoo/releases/arm64/binpackages/23.0/arm64

The sync-uri in binrepos.conf contains at its end the local system architecture and type of installation. The examples above are given for normal amd64 or arm64 installations. .

Note
An x86-64-v3 directory exists, which is strongly recommended if your CPU supports that microarchitecture level. For more details, see the news article.

Note
When using a hardened, musl, llvm profile, x32, or even an entirely different architecture, these paths are not correct. Corresponding directories exist, but have only the package set found within the stage3.

Configure Portage to use binary packages by default

To automatically download and use a binary package when a suitable one is available on the servers, enable the getbinpkg Portage feature:

FILE /etc/portage/make.conf

FEATURES="getbinpkg"

If no suitable binary package can be found, the package will be compiled from source as usual. This is equivalent to adding --getbinpkg to EMERGE_DEFAULT_OPTS in /etc/portage/make.conf or to the emerge command line.

Package signature verification

Now, enable the binpkg-request-signature Portage feature to require verification of GPG signatures:

FILE /etc/portage/make.conf

FEATURES="binpkg-request-signature"

Once binary packages have to be downloaded, emerge will automatically run the Gentoo Trust Tool known as getuto to set up a ring of GPG keys that are trusted for binary package installation.

Troubleshooting

In the past, /etc/portage/gnupg may have been used for older methods of verifying the Gentoo repository. If it exists, getuto won't override it, but the correct settings may be missing. If hitting issues, move away the old directory, then run getuto again:

root #mv /etc/portage/gnupg /etc/portage/gnupg.bak ; getuto

EMERGE_DEFAULT_OPTS

Below are some useful settings that can be applied via EMERGE_DEFAULT_OPTS in make.conf or on the emerge command line to improve the experience of working with Gentoo binary packages.

--getbinpkg (-g)

Adding --getbinpkg will automatically download and use a binary package when a suitable one is available on the servers. If no suitable binary package can be found, the package will be compiled from source as usual.

This option should still be supplied when using the other options in this section.

--usepkgonly (-K)

Using --usepkgonly will tell Portage to only use binary packages and exit if no suitable one can be found locally or (with -g) for download.

--with-bdeps=y

This can be set to y(es) or n(o) and controls whether build dependencies of packages are downloaded and/or installed. For binary package installation, it defaults to no. For source-based installation, the build dependencies are required and are accordingly also installed.

--binpkg-respect-use=y

Warning
Do not set --binpkg-respect-use=n lightly, in EMERGE_DEFAULT_OPTS or otherwise. It will break the system.

By default, Portage will accept binary packages only if use flags match the precise requirements and compile the package from source otherwise. It will also log a warning: "The following binary packages have been ignored due to non matching USE:"
When the option is explicitly set to y(es), the warning is disabled.
When the option is explicitly set to n(o), the differences between a user's configuration and the configuration used to make the binary package are ignored, and the binary package is installed anyway. Warning: Dangerous.

In some cases, it is desirable to sacrifice choice of USE flags in order to expand the number of binary packages that can be installed. Leaving the option unset is therefore useful, because portage will print possible package.use lines which can be used to opt in to those binaries. Otherwise, it is best to set the option to y(es).

Emerging packages

When emerging packages, add a single switch to the emerge command line: --getbinpkg (-g).

Single package

To install a single package using the binhost use the command below:

root #emerge --ask --verbose --getbinpkg app-editors/nano

or the shorthand:

root #emerge -avg app-editors/nano

System update

To perform a full system update using the binhost use:

root #emerge --ask --verbose --update --deep --changed-use --getbinpkg @world

or shorthand:

root #emerge -avuDUg @world

Package settings

amd64, amd64/23.0/x86-64

CFLAGS

The packages are built with CFLAGS="-O2 -pipe -march=x86-64 -mtune=generic", which means all x86-64 CPUs are supported.

Profiles

This binhost is built with USE flags of the following profiles:

default/linux/amd64/23.0/no-multilib
default/linux/amd64/23.0/desktop/gnome
default/linux/amd64/23.0/desktop/gnome/systemd
default/linux/amd64/23.0/desktop/plasma/systemd

This will cover most of the USE flag combinations needed for both a OpenRC and systemd system.

Selected packages

Each profile has a world file as well, listing the packages which will be built (along with their build dependencies). These can be found in the subdirectories of https://gitweb.gentoo.org/proj/binhost.git/tree/builders/milou

There is also a "lottery" that will randomly try to build a few packages each day, per profile. Those additional packages may disappear over time as they are version-bumped, and be replaced by entirely different packages.

x86-64-v3 variant

Most configuration is identical between x86-64 and x86-64-v3, but there are two tweaks:

The packages are built with CFLAGS="-O2 -pipe -march=x86-64-v3" instead.
Additionally, package.use contains */* CPU_FLAGS_X86: avx avx2 f16c fma3 mmx mmxext popcnt sse sse2 sse3 sse4_1 sse4_2 ssse3.

arm64, arm64/23.0

CFLAGS

The packages are built with CFLAGS="-O2 -pipe", which means all arm64 CPUs are supported.

Profiles

This binhost is built with USE flags of the following profiles:

default/linux/arm64/23.0
default/linux/arm64/23.0/desktop/gnome/systemd
default/linux/arm64/23.0/desktop/plasma/systemd

This will cover most of the USE flag combinations needed for both a OpenRC and systemd system.

Selected packages

Each profile has a world file as well, listing the packages which will be built (along with their build dependencies). These can be found in the subdirectories of https://gitweb.gentoo.org/proj/binhost.git/tree/builders/dola

There is also a "lottery" that will randomly try to build a few packages each day, per profile. Those additional packages may disappear over time as they are version-bumped, and be replaced by entirely different packages.

Other arches and experimental profiles on amd64 and arm64

Note
Only the packages offered in a stage3 are provided here like sys-devel/gcc and sys-app/shadow as two examples. These are also updated weekly rather than daily

CFLAGS

The packages are built with CFLAGS="-O2 -pipe", which means all CPUs are supported in their respect profile architects.

Profiles

Listing a few examples of how this would work for a user's system.

amd64 using llvm as system compiler:

default/linux/amd64/23.0/clang

arm64 using musl as the libc:

default/linux/arm64/23.0/musl

ppc using the standard profile:

default/linux/ppc/23.0

m68k using systemd:

default/linux/m68k/23.0/systemd

USE flags will be the defaults set by the profile itself.

Frequently asked questions

Various questions are covered in the Gentoo news Gentoo goes Binary!.

Review the frequently asked questions before asking for help when using the Gentoo binhost.

Update GCC first

When using the binhost always use the latest stable version of GCC to avoid errors like /usr/libexec/gcc/x86_64-pc-linux-gnu/ld: /usr/lib/gcc/x86_64-pc-linux-gnu/12/../../../../lib64/libSPIRV-Tools-opt.so: undefined reference to `std::ios_base_library_init()@GLIBCXX_3.4.32

I used to have a binary package but not anymore, what happened?

Builds are scheduled around 5am EST and may take a couple hours to finish building (except when dev-libs/icu has a major version bump, in which case you will have to wait all day because there is just SO MUCH to rebuild. Sorry about that!) Try waiting a bit. Getting in the habit of doing your daily updates later in the day might help too. You may also wish to keep an eye on bug #924772.

Note that some additional packages are also built by lottery every day. Winning that lottery one day doesn't guarantee it will be built the next time that package gets a version bump.

Portage still tries to compile from source

If there is a binary package available on a binhost but Portage is not using it, it may well be because of a mismatch between the USE flags that were requested to install the package with, and the USE flags that were applied to build the binary package.

The USE flags that were used to build the available binary package may be listed by using the following command:

user $emerge --pretend --getbinpkg --usepkgonly --binpkg-respect-use=n <package-X>

To allow Portage to install from the available binary package, adjust the requested USE flags accordingly, in /etc/portage/make.conf or /etc/portage/package.use.

Preferring binary to source for particular packages

There is currently no way to specify that the binary version of a particular package should be preferred to the source version. The functionality is planned, but there is no specific timeline for implementation at this stage.^[1] Refer to bug 463964 and bug 924772.

Troubleshooting

Emerge complains with "there are no binary packages to satisfy <package>"

If --getbinpkg (-g) isn't supplied, Portage won't search the binhost for binary packages, even if --usepkgonly (-K) is supplied.

If --getbinpkg is being supplied to portage, users should make sure the package exists on the binhost by visiting the URL in /etc/portage/binhost.conf in a web browser.

keyblock resource: '/etc/portage/gnupg/pubring.kbx': No such file or directory

The keyring in /etc/portage/gnupg/ needs to be generated. If /etc/portage/gnupg/ does not exist, run getuto.

If that directory does exist, follow the instructions in section Troubleshooting.

References

↑ Gentoo forums post. Accessed on 2024-03-17.

[1] Gentoo forums post. Accessed on 2024-03-17.

[1]