Multilib/Adding new ABIs

This article aims to outline 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), 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 profiles/base/make.defaults:
 * 3) add ABI_XXX (an uppercase variant of ABI group name) into USE_EXPAND,
 * 4) add ABI_XXX into USE_EXPAND_HIDDEN,
 * 5) in profiles/base/use.mask:
 * 6) mask all abi_xxx_* flags,
 * 7) in profiles/arch/* for arches involved in the multilib:
 * 8) set the default value for ABI_XXX in make.defaults,
 * 9) add the native ABI entry (abi_xxx_yyy) to use.force,
 * 10) unmask the native ABI (-abi_xxx_yyy) in use.mask,
 * 11) set the native ABI as only ABI in IUSE_IMPLICIT in make.conf,
 * 12) in profiles/arch/* for multilib profiles of the above arches:
 * 13) add -ABI_XXX to USE_EXPAND_HIDDEN in make.defaults to make the flags visible,
 * 14) unmask other supported ABIs (-abi_xxx_yyy) in use.mask,
 * 15) in eclass/multilib-build.eclass:
 * 16) add all new ABIs to _MULTILIB_FLAGS,
 * 17) 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 that),
 * 18) add ABI->USE flag mapping to multilib_prepare_wrappers function.

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

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 profiles/desc/abi_xxx.desc,
 * 2) in profiles/base/use.mask:
 * 3) mask the new abi_xxx_yyy flag,
 * 4) in profiles/arch/* for multilib profiles:
 * 5) unmask the new ABI (-abi_xxx_yyy) in use.mask,
 * 6) in eclass/multilib-build.eclass:
 * 7) add the new ABI to _MULTILIB_FLAGS,
 * 8) 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 that),
 * 9) add ABI->USE flag mapping to multilib_prepare_wrappers function.

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