blob: 5cbbb8bff37660892808740a7443a6390a889b66 [file] [log] [blame]
# Copyright 1999-2013 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: /var/cvsroot/gentoo-x86/eclass/readme.gentoo.eclass,v 1.7 2013/05/24 18:05:27 pacho Exp $
# @ECLASS: readme.gentoo
# Pacho Ramos <>
# Author: Pacho Ramos <>
# @BLURB: An eclass for installing a README.gentoo doc file recording tips
# shown via elog messages.
# 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 and a file for later reviewing will be
# installed under /usr/share/doc/${PF}
if [[ ${___ECLASS_ONCE_README_GENTOO} != "recur -_+^+_- spank" ]] ; then
___ECLASS_ONCE_README_GENTOO="recur -_+^+_- spank"
inherit eutils
case "${EAPI:-0}" in
die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
# EAPI>=4 is required for REPLACING_VERSIONS preventing us
# from needing to export another pkg_preinst phase to save has_version
# result. Also relies on EAPI >=4 default src_install phase.
die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
EXPORT_FUNCTIONS src_install pkg_postinst
# If non-empty, DOC_CONTENTS information will be strictly respected,
# not getting it automatically formatted by fmt. If empty, it will
# rely on fmt for formatting and 'echo -e' options to tweak lines a bit.
# If non-empty this variable forces elog messages to be printed.
# @FUNCTION: readme.gentoo_create_doc
# Create doc file with ${DOC_CONTENTS} variable (preferred) and, if not set,
# look for "${FILESDIR}/README.gentoo" contents. You can use
# ${FILESDIR}/README.gentoo-${SLOT} also.
# Usually called at src_install phase.
readme.gentoo_create_doc() {
debug-print-function ${FUNCNAME} "${@}"
if [[ -n "${DOC_CONTENTS}" ]]; then
set -f
if [[ -n "${DISABLE_AUTOFORMATTING}" ]]; then
echo "${DOC_CONTENTS}" > "${T}"/README.gentoo
echo -e ${DOC_CONTENTS} | fold -s -w 70 \
| sed 's/[[:space:]]*$//' > "${T}"/README.gentoo
elif [[ -f "${FILESDIR}/README.gentoo-${SLOT%/*}" ]]; then
cp "${FILESDIR}/README.gentoo-${SLOT%/*}" "${T}"/README.gentoo
elif [[ -f "${FILESDIR}/README.gentoo" ]]; then
cp "${FILESDIR}/README.gentoo" "${T}"/README.gentoo
die "You are not specifying README.gentoo contents!"
dodoc "${T}"/README.gentoo
# @FUNCTION: readme.gentoo_print_elog
# Print elog messages with "${T}"/README.gentoo contents. They will be
# shown only when package is installed at first time.
# Usually called at pkg_postinst phase.
# If you want to show them always, please set FORCE_PRINT_ELOG to a non empty
# value in your ebuild before this function is called.
# This can be useful when, for example, DOC_CONTENTS is modified, then, you can
# rely on specific REPLACING_VERSIONS handling in your ebuild to print messages
# when people update from versions still providing old message.
readme.gentoo_print_elog() {
debug-print-function ${FUNCNAME} "${@}"
if [[ -z "${README_GENTOO_DOC_VALUE}" ]]; then
die "readme.gentoo_print_elog invoked without matching readme.gentoo_create_doc call!"
elif ! [[ -n "${REPLACING_VERSIONS}" ]] || [[ -n "${FORCE_PRINT_ELOG}" ]]; then
echo -e "${README_GENTOO_DOC_VALUE}" | while read -r ELINE; do elog "${ELINE}"; done
elog ""
elog "(Note: Above message is only printed the first time package is"
elog "installed. Please look at /usr/share/doc/${PF}/README.gentoo*"
elog "for future reference)"
# @FUNCTION: readme.gentoo_src_install
# Install generated doc file automatically.
readme.gentoo_src_install() {
debug-print-function ${FUNCNAME} "${@}"
# @FUNCTION: readme.gentoo_pkg_postinst
# Show elog messages from from just generated doc file.
readme.gentoo_pkg_postinst() {
debug-print-function ${FUNCNAME} "${@}"