From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id E84791581D3 for ; Sun, 2 Jun 2024 13:57:44 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 66A13E2B3A; Sun, 2 Jun 2024 13:57:25 +0000 (UTC) Received: from smtp.gentoo.org (dev.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 17613E2B37 for ; Sun, 2 Jun 2024 13:57:25 +0000 (UTC) From: Florian Schmaus To: gentoo-dev@lists.gentoo.org Cc: pacho@gentoo.org, Florian Schmaus Subject: [gentoo-dev] [PATCH 1/4] readme.gentoo-r1.eclass: display readme if content changed (or fresh install) Date: Sun, 2 Jun 2024 15:57:06 +0200 Message-ID: <20240602135716.66992-2-flow@gentoo.org> X-Mailer: git-send-email 2.44.1 In-Reply-To: <20240602135716.66992-1-flow@gentoo.org> References: <20240109083914.242561-1-flow@gentoo.org> <20240602135716.66992-1-flow@gentoo.org> Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Archives-Salt: d824dba0-a121-441b-a1fd-502b46b1397d X-Archives-Hash: b2552276b12df032c97682f8a16dc097 Improve the user experience of readme.gentoo-r1.eclass by reducing the number of messages presented to the user upon emerge. We reduce the number of messages by only showing the contents of README.gentoo *if they have changed* (or on fresh installations). To be able to detect if the content has changed, the eclass now records the 4-byte CRC value of README.gentoo. Upon installation, this 4-byte value is compared. It is necessary to indirectly compare the content, as README.gentoo is installed via dodoc, which is subject to docdir compression, and there is no guarantee that we will be able to uncompress the live system's version of README.gentoo (let alone that it is not trivial to find a suitable decompressor candidate). Signed-off-by: Florian Schmaus --- eclass/readme.gentoo-r1.eclass | 124 ++++++++++++++++++++++++++++----- 1 file changed, 108 insertions(+), 16 deletions(-) diff --git a/eclass/readme.gentoo-r1.eclass b/eclass/readme.gentoo-r1.eclass index 202ba31f4f70..2a79911cafbf 100644 --- a/eclass/readme.gentoo-r1.eclass +++ b/eclass/readme.gentoo-r1.eclass @@ -1,4 +1,4 @@ -# Copyright 1999-2023 Gentoo Authors +# Copyright 1999-2024 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 # @ECLASS: readme.gentoo-r1.eclass @@ -14,8 +14,11 @@ # shown at first package installation and a file for later reviewing will be # installed under /usr/share/doc/${PF} # -# You need to call readme.gentoo_create_doc in src_install phase and -# readme.gentoo_print_elog in pkg_postinst +# +# You need to call readme.gentoo_create_doc in src_install phase if you +# use DOC_CONTENTS or obtain the readme from FILESIDR. +# +# Note that this eclass exports pkg_preinst and pkg_postinst functions. if [[ -z ${_README_GENTOO_ECLASS} ]]; then _README_GENTOO_ECLASS=1 @@ -47,6 +50,15 @@ esac # If you want to specify a suffix for README.gentoo file please export it. : "${README_GENTOO_SUFFIX:=""}" +_GREADME_FILENAME="README.gentoo" +_GREADME_HASH_FILENAME=".${_GREADME_FILENAME}.hash" + +_GREADME_TMP_FILE="${T}/${_GREADME_FILENAME}" + +_GREADME_DOC_DIR="usr/share/doc/${PF}" +_GREADME_REL_PATH="${_GREADME_DOC_DIR}/${_GREADME_FILENAME}" +_GREADME_HASH_REL_PATH="${_GREADME_DOC_DIR}/${_GREADME_HASH_FILENAME}" + # @FUNCTION: readme.gentoo_create_doc # @DESCRIPTION: # Create doc file with ${DOC_CONTENTS} variable (preferred) and, if not set, @@ -75,11 +87,20 @@ readme.gentoo_create_doc() { die "You are not specifying README.gentoo contents!" fi - ( # subshell to avoid pollution of calling environment - docinto . - dodoc "${T}"/README.gentoo - ) || die - README_GENTOO_DOC_VALUE=$(< "${T}/README.gentoo") + # subshell to avoid pollution of calling environment + ( + insinto "${_GREADME_DOC_DIR}" + + doins "${_GREADME_TMP_FILE}" + cksum --raw "${_GREADME_TMP_FILE}" | newins - "${_GREADME_HASH_FILENAME}" + assert + ) + + # Save the readme contents in an variable, so that it can be shown ins pkg_postinst(). + _GREADME_CONTENTS=$(< "${_GREADME_TMP_FILE}") + + # Exclude the 4-byte hash file from compression. + docompress -x "${_GREADME_HASH_REL_PATH}" } # @FUNCTION: readme.gentoo_print_elog @@ -96,15 +117,86 @@ readme.gentoo_create_doc() { readme.gentoo_print_elog() { debug-print-function ${FUNCNAME} "${@}" - if [[ -z "${README_GENTOO_DOC_VALUE}" ]]; then - die "readme.gentoo_print_elog invoked without matching readme.gentoo_create_doc call!" - elif ! [[ -n "${REPLACING_VERSIONS}" ]] || [[ -n "${FORCE_PRINT_ELOG}" ]]; then - echo -e "${README_GENTOO_DOC_VALUE}" | while read -r ELINE; do elog "${ELINE}"; done - elog "" - elog "(Note: Above message is only printed the first time package is" - elog "installed. Please look at ${EPREFIX}/usr/share/doc/${PF}/README.gentoo*" - elog "for future reference)" + if ! [[ -n "${REPLACING_VERSIONS}" ]] || [[ -n "${FORCE_PRINT_ELOG}" ]]; then + _GREADME_SHOW="force" + readme.gentoo-r1_pkg_postinst fi } +# @FUNCTION: readme.gentoo_pkg_preinst +# @DESCRIPTION: +# Performs checks like comparing the readme doc from the image with a +# potentially existing one in the live system. +readme.gentoo-r1_pkg_preinst() { + debug-print-function ${FUNCNAME} "${@}" + + if [[ -z ${REPLACING_VERSIONS} ]]; then + _GREADME_SHOW="fresh-install" + return + fi + + local image_hash_file="${ED}/${_GREADME_HASH_REL_PATH}" + + check_live_doc_file() { + local cur_pvr=$1 + local live_hash_file="${EROOT}/usr/share/doc/${PN}-${cur_pvr}/${_GREADME_HASH_FILENAME}" + + if [[ ! -f ${live_hash_file} ]]; then + _GREADME_SHOW="no-current-greadme" + return + fi + + cmp -s "${live_hash_file}" "${image_hash_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} + + # Once _GREADME_SHOW is non empty, we found a reason to show the + # readme and we can abort the loop. + if [[ -n ${_GREADME_SHOW} ]]; then + break + fi + done +} + +# @FUNCTION: readme.gentoo_pkg_postinst +# @DESCRIPTION: +# Conditionally shows the contents of the readme doc via elog. +readme.gentoo-r1_pkg_postinst() { + debug-print-function ${FUNCNAME} "${@}" + + if [[ ! -v _GREADME_SHOW ]]; then + ewarn "_GREADME_SHOW not set. Missing call of greadme_pkg_preinst?" + return + fi + + if [[ -z "${_GREADME_SHOW}" ]]; then + # If _GREADME_SHOW is empty, then there is no reason to show the contents. + return + fi + + local line + echo -e "${_GREADME_CONTENTS}" | while read -r line; do elog "${line}"; done + 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)" +} + fi + +EXPORT_FUNCTIONS pkg_preinst pkg_postinst -- 2.44.1