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 AA2A0158451 for ; Tue, 9 Jan 2024 08:39:43 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 9D5EBE29DA; Tue, 9 Jan 2024 08:39:25 +0000 (UTC) Received: from smtp.gentoo.org (smtp.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)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 2BA26E29D3 for ; Tue, 9 Jan 2024 08:39:25 +0000 (UTC) From: Florian Schmaus To: gentoo-dev@lists.gentoo.org Cc: Florian Schmaus Subject: [gentoo-dev] [PATCH v2 2/3] add UNPACKER_NO_BANNER variable Date: Tue, 9 Jan 2024 09:39:02 +0100 Message-ID: <20240109083914.242561-2-flow@gentoo.org> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20240109083914.242561-1-flow@gentoo.org> References: <20240109083914.242561-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-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Archives-Salt: 58409090-952b-440b-8ab0-994074c85a7d X-Archives-Hash: af305fdbd56040d2cd4656d49f9d1e9c Signed-off-by: Florian Schmaus --- 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 +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 +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 +--- + 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 ++# @AUTHOR: ++# Author: Florian Schmaus ++# @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: ++# @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