Multilib/Adding new ABIs

This article outlines the steps necessary to add a new ABI to gx86-multilib framework.

Adding a new ABI group (arch)

Once multilib support is introduced in a new architecture (or group of architectures), a new ABI group needs to be introduced. The group name serves as the USE flag prefix and needs to be the same for all arches involved in particular multilib. Preferably, it should match the most generic name for the arch group.

Examples of ABI groups are: abi_x86 (x86 and amd64), abi_ppc (ppc and ppc64), or abi_mips (mips).

The following steps need to be taken in order to add a new ABI group:

1. Create a profiles/desc/abi_xxx.desc file for the new ABI.
2. In the profiles/base/make.defaults file:
   1. Add ABI_XXX (an uppercase variant of ABI group name) into the USE_EXPAND variable.
   2. Add ABI_XXX into the USE_EXPAND_HIDDEN variable.
3. In the profiles/base/use.mask file:
   1. Mask all abi_xxx_* flags.
4. In profiles/arch/* for arches involved in the multilib:
   1. Set the default value for ABI_XXX in the make.defaults file.
   2. Add the native ABI entry (abi_xxx_yyy) to the use.force file.
   3. Unmask the native ABI (-abi_xxx_yyy) in the use.mask file.
   4. Set the native ABI as only ABI in IUSE_IMPLICIT in the make.defaults file.
5. In profiles/arch/* for multilib profiles of the above arches:
   1. Add -ABI_XXX to USE_EXPAND_HIDDEN in make.defaults to make the flags visible.
   2. Unmask other supported ABIs (-abi_xxx_yyy) in the use.mask file.
6. In eclass/multilib-build.eclass:
   1. Add all new ABIs to _MULTILIB_FLAGS variable.
   2. Add conditionals appropriate for the new ABIs to the header template in multilib_prepare_wrappers() function (it is important that the #error contains full ABI flag since the substitution relies on it).
   3. Add ABI->USE flag mapping to multilib_prepare_wrappers() function.

Before those changes are committed, they need to be tested and a full pkgcheck scan needs to be done in order to ensure that the new flags do not introduce dependency errors.

Note
If there are no-multilib profiles that inherit from multilib profiles, the multilib changes need to be reversed in them.

Adding new ABIs to existing groups

If a new ABI is to be added to an existing group, the following steps need to be taken:

1. Add the new ABI to the profiles/desc/abi_xxx.desc file.
2. In profiles/base/use.mask
   1. Mask the new abi_xxx_yyy flag.
3. In profiles/arch/* for multilib profiles.
   1. Unmask the new ABI (-abi_xxx_yyy) in the use.mask file.
4. In the eclass/multilib-build.eclass:
   1. Add the new ABI to the _MULTILIB_FLAGS variable.
   2. Add conditional appropriate for the new ABI to the header template in multilib_prepare_wrappers() function (it is important that the #error contains full ABI flag since the substitution relies on it).
   3. Add ABI->USE flag mapping to multilib_prepare_wrappers() function.

Before those changes are committed, they need to be tested and a full pkgcheck scan needs to be done in order to ensure that the new flag does not introduce dependency errors.