GUILE.ECLASS

Section: eclass-manpages (5)
Updated: Nov 2024
Index Return to Main Contents

NAME

guile.eclass - Utilities for packages multi-implementation Guile packages.

DESCRIPTION

This eclass facilitates building against many Guile implementations, useful for Guile libraries. Each ebuild must set GUILE_COMPAT to a list of versions they support, which will be intersected with GUILE_TARGETS to pick which versions to install. The eclass will generate a GUILE_DEPS based on the configured GUILE_COMPAT, as well as a GUILE_REQUIRED_USE, that the user must use.

If the user of the eclass needs some USE flag on Guile itself, they should provide it via GUILE_REQ_USE.

This ebuild provides multibuild functionality. Use guile_foreach_impl to run a given command for each enabled Guile version. The command provided will be ran in a modified environment, see the description of that function for more details.

This package provides some stage functions written assuming a conventional GNU Build System-based Guile library and may or may not work.

For each Guile target, a Guile library should have at least compiled .go files in the ccache or %site-ccache-dir. It must also have corresponding sources installed in %site-dir.

If your package has some steps that should only happen for one implementation (e.g. installing a program), you can utilize guile_for_best_impl.

Due to http://debbugs.gnu.org/cgi/bugreport.cgi?bug=38112, Guile packages ought to bump their sources before building. To this end, the src_prepare this eclass provides will call guile_bump_sources of the guile-utils eclass.

When installing, the packages using this eclass ought to use guile_foreach_impl and its SLOTTED_{,E}D, followed by merging roots via guile_merge_roots and unstripping ccache objects via guile_unstrip_ccache. See descriptions of those functions for details.

Ebuild authors, please pay attention for potential conflicts between slots. As an example, dev-scheme/guile-lib installs a pkg-config file that depends on the Guile version it is installed for. This is not acceptable, as it means revdeps will only ever see the version of the file for the best Guile implementation in GUILE_TARGETS.

SUPPORTED EAPIS

TRANSITIVELY PROVIDED ECLASSES

guile-utils

EXAMPLE

The following example demonstrates a simple package relying entirely on the setup of this eclass. For each enabled, compatible target, the ebuild will bump sources (see description), and run the default configure, compile and test stages (per PMS, meaning GNU Build System), and an install stage modified such that it installs each variant into SLOTTED_D followed by merging roots and unstripping.

EAPI=8

GUILE_COMPAT=( 2-2 3-0 )
inherit guile

DESCRIPTION="iCalendar/vCard parser for GNU Guile"
HOMEPAGE="https://github.com/artyom-poptsov/guile-ics"
SRC_URI="https://github.com/artyom-poptsov/${PN}/releases/download/v${PV}/${P}.tar.gz"

LICENSE="GPL-3+"
SLOT="0"
KEYWORDS="~amd64"
REQUIRED_USE="${GUILE_REQUIRED_USE}"

RDEPEND="
        ${GUILE_DEPS}
        dev-scheme/guile-smc[${GUILE_USEDEP}]
"
DEPEND="${RDEPEND}"

FUNCTIONS

guile_pkg_setup

Sets up eclass-internal variables for this build.

guile_copy_sources

Create a single copy of the package sources for each selected Guile implementation.

SLOTTED_D

In functions ran by guile_foreach_impl, this variable is set to a new ${D} value that the variant being installed should use.

SLOTTED_ED

In functions ran by guile_foreach_impl, this variable is set to a new ${ED} value that the variant being installed should use. It is equivalent to "${SLOTTED_D%/}${EPREFIX}/".

ECONF_SOURCE

In functions ran by guile_foreach_impl, this variable is set to ${S}, for convenience.

PKG_CONFIG_PATH

In functions ran by guile_foreach_impl, PKG_CONFIG_PATH is filtered to contain only the current ${MULTIBUILD_VARIANT}.

BUILD_DIR

In functions ran by guile_foreach_impl, this variable is set to a newly-generated build directory for this variant.

guile_foreach_impl <command> [<argv>...]

Runs the given command for each of the selected Guile implementations.

The function will return 0 status if all invocations succeed. Otherwise, the return code from first failing invocation will be returned.

Each invocation will have PKG_CONFIG_DIR altered to contain only one Guile implementation, as well as a SLOTTED_D, SLOTTED_ED for installation purposes, and a new BUILD_DIR, in which the wrapped function will be executed, with a pre-configured ECONF_SOURCE. A temporary program called 'guile-config' is generated and inserted into the PATH.

Also automatically exported are GUILE, GUILD, and GUILESNARF - see guile_export for details - as well as GUILE_CURRENT_VERSION and GUILE_EFFECTIVE_VERSION, which are set to the same value (the current version).

This combination should cover Guile detection of a large amount of packages out of the box.

guile_merge_roots

Merges install roots from all slots, diagnosing conflicts.

guile_for_best_impl

Runs the passed command once, for the best installed Guile implementation.

guile_src_prepare

Bumps SCM sources runs the default src_prepare and bumps all *.scm files. See guile_bump_sources of guile-utils.eclass.

guile_src_configure

Runs the default src_configure for each selected variant target.

guile_src_compile

Runs the default src_compile for each selected variant target.

guile_src_test

Runs the default src_test phase for each implementation.

guile_src_install

Runs the an imitation of the default src_install that does the right thing for a GNU Build System based Guile package, for each selected variant target. Merges roots after completing the installs.

ECLASS VARIABLES

GUILE_USEDEP (GENERATED BY ECLASS)

USE dependency string that can be applied to Guile multi-implementation dependencies.

GUILE_COMPAT (REQUIRED) (SET BEFORE INHERIT)

List of acceptable versions of Guile. For instance, setting this variable like below will allow the package to be built against both Guile 2.2 or 3.0:

GUILE_COMPAT=( 2-2 3-0 )

Please keep in ascending order.

AUTHORS

Author: Arsen Arsenović <[email protected]>
Inspired by prior work in the Gentoo Python ecosystem.

MAINTAINERS

Gentoo Scheme project <[email protected]>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

guile.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, November 25, 2024