GREADME.ECLASS

Section: eclass-manpages (5)
Updated: Oct 2024
Index Return to Main Contents

NAME

greadme.eclass - install a doc file, that will be conditionally shown via elog messages

DESCRIPTION

An eclass for installing a README.gentoo doc file with important information for the user. The content of README.gentoo will shown be via elog messages either on fresh installations or if the contents of the file have changed. Furthermore, the README.gentoo file will be installed under /usr/share/doc/${PF} for later consultation.

This eclass was inspired by readme.gentoo-r1.eclass. The main differences are as follows. Firstly, it only displays the doc file contents if they have changed (unless GREADME_SHOW is set). Secondly, it provides a convenient API to install the doc file via stdin.

inherit greadme

src_install() {
  ...
  greadme_stdin <<-EOF
  This is the content of the created readme doc file.
  EOF
  ...
  if use foo; then
    greadme_stdin --append <<-EOF
    This is conditional readme content, based on USE=foo.
    EOF
  fi
}

If the ebuild overrides the default pkg_preinst or respectively pkg_postinst, then it must call greadme_pkg_preinst and greadme_pkg_postinst explicitly.

SUPPORTED EAPIS

FUNCTIONS

greadme_stdin [--append]: Create the readme doc via stdin. You can use --append to append to an existing readme doc.
greadme_file <file>: Installs the provided file as readme doc.
greadme_pkg_preinst: Performs checks like comparing the readme doc from the image with a potentially existing one in the live system.
greadme_pkg_postinst: Conditionally shows the contents of the readme doc via elog.

ECLASS VARIABLES

GREADME_SHOW: If set to "yes" then unconditionally show the contents of the readme file in pkg_postinst via elog. If set to "no", then do not show the contents of the readme file, even if they have changed.
GREADME_DISABLE_AUTOFORMAT: If non-empty, the readme file will not be automatically formatted.

MAINTAINERS

Florian Schmaus <flow@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

greadme.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, October 07, 2024