Completed eblit.eclass implementation v2

eblit.eclass (text/plain), 5.11 KB, created by Joshua Kinard on 2017-03-17 18:02:53 UTC

# Copyright 1999-2017 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2

# Description: eblit.eclass contains the core functions for creating "eblits".
#              eblits are a place to store common code shared among multiple
#              ebuilds within a specific package directory.
#
# Original Eblit Author: Mike Frysinger <[e-mail]>
# Eblit Eclass Author: Joshua Kinard <[e-mail]>
# Maintainer: [e-mail]

# Implementation Note: Since code in an eblit is used by multiple ebuilds,
# PLEASE revbump the eblit files when changes are made.  Then update each
# ebuild that needs to use the new eblit version.  Remove old eblit versions
# when there are no more consumers.  This makes it a lot easier to debug
# problems with the shared code within an eblit, as well as the affected
# ebuilds.

# To create an eblit:
#  1. Create an "eblits" subdirectory under the specific package directory
#     that you intend to use eblits in, if one does not already exist.
#  2. Create a new eblit file under the "eblits" directory that uses the
#     following formula: [a-z0-9_]-v[0-9]+.eblit
#  3. Add any eblit code by following #4 in the below documentation.
#  4. Update ebuilds following #2, #3, and #5 below.
#
# Try to keep eblits specific to the functions they implement.  E.g., if a
# number of ebuilds have a large, but common src_unpack() function, and it
# is not already provided by an eclass, then add that code to an eblit named
# "src_unpack-vX.eblit", where X is a version number.

# To load and use eblits:
#  1. Inherit the "eblit" eclass (this class).
#  2. Define a new function called "load_eblit_funcs" in the ebuild
#     immediately after any global ebuild variables and use the below example
#     implementation as a guide (the guard variable is required).
#
#         load_eblit_funcs() {
#             # This is a guard variable that is required to prevent eblits
#             # from being sourced during metadata operations.
#             [ -n "${_EBLITS_LOADED}" ] && return
#                 # Use eblit-include to load an eblit so that any functions
#                 # defined within are available for use within the ebuild.
#                 eblit-include foo_stuff v1  # ${EBLITSDIR}/foo_stuff-v1.eblit
#
#                 # Use eblit-pkg to source any eblits that handle pkg_*
#                 # functions so they are eval'ed like with eblit-include AND
#                 # included in any binpkgs.
#                 eblit-pkg foo_setup v1  # ${EBLITSDIR}/foo_setup-v1.eblit
#                 eblit-pkg foo_postinst v1  # ${EBLITSDIR}/foo_postinst-v1.eblit
#
#                 # Define the guard variable, as our eblit loading is done.
#                 _EBLITS_LOADED=1
#         }
#
#  3. Next, define pkg_setup and call 'load_eblit_funcs':
#
#         pkg_setup() {
#             load_eblit_funcs
#             pkg_setup  # loaded from foo_setup-v1.eblit
#         }
#
#  4. To implement a specific ebuild phase function in an eblit, create an
#     override using the following format:
#
#         eblit-PKGNAME-FUNC() {
#             ### code ###
#         }
#
#         Where:
#           - PKGNAME is the name of the package.
#           - FUNC is the ebuild phase function implemented by the eblit.
#
#  5. In an ebuild that uses a function implemented in an eblit, create
#     an appropriately-named stub function and invoke the eblit copy by
#     calling eblit-run:
#
#         src_unpack() {
#             eblit-run foo_unpack v1  # ${EBLITSDIR}/foo_unpack-v1.eblit
#         }


# XXX: This is a hack for now until we submit a patch to PMS and the various
#      package managers to implement ${EBLITSDIR}.
EBLITSDIR="${FILESDIR%/files}/eblits"

# eblit-core
# Usage: <function> [version]
# Main eblit engine
eblit-core() {
	local e v func=$1 ver=$2
	for v in ${ver:+-}${ver} -${PVR} -${PV} "" ; do
		e="${EBLITSDIR}/${func}${v}.eblit"
		if [[ -e ${e} ]] ; then
			. "${e}"
			[[ ${func} == pkg_* ]] && eval "${func}() { eblit-run ${func} ${ver} ; }"
			return 0
		fi
	done
	return 1
}

# eblit-include
# Usage: [--skip] <function> [version]
# Includes an "eblit" -- a chunk of common code among ebuilds in a given
# package so that its functions can be sourced and utilized within the
# ebuild.
eblit-include() {
	local skipable=false r=0
	[[ $1 == "--skip" ]] && skipable=true && shift
	[[ $1 == pkg_* ]] && skipable=true

	[[ -z $1 ]] && die "Usage: eblit-include <function> [version]"
	eblit-core $1 $2
	r="$?"
	${skipable} && return 0
	[[ "$r" -gt "0" ]] && die "Could not locate requested eblit '$1' in ${EBLITSDIR}/"
}

# eblit-run-maybe
# Usage: <function>
# Runs a function if it is defined in an eblit
eblit-run-maybe() {
	[[ $(type -t "$@") == "function" ]] && "$@"
}

# eblit-run
# Usage: <function> [version]
# Runs a function defined in an eblit
eblit-run() {
	eblit-include --skip common "${*:2}"
	eblit-include "$@"
	eblit-run-maybe eblit-$1-pre
	eblit-${PN}-$1
	eblit-run-maybe eblit-$1-post
}

# eblit-pkg
# Usage: <phase> [version]
# Runs the pkg_* functions AND evals them so they're included in the binpkgs
eblit-pkg() {
	[[ -z $1 ]] && die "Usage: eblit-pkg <phase> [version]"
	eblit-core pkg_$1 $2
}