Multilib/multilib-minimal

From Gentoo Wiki
Jump to:navigation Jump to:search

The multilib-minimal is the eclass that is suggested to be used for most of the packages supporting multilib. It provides a friendly, sub-phase function-based API to build packages. It is built on top of multilib-build eclass and therefore all common APIs are provided.

Description

The multilib-minimal eclass is built around the concept of sub-phase functions. It exports each of the following phase functions, and implements it in terms of sub-phase functions:

Phase Per-ABI sub-phase Common sub-phase
src_configure multilib_src_configure -
src_compile multilib_src_compile -
src_test multilib_src_test -
src_install multilib_src_install multilib_src_install_all

Each of the per-ABI sub-phase functions is executed for each enabled multilib ABI, in a dedicated build directory (that is different from ${S}), with an environment set up for building for the particular ABI.

By default, the per-ABI sub-phase performs the same task as the original phase function, e.g. multilib_src_compile calls emake. However, each of those functions can be overriden in ebuild to perform different code. When adding multilib support to existing packages, it is common to start by renaming phase functions to their respective multilib sub-phases.

The additional common sub-phase can be used to perform tasks that are irrelevant to multilib. It is run inside ${S}, and defaults to installing documentation. When overriden in an ebuild, einstalldocs can be used to reproduce the original behavior.

Please note that the ebuild needs to explicitly ensure the correctness of commands run in build directory. This usually requires either:

  • setting ECONF_SOURCE=${S} for src_configure() when using autotools so that an out-of-source build will be performed,
  • calling multilib_copy_sources in src_prepare() to create separate copies of sources in build directories.

Examples

CODE Verbose example for handling multilib-capable autotools package
inherit eutils multilib-minimal

# ...

multilib_src_configure() {
    local myconf=(
        # flags common to all ABIs
        $(use_enable jpeg)
        $(use_enable png)
        $(use_enable static-libs static)

        # python does not support multilib
        $(multilib_native_use_enable python)
    )

    if ! multilib_is_native_abi; then
        myconf+=(
            # tools are installed for native ABI only, so do not build them twice
            --disable-tools
        )
    fi

    # Enable building out-of-source using sources in ${S}
    ECONF_SOURCE=${S} econf "${myconf[@]}"
}

multilib_src_compile() {
    default

    if multilib_is_native_abi; then
        # build some custom docs, for native ABI since once is enough
        emake doc
    fi
}

multilib_src_install() {
    # not 1:1 with the eclass default but acceptable
    default

    if multilib_is_native_abi; then
        # install the docs we just built. while technically this could go
        # into multilib_src_install_all(), the docs were placed in BUILD_DIR
        # so it's better to place it here.
        dohtml -r doc/.
    fi    
}

multilib_src_install_all() {
    einstalldocs

    # strip .la files once for all ABIs
    prune_libtool_files --all

    # some common rules that are independent of multilib
    domenu "${FILESDIR}"/foo.desktop
}