eclass/readme.gentoo.eclass

   1 # Copyright 1999-2014 Gentoo Foundation
   2 # Distributed under the terms of the GNU General Public License v2
   3 # $Id$
   4
   5 # @ECLASS: readme.gentoo.eclass
   6 # @MAINTAINER:
   7 # Pacho Ramos <pacho@gentoo.org>
   8 # @AUTHOR:
   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.
  12 # @DESCRIPTION:
  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}
  17
  18 if [[ -z ${_README_GENTOO_ECLASS} ]]; then
  19 _README_GENTOO_ECLASS=1
  20
  21 inherit eutils
  22
  23 case "${EAPI:-0}" in
  24         0|1|2|3)
  25                 die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
  26                 ;;
  27         4|5)
  28                 # EAPI>=4 is required for REPLACING_VERSIONS preventing us
  29                 # from needing to export another pkg_preinst phase to save has_version
  30                 # result. Also relies on EAPI >=4 default src_install phase.
  31                 ;;
  32         *)
  33                 die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
  34                 ;;
  35 esac
  36
  37 EXPORT_FUNCTIONS src_install pkg_postinst
  38
  39 # @ECLASS-VARIABLE: DISABLE_AUTOFORMATTING
  40 # @DEFAULT_UNSET
  41 # @DESCRIPTION:
  42 # If non-empty, DOC_CONTENTS information will be strictly respected,
  43 # not getting it automatically formatted by fmt. If empty, it will
  44 # rely on fmt for formatting and 'echo -e' options to tweak lines a bit.
  45
  46 # @ECLASS-VARIABLE: FORCE_PRINT_ELOG
  47 # @DEFAULT_UNSET
  48 # @DESCRIPTION:
  49 # If non-empty this variable forces elog messages to be printed.
  50
  51 # @ECLASS-VARIABLE: README_GENTOO_SUFFIX
  52 # @DESCRIPTION:
  53 # If you want to specify a suffix for README.gentoo file please export it.
  54 : ${README_GENTOO_SUFFIX:=""}
  55
  56 # @FUNCTION: readme.gentoo_create_doc
  57 # @DESCRIPTION:
  58 # Create doc file with ${DOC_CONTENTS} variable (preferred) and, if not set,
  59 # look for "${FILESDIR}/README.gentoo" contents. You can use
  60 # ${FILESDIR}/README.gentoo-${SLOT} also.
  61 # Usually called at src_install phase.
  62 readme.gentoo_create_doc() {
  63         debug-print-function ${FUNCNAME} "${@}"
  64
  65         if [[ -n "${DOC_CONTENTS}" ]]; then
  66                 eshopts_push
  67                 set -f
  68                 if [[ -n "${DISABLE_AUTOFORMATTING}" ]]; then
  69                         echo "${DOC_CONTENTS}" > "${T}"/README.gentoo
  70                 else
  71                         echo -e ${DOC_CONTENTS} | fold -s -w 70 \
  72                                 | sed 's/[[:space:]]*$//' > "${T}"/README.gentoo
  73                 fi
  74                 eshopts_pop
  75         elif [[ -f "${FILESDIR}/README.gentoo-${SLOT%/*}" ]]; then
  76                 cp "${FILESDIR}/README.gentoo-${SLOT%/*}" "${T}"/README.gentoo || die
  77         elif [[ -f "${FILESDIR}/README.gentoo${README_GENTOO_SUFFIX}" ]]; then
  78                 cp "${FILESDIR}/README.gentoo${README_GENTOO_SUFFIX}" "${T}"/README.gentoo || die
  79         else
  80                 die "You are not specifying README.gentoo contents!"
  81         fi
  82
  83         dodoc "${T}"/README.gentoo
  84         README_GENTOO_DOC_VALUE=$(< "${T}/README.gentoo")
  85 }
  86
  87 # @FUNCTION: readme.gentoo_print_elog
  88 # @DESCRIPTION:
  89 # Print elog messages with "${T}"/README.gentoo contents. They will be
  90 # shown only when package is installed at first time.
  91 # Usually called at pkg_postinst phase.
  92 #
  93 # If you want to show them always, please set FORCE_PRINT_ELOG to a non empty
  94 # value in your ebuild before this function is called.
  95 # This can be useful when, for example, DOC_CONTENTS is modified, then, you can
  96 # rely on specific REPLACING_VERSIONS handling in your ebuild to print messages
  97 # when people update from versions still providing old message.
  98 readme.gentoo_print_elog() {
  99         debug-print-function ${FUNCNAME} "${@}"
 100
 101         if [[ -z "${README_GENTOO_DOC_VALUE}" ]]; then
 102                 die "readme.gentoo_print_elog invoked without matching readme.gentoo_create_doc call!"
 103         elif ! [[ -n "${REPLACING_VERSIONS}" ]] || [[ -n "${FORCE_PRINT_ELOG}" ]]; then
 104                 echo -e "${README_GENTOO_DOC_VALUE}" | while read -r ELINE; do elog "${ELINE}"; done
 105                 elog ""
 106                 elog "(Note: Above message is only printed the first time package is"
 107                 elog "installed. Please look at ${EPREFIX}/usr/share/doc/${PF}/README.gentoo*"
 108                 elog "for future reference)"
 109         fi
 110 }
 111
 112
 113 # @FUNCTION: readme.gentoo_src_install
 114 # @DESCRIPTION:
 115 # Install generated doc file automatically.
 116 readme.gentoo_src_install() {
 117         debug-print-function ${FUNCNAME} "${@}"
 118         default
 119         readme.gentoo_create_doc
 120 }
 121
 122 # @FUNCTION: readme.gentoo_pkg_postinst
 123 # @DESCRIPTION:
 124 # Show elog messages from from just generated doc file.
 125 readme.gentoo_pkg_postinst() {
 126         debug-print-function ${FUNCNAME} "${@}"
 127         readme.gentoo_print_elog
 128 }
 129
 130 fi