eclass/readme.gentoo.eclass

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