Project:AMD64/Multilib layout

At this moment, Gentoo supports two different multilib layouts for AMD64. The main difference between those layouts is the presence of lib symlink. They are therefore informally called the SYMLINK_LIB=yes and SYMLINK_LIB=no layouts.

The layouts

SYMLINK_LIB=yes layout (old)

The main feature of this layout is the presence of lib compatibility symlink. In this layout:

64-bit libraries are installed into lib64 directory,
32-bit libraries are installed into lib32 directory,
lib is a symlink to lib64, so packages installed into lib are actually installed to the lib64 directory.

SYMLINK_LIB=no layout (17.1 profiles)

In this layout, the compatibility symlink is removed, and canonical directories are used. That is:

64-bit libraries are installed into lib64 directory,
32-bit libraries are installed into lib directory,
lib is a real directory, so packages using that directory are not moved to lib64.

Rationale

How are libdirs chosen?

Many users have asked why X and not Y? The answer is, canonical libdir names are derived from the program interpreter paths used on Linux. Those paths are hardcoded in created executables by the compiler and must be static for programs to be portable across different Linux systems.

The values used by the various ABIs are:

/lib/ld-linux.so.2 for 32-bit x86 ABI,
/lib64/ld-linux-x86-64.so.2 for x86_64 (amd64) ABI,
/libx32/ld-linux-x32.so.2 for the x32 ABI.

The appropriate libdir values are derived from those paths.

Why lib and not lib32?

Using lib is beneficial to compatibility with prebuilt x86 software, e.g. old games. All that software is naturally built to use lib as libdir, and using the same directory on multilib amd64 systems improves compatibility and reduces the need for custom hacks to keep things working.

Why lib64 and not lib?

Some people have argued that lib should be used for the default ABI. This is not true. Gentoo has always used lib64 as canonical amd64 libdir, and using it improves compatibility with other Linux distributions that use the same layout, and therefore with prebuilt software.

Future plans

Will the old layout continue to be supported?

No. While we're planning to support the old layout for some time to come, we will eventually drop support for it and expect all users to migrate to the new one eventually. While we don't expect any major breakage for users still using the old layout, we will eventually stop patching software to support it.

The exact timeline for the termination of support hasn't been provided yet. We are planning to define it when the relevant tooling and profiles become stable.

Will alternative multilib layouts be supported?

No. While Gentoo is very flexible and supports a lot of customization, we are not planning to officially support non-standard multilib layouts.

This doesn't mean you can't use it. However, you will probably have to fork sys-apps/baselayout and possibly carry some local patches to packages. You won't be able to expect developers to test your layout, nor to carry downstream patches to support it.

Common issues

Programs installing 64-bit libraries to /usr/lib (not respecting libdir)

Historically, the most common problem with SYMLINK_LIB=no layout were programs that installed 64-bit libraries to /usr/lib, either due to mistake in the ebuild or incorrect assumptions in the build system. However, majority of those issues were caught by the multilib-strict feature in Portage which were used by many developers for a long time and finally became the default in July 2017.

Any ebuilds that attempt to install native libraries to /usr/lib need to be fixed to use get_libdir function (provided by EAPI 6 or multilib.eclass in earlier EAPIs) to obtain the correct library directory name.

Programs using lib and lib64 interchangeably

The other common problem with the new layout is that some ebuilds wrongly relied on the equivalence of lib and lib64 directories. This happens e.g. if a program internally references /usr/lib but the ebuild was modified to install to the correct lib64 directory.

The correct solution depends on the package in question. Frequently the lib directory is used as libexec-style destination, in which case it is entirely valid to install 64-bit software there and the ebuild should be modified not to alter the libdir. Otherwise, the upstream software may need patching to respect libdir.