1 # Copyright 1999-2018 Gentoo Foundation
2 # Distributed under the terms of the GNU General Public License v2
4 # @ECLASS: readme.gentoo-r1.eclass
6 # Pacho Ramos <pacho@gentoo.org>
8 # Author: Pacho Ramos <pacho@gentoo.org>
9 # @SUPPORTED_EAPIS: 4 5 6 7
10 # @BLURB: install a doc file shown via elog messages
12 # An eclass for installing a README.gentoo doc file recording tips
13 # shown via elog messages. With this eclass, those elog messages will only be
14 # shown at first package installation and a file for later reviewing will be
15 # installed under /usr/share/doc/${PF}
17 # You need to call readme.gentoo_create_doc in src_install phase and
18 # readme.gentoo_print_elog in pkg_postinst
20 if [[ -z ${_README_GENTOO_ECLASS} ]]; then
21 _README_GENTOO_ECLASS=1
25 die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
30 die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
34 # @ECLASS-VARIABLE: DISABLE_AUTOFORMATTING
37 # If non-empty, DOC_CONTENTS information will be strictly respected,
38 # not getting it automatically formatted by fmt. If empty, it will
39 # rely on fmt for formatting and 'echo -e' options to tweak lines a bit.
41 # @ECLASS-VARIABLE: FORCE_PRINT_ELOG
44 # If non-empty this variable forces elog messages to be printed.
46 # @ECLASS-VARIABLE: README_GENTOO_SUFFIX
48 # If you want to specify a suffix for README.gentoo file please export it.
49 : ${README_GENTOO_SUFFIX:=""}
51 # @FUNCTION: readme.gentoo_create_doc
53 # Create doc file with ${DOC_CONTENTS} variable (preferred) and, if not set,
54 # look for "${FILESDIR}/README.gentoo" contents. You can use
55 # ${FILESDIR}/README.gentoo-${SLOT} also.
56 # Usually called at src_install phase.
57 readme.gentoo_create_doc() {
58 debug-print-function ${FUNCNAME} "${@}"
60 if [[ -n "${DOC_CONTENTS}" ]]; then
61 if [[ -n "${DISABLE_AUTOFORMATTING}" ]]; then
62 echo "${DOC_CONTENTS}" > "${T}"/README.gentoo || die
65 set -f # disable filename expansion in echo arguments
66 echo -e ${DOC_CONTENTS} | fold -s -w 70 \
67 | sed 's/[[:space:]]*$//' > "${T}"/README.gentoo
69 set +f -${saved_flags}
71 elif [[ -f "${FILESDIR}/README.gentoo-${SLOT%/*}" ]]; then
72 cp "${FILESDIR}/README.gentoo-${SLOT%/*}" "${T}"/README.gentoo || die
73 elif [[ -f "${FILESDIR}/README.gentoo${README_GENTOO_SUFFIX}" ]]; then
74 cp "${FILESDIR}/README.gentoo${README_GENTOO_SUFFIX}" "${T}"/README.gentoo || die
76 die "You are not specifying README.gentoo contents!"
79 dodoc "${T}"/README.gentoo
80 README_GENTOO_DOC_VALUE=$(< "${T}/README.gentoo")
83 # @FUNCTION: readme.gentoo_print_elog
85 # Print elog messages with "${T}"/README.gentoo contents. They will be
86 # shown only when package is installed at first time.
87 # Usually called at pkg_postinst phase.
89 # If you want to show them always, please set FORCE_PRINT_ELOG to a non empty
90 # value in your ebuild before this function is called.
91 # This can be useful when, for example, DOC_CONTENTS is modified, then, you can
92 # rely on specific REPLACING_VERSIONS handling in your ebuild to print messages
93 # when people update from versions still providing old message.
94 readme.gentoo_print_elog() {
95 debug-print-function ${FUNCNAME} "${@}"
97 if [[ -z "${README_GENTOO_DOC_VALUE}" ]]; then
98 die "readme.gentoo_print_elog invoked without matching readme.gentoo_create_doc call!"
99 elif ! [[ -n "${REPLACING_VERSIONS}" ]] || [[ -n "${FORCE_PRINT_ELOG}" ]]; then
100 echo -e "${README_GENTOO_DOC_VALUE}" | while read -r ELINE; do elog "${ELINE}"; done
102 elog "(Note: Above message is only printed the first time package is"
103 elog "installed. Please look at ${EPREFIX}/usr/share/doc/${PF}/README.gentoo*"
104 elog "for future reference)"