Signed-off-by: Florian Schmaus <f...@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 <f...@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 <f...@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 <f...@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 <f...@gentoo.org>
++# @AUTHOR:
++# Author: Florian Schmaus <f...@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
