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 1FF66159C96 for ; Wed, 24 Jul 2024 08:59:00 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 3B7EBE2A0E; Wed, 24 Jul 2024 08:58:59 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 13641E2A0E for ; Wed, 24 Jul 2024 08:58:59 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (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 smtp.gentoo.org (Postfix) with ESMTPS id 138D8340CB1 for ; Wed, 24 Jul 2024 08:58:58 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 4C7D21117 for ; Wed, 24 Jul 2024 08:58:56 +0000 (UTC) From: "Florian Schmaus" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Florian Schmaus" Message-ID: <1721811304.6b00659e2a8da878326fa499419f97e9a3d7daf5.flow@gentoo> Subject: [gentoo-commits] repo/gentoo:master commit in: eclass/ X-VCS-Repository: repo/gentoo X-VCS-Files: eclass/greadme.eclass X-VCS-Directories: eclass/ X-VCS-Committer: flow X-VCS-Committer-Name: Florian Schmaus X-VCS-Revision: 6b00659e2a8da878326fa499419f97e9a3d7daf5 X-VCS-Branch: master Date: Wed, 24 Jul 2024 08:58:56 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: a1f2e2e2-e983-431b-a337-f3ed1795dcda X-Archives-Hash: 0cf7a4b410ab7c8c32a8a67eb14780f8 commit: 6b00659e2a8da878326fa499419f97e9a3d7daf5 Author: Florian Schmaus gentoo org> AuthorDate: Thu Jun 13 07:48:40 2024 +0000 Commit: Florian Schmaus gentoo org> CommitDate: Wed Jul 24 08:55:04 2024 +0000 URL: https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=6b00659e greadme.eclass: new eclass This new eclass includes various improvements over the existing readme.gentoo-r1.eclass. First, the content of README.gentoo will only be shown on new installations or if it has changed between updates. Second, it allows the composition of readme via bash's heredoc. And finally, the eclass exports phase functions, which helps to reduce the boilerplate code in many cases. Signed-off-by: Florian Schmaus gentoo.org> eclass/greadme.eclass | 251 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) diff --git a/eclass/greadme.eclass b/eclass/greadme.eclass new file mode 100644 index 000000000000..38190becf91d --- /dev/null +++ b/eclass/greadme.eclass @@ -0,0 +1,251 @@ +# Copyright 1999-2024 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +# @ECLASS: greadme.eclass +# @MAINTAINER: +# Florian Schmaus +# @SUPPORTED_EAPIS: 8 +# @BLURB: install a doc file, that will be conditionally shown via elog messages +# @DESCRIPTION: +# An eclass for installing a README.gentoo doc file with important +# information for the user. The content of README.gentoo will shown be +# via elog messages either on fresh installations or if the contents of +# the file have changed. Furthermore, the README.gentoo file will be +# installed under /usr/share/doc/${PF} for later consultation. +# +# This eclass was inspired by readme.gentoo-r1.eclass. The main +# differences are as follows. Firstly, it only displays the doc file +# contents if they have changed (unless GREADME_SHOW is set). +# 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 --append <<-EOF +# This is conditional readme content, based on USE=foo. +# EOF +# fi +# } +# @CODE +# +# If the ebuild overrides the default pkg_preinst or respectively +# pkg_postinst, then it must call greadme_pkg_preinst and +# greadme_pkg_postinst explicitly. + +if [[ -z ${_GREADME_ECLASS} ]]; then +_GREADME_ECLASS=1 + +case ${EAPI} in + 8) ;; + *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;; +esac + +_GREADME_TMP_FILE="${T}/README.gentoo" +_GREADME_REL_PATH="/usr/share/doc/${PF}/README.gentoo" + +# @ECLASS_VARIABLE: GREADME_SHOW +# @DEFAULT_UNSET +# @DESCRIPTION: +# If set to "yes" then unconditionally show the contents of the readme +# file in pkg_postinst via elog. If set to "no", then do not show the +# contents of the readme file, even if they have changed. + +# @ECLASS_VARIABLE: GREADME_DISABLE_AUTOFORMAT +# @DEFAULT_UNSET +# @DESCRIPTION: +# If non-empty, the readme file will not be automatically formatted. + +# @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 + if [[ ${1} = --append ]]; then + append=1 + shift + fi + + [[ $# -eq 0 ]] || die "${FUNCNAME[0]}: Bad parameters: $*" + + if [[ -n ${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 + cat > "${_GREADME_TMP_FILE}" || die + fi + + _greadme_install_doc +} + +# @FUNCTION: greadme_file +# @USAGE: +# @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 + + 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} "${@}" + + local greadme="${_GREADME_TMP_FILE}" + if [[ ! ${GREADME_DISABLE_AUTOFORMAT} ]]; then + greadme="${_GREADME_TMP_FILE}".formatted + + # Use fold, followed by a sed to strip trailing whitespace. + # https://bugs.gentoo.org/460050#c7 + fold -s -w 70 "${_GREADME_TMP_FILE}" | + sed 's/[[:space:]]*$//' > "${greadme}" + assert "failed to autoformat README.gentoo" + fi + + # Subshell to avoid pollution of calling environment. + ( + docinto . + newdoc "${greadme}" "README.gentoo" + ) + + # Exclude the readme file from compression, so that its contents can + # be easily compared. + docompress -x "${_GREADME_REL_PATH}" + + # Save the contents of the of the readme. Unfortunately we have to + # do this in src_* phase, because FEATURES=nodoc is applied right + # after src_install and not after pkg_preinst. + _GREADME_CONTENT=$(< "${greadme}") +} + +# @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() { + debug-print-function ${FUNCNAME} "${@}" + + if [[ -z ${REPLACING_VERSIONS} ]]; then + _GREADME_SHOW="fresh-install" + return + fi + + if [[ -v GREADME_SHOW ]]; then + case ${GREADME_SHOW} in + yes) + _GREADME_SHOW="forced" + ;; + no) + _GREADME_SHOW="" + ;; + *) + die "Invalid argument of GREADME_SHOW: ${GREADME_SHOW}" + ;; + esac + return + fi + + local image_greadme_file="${ED}${_GREADME_REL_PATH}" + if [[ ! -f ${image_greadme_file} ]]; then + if [[ -v _GREADME_CONTENT ]]; then + # There is no greadme in the image but the ebuild created + # one. This is likely because FEATURES=nodoc is active. + # Unconditionally show greadme's contents. + _GREADME_SHOW="nodoc-active" + else + # No README file was created by the ebuild. + _GREADME_SHOW="" + fi + + return + fi + + check_live_doc_file() { + local cur_pvr=$1 + local live_greadme_file="${EROOT}/usr/share/doc/${PN}-${cur_pvr}/README.gentoo" + + if [[ ! -f ${live_greadme_file} ]]; then + _GREADME_SHOW="no-current-greadme" + return + fi + + cmp -s "${live_greadme_file}" "${image_greadme_file}" + case $? in + 0) + _GREADME_SHOW="" + ;; + 1) + _GREADME_SHOW="content-differs" + ;; + *) + die "cmp failed with $?" + ;; + 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: 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 line + printf '%s\n' "${_GREADME_CONTENT}" | 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 message changed. Please look at" + elog "${EPREFIX}${_GREADME_REL_PATH}" + elog "for future reference." +} + +fi + +EXPORT_FUNCTIONS pkg_preinst pkg_postinst