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 symlink. They are therefore informally called the SYMLINK_LIB=yes and SYMLINK_LIB=no 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 directory,
 * 32-bit libraries are installed into directory,
 * is a symlink to, so packages installed into are actually installed to the  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 directory,
 * 32-bit libraries are installed into directory,
 * is a real directory, so packages using that directory are not moved to.

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:
 * for 32-bit x86 ABI,
 * for x86_64 (amd64) ABI,
 * for the x32 ABI.

The appropriate libdir values are derived from those paths.

Why lib and not lib32?
Using is beneficial to compatibility with prebuilt x86 software, e.g. old games. All that software is naturally built to use 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 should be used for the default ABI. This is not true. Gentoo has always used as canonical amd64 libdir, and using it improves compatibility with other Linux distributions that use the same layout, and therefore with prebuilt software.

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, 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 need to be fixed to use get_libdir function (provided by EAPI 6 or  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 and  directories. This happens e.g. if a program internally references but the ebuild was modified to install to the correct  directory.

The correct solution depends on the package in question. Frequently the 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.