greadme.eclass

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

8 9

Exported Phases

• pkg_preinst

• pkg_postinst

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.

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 if EAPI < 9.

GREADME_AUTOFORMAT

If non-empty, the readme file will be automatically formatted if EAPI >= 9.

Maintainers

Florian Schmaus <flow@gentoo.org>

Reporting Bugs

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