[gentoo-dev] [PATCH v2 2/3] add UNPACKER_NO_BANNER variable

[Florian Schmaus <flow@gentoo.org>]

Signed-off-by: Florian Schmaus <flow@gentoo.org>
---
 eclass/0000-cover-letter.patch              |  49 ++++
 eclass/0001-greadme.eclass-new-eclass.patch | 305 ++++++++++++++++++++
 eclass/unpacker.eclass                      |   7 +
 3 files changed, 361 insertions(+)
 create mode 100644 eclass/0000-cover-letter.patch
 create mode 100644 eclass/0001-greadme.eclass-new-eclass.patch

diff --git a/eclass/0000-cover-letter.patch b/eclass/0000-cover-letter.patch
new file mode 100644
index 000000000000..2e162d419a44
--- /dev/null
+++ b/eclass/0000-cover-letter.patch
@@ -0,0 +1,49 @@
+From edff06160e33b361c9d6a7e273fc7808337c4518 Mon Sep 17 00:00:00 2001
+From: Florian Schmaus <flow@gentoo.org>
+Date: Sat, 6 Jan 2024 17:44:44 +0100
+Subject: [PATCH 0/1] [RFC] greadme.eclass
+
+I really like the functionality of readme.gentoo-r1.eclass, as it
+allows to communicate Gentoo-specific information about a package to
+the user. Especially as it improves the signal-to-noise ratio of
+messages arriving to our users.
+
+However, readme.gentoo-r1.eclass will only show this information on
+new installs, but not if the information changed. This is a major
+drawback. Furthermore, readme.gentoo-r1.eclass does not provide an API
+to assemble the information via heredoc.
+
+The following patch includes a new eclass named "greadme", that
+addresses those shortcomings of readme.gentoo-r1.eclass and hopefully
+can be seen as a general overhaul.
+
+This is a first draft of the eclass and therefore I'd like to ask for
+feedback.
+
+The greadme.eclass contains some TODO items at the end of its
+@DESCRIPTION.
+
+The main item is doc compression. Right now, greadme.eclass defaults
+to add the readme doc to the compression exclusion list via
+"docompress -x". A mode where the readme doc is compressed, just as
+readme.gentoo-r1.eclass does, can be activated by setting
+_GREADME_COMPRESS. However, I believe this mode is fragile as it can
+not be guaranteed that a binary for the used compression algorithms is
+installed on the host [1].
+
+I believe it is reasonable to simply install the readme doc
+uncompressed, since they are typically only a few lines long. However,
+if anyone can point out a way to achieve the desired functionality with
+a compressed readme doc, then please let me know.
+
+Thanks for reviewing the eclass.
+
+Florian Schmaus (1):
+  greadme.eclass: new eclass
+
+ eclass/greadme.eclass | 281 ++++++++++++++++++++++++++++++++++++++++++
+ 1 file changed, 281 insertions(+)
+ create mode 100644 eclass/greadme.eclass
+
+-- 
+2.41.0
diff --git a/eclass/0001-greadme.eclass-new-eclass.patch b/eclass/0001-greadme.eclass-new-eclass.patch
new file mode 100644
index 000000000000..52f4d9b6ff4d
--- /dev/null
+++ b/eclass/0001-greadme.eclass-new-eclass.patch
@@ -0,0 +1,305 @@
+From edff06160e33b361c9d6a7e273fc7808337c4518 Mon Sep 17 00:00:00 2001
+From: Florian Schmaus <flow@gentoo.org>
+Date: Sat, 6 Jan 2024 17:39:45 +0100
+Subject: [PATCH 1/1] greadme.eclass: new eclass
+
+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.
+
+Signed-off-by: Florian Schmaus <flow@gentoo.org>
+---
+ eclass/greadme.eclass | 281 ++++++++++++++++++++++++++++++++++++++++++
+ 1 file changed, 281 insertions(+)
+ create mode 100644 eclass/greadme.eclass
+
+diff --git a/eclass/greadme.eclass b/eclass/greadme.eclass
+new file mode 100644
+index 000000000000..ac83c36983ef
+--- /dev/null
++++ b/eclass/greadme.eclass
+@@ -0,0 +1,281 @@
++# 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"
++		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() {
++	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_files[0]}"
++					;;
++				*)
++					die "unpexpected number of Gentoo README files found"
++					;;
++			esac
++
++			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
++
++			mkdir "${T}/greadme"
++
++			mkdir "${T}/greadme/live"
++			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
++				unpacker "${live_doc_file}"
++			fi
++			popd > /dev/null
++
++			mkdir "${T}/greadme/image"
++			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}" .
++			else
++				unpacker "${image_doc_file}"
++			fi
++			popd > /dev/null
++
++			live_doc_file="${T}/greadme/live/${_GREADME_FILENAME}"
++			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 image_doc_file="${ED}/${_GREADME_REL_PATH}"
++
++	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
++		greadme_path="${_GREADME_UNPACKED}"
++	else
++		greadme_path="${EROOT}/${_GREADME_REL_PATH}"
++	fi
++
++	local greadme_line
++	while read -r greadme_line; do elog "${greadme_line}"; done < "${EROOT}/${_GREADME_REL_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
+-- 
+2.41.0
diff --git a/eclass/unpacker.eclass b/eclass/unpacker.eclass
index 2957ca02d3f4..73b763ca2018 100644
--- a/eclass/unpacker.eclass
+++ b/eclass/unpacker.eclass
@@ -42,6 +42,11 @@ inherit multiprocessing toolchain-funcs
 # `xz`, `plzip`, `pdlzip`, and `lzip`.  Make sure your choice accepts the "-dc" options.
 # Note: this is meant for users to set, not ebuilds.
 
+# @ECLASS_VARIABLE: UNPACKER_NO_BANNER
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# If set, do not display the unpack banner with information what got unpacked where.
+
 # for internal use only (unpack_pdv and unpack_makeself)
 find_unpackable_file() {
 	local src=$1
@@ -63,6 +68,8 @@ find_unpackable_file() {
 }
 
 unpack_banner() {
+	[[ ${UNPACKER_NO_BANNER} ]] && return
+
 	echo ">>> Unpacking ${1##*/} to ${PWD}"
 }
 
-- 
2.41.0