Re: [gentoo-dev] [RFC] sword-module.eclass: update, extend, increment revision

[Marek Szuba]

On 2020-07-26 21:19, Michał Górny wrote:

> Please use git-send-email, so that we can reply in context without
> jumping through hoops.

Funny, last time I used git-send-email to post a diff introducing a new
revision of a file (it was virtual/opencl, IIRC) I got told it was too
difficult to follow the changes that way and a plain diff would have
been more useful.

Anyway, here is the same diff but inline. I'll also repeat the summary
of proposed changes here so that it isn't necessary to switch to a
different message to see it:
 - add eclassdoc blocks;
 - add the optional variable SWORD_MINIMUM_VERSION to specify the lowest
version of app-text/sword supported by the module at hand;
 - check if SWORD_MODULE is set and not null, and die otherwise;
 - change the default SRC_URI from mirror://gentoo to my Web space on
dev.gentoo.org;
 - remove redundant declarations of HOMEPAGE and IUSE;
 - app-arch/unzip is now in BDEPEND rather than DEPEND;
 - as a consequence of the above, enforce the use of EAPI-7 in ebuilds
inheriting this eclass;
 - remove redundant references to ${S} from doins() calls.

* * *

--- eclass/sword-module.eclass
+++ eclass/sword-module-r1.eclass
@@ -1,33 +1,100 @@
 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
+# @ECLASS: sword-module-r1.eclass
+# @MAINTAINER:
+# Marek Szuba <marecki@g.o>
+# @SUPPORTED_EAPIS: 7
+# @BLURB: Simplify installations of SWORD modules
+# @DESCRIPTION:
+# This eclass provides dependencies, ebuild environment and the src_install
+# function common to all app-text/sword modules published by the SWORD Project.
 #
-# eclass to simplify installation of Sword modules
-# Bugs to marecki@g.o
+# Note that while all SWORD modules which do not require prior registration
+# to unlock can easily be downloaded from the upstream Web site, as of
+# 2020-07-26 all the files available at
+# https://crosswire.org/ftpmirror/pub/sword/packages/rawzip/
+# are unversioned and it is necessary to look at respective module pages
+# in order to see when they have last been updated. Therefore, maintainers
+# must rename module files to include the version number and host them
+# somewhere to avoid breaking digests when new versions are released.
 #
+# @EXAMPLE:
+# Typical ebuild using sword-module-r1.eclass:
+#
+# @CODE
+# EAPI=7
+#
+# SWORD_MODULE="Personal"
+# SWORD_MINIMUM_VERSION="1.5.1a"
+#
+# inherit sword-module-r1
+#
+# DESCRIPTION="SWORD module for storing one's own commentary"
+# HOMEPAGE="https://crosswire.org/sword/modules/ModInfo.jsp?modName=Personal"
+# LICENSE="public-domain"
+# KEYWORDS="~amd64"
+#
+# @CODE
 
-HOMEPAGE="http://www.crosswire.org/sword/modules/"
+case ${EAPI:-0} in
+	0|1|2|3|4|5|6)
+		die "Unsupported EAPI=${EAPI} (too old) for ${ECLASS}"
+		;;
+	7)
+		;;
+	*)
+		die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
+		;;
+esac
+
+# @ECLASS-VARIABLE: SWORD_MODULE
+# @DEFAULT_UNSET
+# @PRE_INHERIT
+# @REQUIRED
+# @DESCRIPTION:
+# Name of the module as used by the SWORD Project. Case-sensitive.
+# Needs to be set before the inherit line.
+
+if [[ ! ${SWORD_MODULE} ]]; then
+	die 'SWORD_MODULE not declared or null'
+fi
+
+# @ECLASS-VARIABLE: SWORD_MINIMUM_VERSION
+# @DEFAULT_UNSET
+# @PRE_INHERIT
+# @DESCRIPTION:
+# If set to a non-null value, specifies the minimum version of app-text/sword
+# the module requires. This will be included in RDEPEND. If null or unset,
+# the dependency will be unversioned.
+# Needs to be set before the inherit line.
 
-# Sword packages are generally released as FooBar.zip in their 'rawzip' form
-# The files are also unversioned, so the packager will need to rename the
-# original file to something else and host it somewhere to avoid breaking
-# the digest when new versions are released.
+EXPORT_FUNCTIONS src_install
 
-SRC_URI="mirror://gentoo/${SWORD_MODULE}-${PV}.zip"
+# Default location of versioned files. In general this is obviously
+# maintainer-specific, then again all the 133 modules present in the tree
+# as of mid-July 2020 are maintained by the same person.
+SRC_URI="https://dev.gentoo.org/~marecki/dists/sword-modules/${SWORD_MODULE}-${PV}.zip"
 
 SLOT="0"
-IUSE=""
 
+# Module archives contain no top-level directory.
 S="${WORKDIR}"
 
-RDEPEND="app-text/sword"
-DEPEND="app-arch/unzip"
-
-sword-module_src_install() {
+if [[ ${SWORD_MINIMUM_VERSION} ]]; then
+	RDEPEND=">=app-text/sword-${SWORD_MINIMUM_VERSION}"
+else
+	RDEPEND="app-text/sword"
+fi
+
+BDEPEND="app-arch/unzip"
+
+# @FUNCTION: sword-module-r1_src_install
+# @DESCRIPTION:
+# Install all the module files into directories expected by app-text/sword.
+sword-module-r1_src_install() {
 	insinto /usr/share/sword/modules
-	doins -r "${S}"/modules/*
+	doins -r modules/*
 	insinto /usr/share/sword/mods.d
-	doins "${S}"/mods.d/*
+	doins mods.d/*
 }
-
-EXPORT_FUNCTIONS src_install




-- 
MS