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 E802115803E for ; Sat, 6 Jan 2024 17:02:27 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 1051C2BC072; Sat, 6 Jan 2024 17:02:05 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.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 ADB682BC06D for ; Sat, 6 Jan 2024 17:02:04 +0000 (UTC) From: Florian Schmaus To: gentoo-dev@lists.gentoo.org Cc: pacho@gentoo.org, Florian Schmaus Subject: [gentoo-dev] [PATCH 1/1] greadme.eclass: new eclass Date: Sat, 6 Jan 2024 18:01:48 +0100 Message-ID: <20240106170153.1581902-2-flow@gentoo.org> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20240106170153.1581902-1-flow@gentoo.org> References: <20240106170153.1581902-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: 6ed4a4f5-3b4c-44b2-9179-217c894f0f1c X-Archives-Hash: 71703a029b05dd0ef7ce18b05a7f55c7 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