1 # Copyright 1999-2015 Gentoo Foundation
2 # Distributed under the terms of the GNU General Public License v2
5 # @ECLASS: readme.gentoo.eclass
7 # Pacho Ramos <pacho@gentoo.org>
9 # Author: Pacho Ramos <pacho@gentoo.org>
10 # @BLURB: An eclass for installing a README.gentoo doc file recording tips
11 # shown via elog messages.
13 # An eclass for installing a README.gentoo doc file recording tips
14 # shown via elog messages. With this eclass, those elog messages will only be
15 # shown at first package installation and a file for later reviewing will be
16 # installed under /usr/share/doc/${PF}
18 # This eclass is DEPRECATED. Please use readme.gentoo-r1 instead.
20 if [[ -z ${_README_GENTOO_ECLASS} ]]; then
21 _README_GENTOO_ECLASS=1
27 die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
30 # EAPI>=4 is required for REPLACING_VERSIONS preventing us
31 # from needing to export another pkg_preinst phase to save has_version
32 # result. Also relies on EAPI >=4 default src_install phase.
33 EXPORT_FUNCTIONS src_install pkg_postinst
36 die "Unsupported EAPI=${EAPI} for ${ECLASS}"
37 die "Please migrate to readme.gentoo-r1.eclass and note that"
38 die "it stops to export any ebuild phases and, then, you will"
39 die "need to ensure readme.gentoo_create_doc is called in"
40 die "src_install and readme.gentoo_print_elog in pkg_postinst"
43 die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
47 # @ECLASS-VARIABLE: DISABLE_AUTOFORMATTING
50 # If non-empty, DOC_CONTENTS information will be strictly respected,
51 # not getting it automatically formatted by fmt. If empty, it will
52 # rely on fmt for formatting and 'echo -e' options to tweak lines a bit.
54 # @ECLASS-VARIABLE: FORCE_PRINT_ELOG
57 # If non-empty this variable forces elog messages to be printed.
59 # @ECLASS-VARIABLE: README_GENTOO_SUFFIX
61 # If you want to specify a suffix for README.gentoo file please export it.
62 : ${README_GENTOO_SUFFIX:=""}
64 # @FUNCTION: readme.gentoo_create_doc
66 # Create doc file with ${DOC_CONTENTS} variable (preferred) and, if not set,
67 # look for "${FILESDIR}/README.gentoo" contents. You can use
68 # ${FILESDIR}/README.gentoo-${SLOT} also.
69 # Usually called at src_install phase.
70 readme.gentoo_create_doc() {
71 debug-print-function ${FUNCNAME} "${@}"
73 if [[ -n "${DOC_CONTENTS}" ]]; then
76 if [[ -n "${DISABLE_AUTOFORMATTING}" ]]; then
77 echo "${DOC_CONTENTS}" > "${T}"/README.gentoo
79 echo -e ${DOC_CONTENTS} | fold -s -w 70 \
80 | sed 's/[[:space:]]*$//' > "${T}"/README.gentoo
83 elif [[ -f "${FILESDIR}/README.gentoo-${SLOT%/*}" ]]; then
84 cp "${FILESDIR}/README.gentoo-${SLOT%/*}" "${T}"/README.gentoo || die
85 elif [[ -f "${FILESDIR}/README.gentoo${README_GENTOO_SUFFIX}" ]]; then
86 cp "${FILESDIR}/README.gentoo${README_GENTOO_SUFFIX}" "${T}"/README.gentoo || die
88 die "You are not specifying README.gentoo contents!"
91 dodoc "${T}"/README.gentoo
92 README_GENTOO_DOC_VALUE=$(< "${T}/README.gentoo")
95 # @FUNCTION: readme.gentoo_print_elog
97 # Print elog messages with "${T}"/README.gentoo contents. They will be
98 # shown only when package is installed at first time.
99 # Usually called at pkg_postinst phase.
101 # If you want to show them always, please set FORCE_PRINT_ELOG to a non empty
102 # value in your ebuild before this function is called.
103 # This can be useful when, for example, DOC_CONTENTS is modified, then, you can
104 # rely on specific REPLACING_VERSIONS handling in your ebuild to print messages
105 # when people update from versions still providing old message.
106 readme.gentoo_print_elog() {
107 debug-print-function ${FUNCNAME} "${@}"
109 eqawarn "${CATEGORY}/${PN} is using the deprecated readme.gentoo.eclass."
110 eqawarn "Please use readme.gentoo-r1 instead."
112 if [[ -z "${README_GENTOO_DOC_VALUE}" ]]; then
113 die "readme.gentoo_print_elog invoked without matching readme.gentoo_create_doc call!"
114 elif ! [[ -n "${REPLACING_VERSIONS}" ]] || [[ -n "${FORCE_PRINT_ELOG}" ]]; then
115 echo -e "${README_GENTOO_DOC_VALUE}" | while read -r ELINE; do elog "${ELINE}"; done
117 elog "(Note: Above message is only printed the first time package is"
118 elog "installed. Please look at ${EPREFIX}/usr/share/doc/${PF}/README.gentoo*"
119 elog "for future reference)"
124 # @FUNCTION: readme.gentoo_src_install
126 # Install generated doc file automatically.
127 readme.gentoo_src_install() {
128 debug-print-function ${FUNCNAME} "${@}"
130 readme.gentoo_create_doc
133 # @FUNCTION: readme.gentoo_pkg_postinst
135 # Show elog messages from from just generated doc file.
136 readme.gentoo_pkg_postinst() {
137 debug-print-function ${FUNCNAME} "${@}"
138 readme.gentoo_print_elog