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.
Furthermore, this eclass dos not store the doc file's contents in an
environment variable, which helps to keep the environment size of
ebuilds using the eclass small.
Signed-off-by: Florian Schmaus <flow@gentoo.org>
---
eclass/greadme.eclass | 307 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 307 insertions(+)
create mode 100644 eclass/greadme.eclass
diff --git a/eclass/greadme.eclass b/eclass/greadme.eclass
new file mode 100644
index 000000000000..25e0210406c1
--- /dev/null
+++ b/eclass/greadme.eclass
@@ -0,0 +1,307 @@
+# Copyright 1999-2024 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+# @ECLASS: greadme.eclass
+# @MAINTAINER:
+# Florian Schmaus <flow@gentoo.org>
+# @AUTHOR:
+# Author: Florian Schmaus <flow@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 while trying to create it"
+ 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() {
+ local image_doc_file="${ED}/${_GREADME_REL_PATH}"
+
+ if [[ ${_GREADME_COMPRESS} ]]; then
+ local greadme_tmpdir="${T}/greadme"
+
+ mkdir -p "${greadme_tmpdir}/image" || die
+
+ 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
+
+ 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}" . || die
+ else
+ nonfatal unpacker "${image_doc_file}"
+ if [[ $? -gt 0 ]]; then
+ # We failed to unpack the readme doc from the
+ # image, therefore, we can't show it (unless we
+ # would save it's content in a env variable like
+ # gentoo.readme-r1 does).
+ _GREADME_SHOW=""
+ return
+ fi
+ fi
+ popd > /dev/null
+ fi
+
+ 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
+
+ if [[ -d "${greadme_tmpdir}/live" ]]; then
+ rm -rf "${greadme_tmpdir}"/live/* || die
+ else
+ mkdir "${T}/greadme/live"
+ fi
+
+ 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
+ nonfatal unpacker "${live_doc_file}"
+ if [[ $? -gt 0 ]]; then
+ # We failed to unpack the live readme doc, fallback
+ # to show the new readme contents.
+ _GREADME_SHOW="failed-to-unpack-live-readme-doc"
+ return
+ fi
+ 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 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
+ if [[ -z ${_GREADME_UNPACKED} ]]; then
+ # We failed to decompress the readme doc from the image.
+ return
+ fi
+ greadme_path="${_GREADME_UNPACKED}"
+ else
+ greadme_path="${EROOT}/${_GREADME_REL_PATH}"
+ fi
+
+ local line
+ while read -r line; do elog "${line}"; done < "${greadme_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
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.
Furthermore, this eclass dos not store the doc file's contents in an
environment variable, which helps to keep the environment size of
ebuilds using the eclass small.
Signed-off-by: Florian Schmaus <flow@gentoo.org>
---
eclass/greadme.eclass | 307 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 307 insertions(+)
create mode 100644 eclass/greadme.eclass
diff --git a/eclass/greadme.eclass b/eclass/greadme.eclass
new file mode 100644
index 000000000000..25e0210406c1
--- /dev/null
+++ b/eclass/greadme.eclass
@@ -0,0 +1,307 @@
+# Copyright 1999-2024 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+# @ECLASS: greadme.eclass
+# @MAINTAINER:
+# Florian Schmaus <flow@gentoo.org>
+# @AUTHOR:
+# Author: Florian Schmaus <flow@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 while trying to create it"
+ 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() {
+ local image_doc_file="${ED}/${_GREADME_REL_PATH}"
+
+ if [[ ${_GREADME_COMPRESS} ]]; then
+ local greadme_tmpdir="${T}/greadme"
+
+ mkdir -p "${greadme_tmpdir}/image" || die
+
+ 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
+
+ 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}" . || die
+ else
+ nonfatal unpacker "${image_doc_file}"
+ if [[ $? -gt 0 ]]; then
+ # We failed to unpack the readme doc from the
+ # image, therefore, we can't show it (unless we
+ # would save it's content in a env variable like
+ # gentoo.readme-r1 does).
+ _GREADME_SHOW=""
+ return
+ fi
+ fi
+ popd > /dev/null
+ fi
+
+ 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
+
+ if [[ -d "${greadme_tmpdir}/live" ]]; then
+ rm -rf "${greadme_tmpdir}"/live/* || die
+ else
+ mkdir "${T}/greadme/live"
+ fi
+
+ 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
+ nonfatal unpacker "${live_doc_file}"
+ if [[ $? -gt 0 ]]; then
+ # We failed to unpack the live readme doc, fallback
+ # to show the new readme contents.
+ _GREADME_SHOW="failed-to-unpack-live-readme-doc"
+ return
+ fi
+ 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 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
+ if [[ -z ${_GREADME_UNPACKED} ]]; then
+ # We failed to decompress the readme doc from the image.
+ return
+ fi
+ greadme_path="${_GREADME_UNPACKED}"
+ else
+ greadme_path="${EROOT}/${_GREADME_REL_PATH}"
+ fi
+
+ local line
+ while read -r line; do elog "${line}"; done < "${greadme_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
