Portage Dynamic Slot

From Funtoo
Jump to navigation Jump to search

Portage-2.3.1 in the experimental tree contains support for dynamic slots.

   Note

If you plan to use dynamic slots, please read this page in its entirety, especially the Requirements below, to ensure you are using dynamic slots correctly.

Traditional SLOT

Historically, Portage has supported SLOTs, which are defined statically in the ebuild and allow certain package versions to be installed alongside other versions of the same package. For example, libpng-1.4.2 could have a SLOT of "1.4" while libpng-1.5 could have a SLOT of "1.5". This indicates that these ebuilds can be installed alongside each other.

It has been the policy of Gentoo Linux to only allow SLOT to be set statically in the ebuild, and not vary (via code) within the ebuild. Traditionally, within a single ebuild it must always be the same, non-variable value.

Dynamic SLOT

Funtoo dynamic slot functionality changes this policy and allows SLOT to vary. This is useful for custom builds of an application whose paths are defined by an external variable passed in to Portage.

Here is an example of how dynamic slot works in an ebuild, and shows how it is intended to be used -- to allow custom versions of ebuilds to be built alongside non-custom versions:

SLOT="$PV"
IUSE="custom"

pkg_setup() {
    if use custom && has "${EBUILD_PHASE:none}" "unpack" "prepare" "compile" "install"; then
        if [ -n "$CUSTOM_CONFIG" ]; then
            SLOT="$PV-${CUSTOM_CONFIG##*/}"
        else
            die "Please define CUSTOM_CONFIG to use 'custom' USE variable"
        fi
    fi
}

src_compile() {
    econf --prefix=/usr/$SLOT --special_options=$CUSTOM_CONFIG || die
    emake || die
}

src_install() {
    emake install DESTDIR="$D" || die
    insinto /usr/$SLOT
    doins foo
}

Above, the ebuild has a USE flag called "custom". When it is set, the ebuild looks for a variable called CUSTOM_CONFIG in the environment (this would typically be exported into the current shell.) The name of the CUSTOM_CONFIG file is used to modify SLOT, so that if CUSTOM_CONFIG pointed to /foo/bar/oni, and the ebuild version was 1.0-r1, then SLOT would be set to 1.0-oni.

Also note that this ebuild takes care to ensure that the ebuild modifies all paths so that the files in this ebuild will not conflict with the paths in other versions of this ebuild. This is how dynamic slot is intended to be used. I plan to use this functionality in Funtoo Linux to support custom kernel ebuilds.

Requirements

  • A default SLOT value must be defined in the main body of the ebuild, as normal, and just like a traditional SLOT, it must not vary within an individual ebuild. This value is cached in the metadata.
  • pkg_setup can be used to override SLOT but this should not be the default behavior. It should be enabled via USE variable.
  • pkg_setup should override the SLOT only in certain required phases that reference the dynamic SLOT. Use EBUILD_PHASE for this, as in the example.
  • Ensure that files in your ebuild are installed to different locations so that they do not conflict with any other installed versions of this ebuild.
  • Typically, you would not use dynamic slot for standard ebuilds that other ebuilds depend on. It is generally intended for "custom" versions of ebuilds that need to vary based on local user settings. However, your ebuild can build in a "standard" mode without dynamic slot enabled via USE, and build in a "custom" mode when dynamic slot is enabled.

Implementation

Dynamic Slot functionality has been implemented by making the following changes to Portage: