Re: [gentoo-dev] [PATCH v2 1/3] greadme.eclass: new eclass

[David Seifert <soap@gentoo.org>]

On Tue, 2024-01-09 at 09:39 +0100, Florian Schmaus wrote:
> This new eclass is similar to readme.gentoo-r1.eclass. The main
> differences are as follows. Firstly, it also displays the doc file
> contents if they have changed. Secondly, it provides a convenient API
> to
> install the doc file via stdin.
> 
> Furthermore, this eclass dos not store the doc file's contents in an
> environment variable, which helps to keep the environment size of
> ebuilds using the eclass small.
> 
> Signed-off-by: Florian Schmaus <flow@gentoo.org>
> ---
>  eclass/greadme.eclass | 307
> ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 307 insertions(+)
>  create mode 100644 eclass/greadme.eclass
> 
> diff --git a/eclass/greadme.eclass b/eclass/greadme.eclass
> new file mode 100644
> index 000000000000..25e0210406c1
> --- /dev/null
> +++ b/eclass/greadme.eclass
> @@ -0,0 +1,307 @@
> +# Copyright 1999-2024 Gentoo Authors
> +# Distributed under the terms of the GNU General Public License v2
> +
> +# @ECLASS: greadme.eclass
> +# @MAINTAINER:
> +# Florian Schmaus <flow@gentoo.org>
> +# @AUTHOR:
> +# Author: Florian Schmaus <flow@gentoo.org>
> +# @SUPPORTED_EAPIS: 6 7 8
> +# @BLURB: install a doc file, that will be conditionally shown via
> elog messages
> +# @DESCRIPTION:
> +# An eclass for installing a README.gentoo doc file recording tips
> +# shown via elog messages.  With this eclass, those elog messages
> will only be
> +# shown at first package installation or if the contents of the file
> have changed.
> +# Furthermore, a file for later reviewing will be installed under
> +# /usr/share/doc/${PF}
> +#
> +# This eclass is similar to readme.gentoo-r1.eclass.  The main
> +# differences are as follows.  Firstly, it also displays the doc file
> +# contents if they have changed.  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 --apend <<-EOF
> +#     This is conditional readme content, based on USE=foo.
> +#     EOF
> +#   fi
> +# }
> +# @CODE
> +#
> +# You must call greadme_pkg_preinst and greadme_pkg_postinst
> explicitly, if
> +# you override the default pkg_preinst or respectively pkg_postinst.
> +#
> +# TODO:
> +# - Should this be named README.Distribution instead of
> README.Gentoo?
> +#   Would that make things easier for Gentoo derivates?
> +#   Similary, (g → d)readme, (G → D)README?
> +# - Incooperate changes into readme.gentoo-r1.elcass?
> +# - Compressing the readme doc file is probably fragile, as it is not
> +#   guaranteed that the required binaries for decompression are
> installed
> +#   in pkg_preinst/pkg_postinst. Note that it is even possible that
> two
> +#   different compression algorithms are used, in case of binpkgs.
> +
> +if [[ -z ${_README_GENTOO_ECLASS} ]]; then
> +_README_GENTOO_ECLASS=1
> +
> +case ${EAPI} in
> +	6|7|8) ;;
> +	*) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
> +esac
> +
> +if [[ ${_GREADME_COMPRESS} ]]; then
> +	inherit unpacker
> +fi
> +
> +_GREADME_FILENAME="README.gentoo"
> +_GREADME_TMP_FILE="${T}/${_GREADME_FILENAME}"
> +_GREADME_REL_PATH="usr/share/doc/${PF}/${_GREADME_FILENAME}"
> +
> +# @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=false
> +	while [[ -n ${1} ]] && [[ ${1} =~ --* ]]; do
> +		case ${1} in
> +			--append)
> +				append=true
> +				shift
> +				;;
> +		esac
> +	done
> +
> +	if $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
> +		if [[ -f "${_GREADME_TMP_FILE}" ]]; then
> +			die "Gentoo README already exists while
> trying to create it"
> +		fi
> +
> +		cat > "${_GREADME_TMP_FILE}" || die
> +	fi
> +
> +	_greadme_install_doc
> +}
> +
> +# @FUNCTION: greadme_file
> +# @USAGE: <file>
> +# @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
> +
> +	if [[ -f "${_GREADME_TMP_FILE}" ]]; then
> +		die "Gentoo README already exists"
> +	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} "${@}"
> +
> +	if [[ ! -f "${_GREADME_TMP_FILE}" ]]; then
> +		die "Gentoo README does not exist"
> +	fi
> +
> +	if ! [[ ${_GREADME_COMPRESS} ]]; then
> +		docompress -x "${_GREADME_REL_PATH}"
> +	fi
> +
> +	( # subshell to avoid pollution of calling environment
> +		docinto .
> +		dodoc "${_GREADME_TMP_FILE}"
> +	) || die
> +
> +}
> +
> +# @FUNCTION: greadme_pkg_preinst
> +# @DESCRIPTION:
> +# Performs checks like comparing the readme doc from the image with a
> +# potentially existing one in the live system.
> +greadme_pkg_preinst() {
> +	local image_doc_file="${ED}/${_GREADME_REL_PATH}"
> +
> +	if [[ ${_GREADME_COMPRESS} ]]; then
> +		local greadme_tmpdir="${T}/greadme"
> +
> +		mkdir -p "${greadme_tmpdir}/image" || die
> +
> +		local image_doc_files=( $(ls -1 ${image_doc_file}*) )
> +		case ${#image_doc_files[@]} in
> +			0)
> +				die "No Gentoo README found in image"
> +				;;
> +			1)
> +				image_doc_file="${image_doc_files[0]}
> "
> +				;;
> +			*)
> +				die "unpexpected number of Gentoo
> README files found"
> +				;;
> +		esac
> +
> +		pushd "${T}/greadme/image" > /dev/null
> +		local image_doc_file_basename="$(basename
> "${image_doc_file}")"
> +		if [[ "${image_doc_file_basename}" ==
> "${_GREADME_FILENAME}" ]]; then
> +			cp "${image_doc_file}" . || die
> +		else
> +			nonfatal unpacker "${image_doc_file}"
> +			if [[ $? -gt 0 ]]; then
> +				# We failed to unpack the readme doc
> from the
> +				# image, therefore, we can't show it
> (unless we
> +				# would save it's content in a env
> variable like
> +				# gentoo.readme-r1 does).
> +				_GREADME_SHOW=""
> +				return
> +			fi
> +		fi
> +		popd > /dev/null
> +	fi
> +
> +	if [[ -z ${REPLACING_VERSIONS} ]]; then
> +		_GREADME_SHOW="fresh-install"
> +		return
> +	fi
> +
> +	check_live_doc_file() {
> +		local cur_pvr=$1
> +		local live_doc_file="${EROOT}/usr/share/doc/${PN}-
> ${cur_pvr}/${_GREADME_FILENAME}"
> +
> +		if [[ ${_GREADME_COMPRESS} ]]; then
> +			local live_doc_files=( $(ls -1
> ${live_doc_file}*) )
> +			case ${#live_doc_files[@]} in
> +				0)
> +					_GREADME_SHOW="no-current-
> greadme"
> +					return
> +					;;
> +				1)
> +					live_doc_file="${live_doc_fil
> es[0]}"
> +					;;
> +				*)
> +					die "unpexpected number of
> Gentoo README files found"
> +					;;
> +			esac
> +
> +			if [[ -d "${greadme_tmpdir}/live" ]]; then
> +				rm -rf "${greadme_tmpdir}"/live/* ||
> die
> +			else
> +				mkdir "${T}/greadme/live"
> +			fi
> +
> +			pushd "${T}/greadme/live" > /dev/null
> +			local live_doc_file_basename="$(basename
> "${live_doc_file}")"
> +			if [[ "${live_doc_file_basename}" ==
> "${_GREADME_FILENAME}" ]]; then
> +				cp "${live_doc_file}" .
> +			else
> +				nonfatal unpacker "${live_doc_file}"
> +				if [[ $? -gt 0 ]]; then
> +					# We failed to unpack the
> live readme doc, fallback
> +					# to show the new readme
> contents.
> +					_GREADME_SHOW="failed-to-
> unpack-live-readme-doc"
> +					return
> +				fi
> +			fi
> +			popd > /dev/null
> +
> +			live_doc_file="${T}/greadme/live/${_GREADME_F
> ILENAME}"
> +			image_doc_file="${T}/greadme/image/${_GREADME
> _FILENAME}"
> +			# Store the unpacked greadme in a global
> variable so that it can
> +			# be used in greadme_pkg_postinst.
> +			_GREADME_UNPACKED="${image_doc_file}"
> +		else
> +			if [[ ! -f ${live_doc_file} ]]; then
> +				_GREADME_SHOW="no-current-greadme"
> +				return
> +			fi
> +		fi
> +
> +		cmp -s "${live_doc_file}" "${image_doc_file}"
> +		local ret=$?
> +		case ${ret} in
> +			0)
> +				_GREADME_SHOW=""
> +				;;
> +			1)
> +				_GREADME_SHOW="content-differs"
> +				;;
> +			*)
> +				die "cmp failed with ${ret}"
> +				;;
> +		esac
> +	}
> +
> +	local replaced_version
> +	for replaced_version in ${REPLACING_VERSIONS}; do
> +		check_live_doc_file ${replaced_version}
> +		if [[ -n ${_GREADME_SHOW} ]]; then
> +			break
> +		fi
> +	done
> +}
> +
> +# @FUNCTION: greadme_pkg_postinst
> +# @DESCRIPTION:
> +# Conditionally shows the contents of the readme doc via elog.
> +greadme_pkg_postinst() {
> +	debug-print-function ${FUNCNAME} "${@}"
> +
> +	if [[ ! -v _GREADME_SHOW ]]; then
> +		die "_GREADME_SHOW not set. Did you call
> greadme_pkg_preinst?"
> +	fi
> +
> +	if [[ -z "${_GREADME_SHOW}" ]]; then
> +		# If _GREADME_SHOW is empty, then there is no reason
> to show the contents.
> +		return
> +	fi
> +
> +	local greadme_path
> +	if [[ ${_GREADME_COMPRESS} ]]; then
> +		if [[ -z ${_GREADME_UNPACKED} ]]; then
> +			# We failed to decompress the readme doc from
> the image.
> +			return
> +		fi
> +		greadme_path="${_GREADME_UNPACKED}"
> +	else
> +		greadme_path="${EROOT}/${_GREADME_REL_PATH}"
> +	fi
> +
> +	local line
> +	while read -r line; do elog "${line}"; done <
> "${greadme_path}"
> +	elog ""
> +	elog "(Note: Above message is only printed the first time
> package is"
> +	elog "installed or if the the message changed. Please look
> at"
> +	elog "${EPREFIX}/${_GREADME_REL_PATH} for future reference)"
> +}
> +
> +EXPORT_FUNCTIONS pkg_preinst pkg_postinst
> +
> +fi

Sorry, but this is definitely too much complexity for installing a
README file. As is, I will block merging this to the tree.