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


Reply via email to