On 21/07/2024 10.26, Ulrich Mueller wrote:
On Tue, 16 Jul 2024, Florian Schmaus wrote:
Notes:
- also show readme contents if FEATURES=nodoc
Good. :)
Thanks for your review.
--- /dev/null
+++ b/eclass/greadme.eclass
@@ -0,0 +1,257 @@
+# Copyright 1999-2024 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+# @ECLASS: greadme.eclass
+# @MAINTAINER:
+# Florian Schmaus
+# @AUTHOR:
+# Author: Florian Schmaus
"Author:" is redundant when there's only a single author.
Applied locally.
+# @SUPPORTED_EAPIS: 8
+# @BLURB: install a doc file, that will be conditionally shown via elog
messages
+# @DESCRIPTION:
+# An eclass for installing a README.gentoo doc file with important
+# information for the user. The content of README.gentoo will shown be
+# via elog messages either on fresh installations or if the contents of
+# the file have changed. Furthermore, the README.gentoo file will be
+# installed under /usr/share/doc/${PF} for later consultation.
+#
+# This eclass was inspired by readme.gentoo-r1.eclass. The main
+# differences are as follows. Firstly, it only displays the doc file
+# contents if they have changed (unless GREADME_SHOW is set).
+# Secondly, it provides a convenient API to install the doc file via
+# stdin.
+#
+# @CODE
+# inherit greadme
+#
+# src_install() {
+# ...
+# greadme_stdin <<-EOF
+# This is the content of the created readme doc file.
+# EOF
+# ...
+# if use foo; then
+# greadme_stdin --append <<-EOF
+# This is conditional readme content, based on USE=foo.
+# EOF
+# fi
+# }
+# @CODE
+#
+# If the ebuild overrides the default pkg_preinst or respectively
+# pkg_postinst, then it must call greadme_pkg_preinst and
+# greadme_pkg_postinst explicitly.
+
+if [[ -z ${_GREADME_ECLASS} ]]; then
+_GREADME_ECLASS=1
+
+case ${EAPI} in
+ 8) ;;
+ *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
+esac
+
+_GREADME_FILENAME="README.gentoo"
+_GREADME_TMP_FILE="${T}/${_GREADME_FILENAME}"
+_GREADME_REL_PATH="/usr/share/doc/${PF}/${_GREADME_FILENAME}"
These are internal variables and they're never set to anything else.
I also think that it is unlikely that "README.gentoo" would ever be
changed to anything else.
IMHO hardcoding it would improve readability. ("README.gentoo" makes it
immediately clear what is happening, while with ${_GREADME_FILENAME} one
must look up what the variable is.)
Applied locally.
+# @ECLASS_VARIABLE: GREADME_SHOW
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# If set to "yes" then unconditionally show the contents of the readme
+# file in pkg_postinst via elog. If set to "no", then do not show the
+# contents of the readme file, even if they have changed.
+
+# @ECLASS_VARIABLE: GREADME_AUTOFORMATTING_DISABLED
It is an input variable, so make it a (grammatical) command, e.g.
GREADME_DISABLE_AUTOFORMAT?
Applied locally.
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# If non-empty, the readme file will not be automatically formatted.
+
+# @FUNCTION: greadme_stdin
+# @USAGE: [--append]
+# @DESCRIPTION:
+# Create the readme doc via stdin. You can use --append to append to an
+# existing readme doc.
+greadme_stdin() {
+ debug-print-function ${FUNCNAME} "${@}"
+
+ local append
+ while [[ -n ${1} ]] && [[ ${1} == --* ]]; do
+ case ${1} in
+ --append)
+ append=1
+ shift
+ ;;
+ esac
+ done
Simply check for either no option, or one option that must be exactly
"--append". Everything else should be an error, i.e. not silent ignoring
of parameters. Something like this:
[[ ${1} = --append ]] && { append=1; shift; }
[[ $# -eq 0 ]] || die "${FUNCNAME[0]}: Bad parameters: $*"
Applied locally.
+
+ if [[ -n ${append} ]]; then
+ if [[ ! -f ${_GREADME_TMP_FILE} ]]; then
+ die "Gentoo README does not exist when trying to append to
it"
+ fi
+
+ cat >> "${_GREADME_TMP_FILE}" || die
+ else
+ cat > "${_GREADME_TMP_FILE}" || die
+ fi
+
+ _greadme_install_doc
+}
+
+# @FUNCTION: greadme_file
+# @USAGE:
+# @DESCRIPTION:
+# Installs the provided file as readme doc.
+greadme_file() {
+ debug-print-function ${FUNCNAME} "${@}"
+
+ local input_doc_file="${1}"
+ if [[ -z ${input_doc_file} ]]; then
+ die "No file specified"
+ fi
+
+ cp "${input_doc_file}" "${_GREADME_TMP_FILE}" || die
+
+ _greadme_install_doc
+}
+
+# @FUNCTION: _greadme_install_doc
+# @INTERNAL
+# @DESCRIPTION:
+# Installs the readme file from the temp directory into the image.
+_greadme_install_doc() {
+ debug-print-function ${FUNCNAME} "${@}"
+
+ local greadme="${_GREADME_TMP_FILE}"
+ if [[ ! "${GREADME_AUTOFORMATTING_DISABLED}" ]]; then
Quotation marks are not necessary here.
Applied locally.
+
