Gentoo Development Guide

EUTILS.ECLASS

NAME

eutils.eclass - many extra (but common) functions that are used in ebuilds

DESCRIPTION

The eutils eclass contains a suite of functions that complement
the ones that ebuild.sh already contain. The idea is that the functions
are not required in all ebuilds but enough utilize them to have a common
home rather than having multiple ebuilds implementing the same thing.

Due to the nature of this eclass, some functions may have maintainers
different from the overall eclass!

FUNCTIONS

eqawarn [message]

Proxy to ewarn for package managers that don't provide eqawarn and use the PM
implementation if available. Reuses PORTAGE_ELOG_CLASSES as set by the dev
profile.

Pop a single item off the specified stack. If a variable is specified,
the popped item is stored there. If no more items are available, return
1, else return 0. See estack_push for more info.

evar_push <variable to save> [more vars to save]

This let's you temporarily modify a variable and then restore it (including
set vs unset semantics). Arrays are not supported at this time.

This is meant for variables where using `local` does not work (such as
exported variables, or only temporarily changing things in a func).

For example:

evar_push LC_ALL
export LC_ALL=C
... do some stuff that needs LC_ALL=C set ...
evar_pop
# You can also save/restore more than one var at a time
evar_push BUTTERFLY IN THE SKY
... do stuff with the vars ...
evar_pop # This restores just one var, SKY
... do more stuff ...
evar_pop 3 # This pops the remaining 3 vars

evar_push_set <variable to save> [new value to store]

This is a handy shortcut to save and temporarily set a variable. If a value
is not specified, the var will be unset.

evar_pop [number of vars to restore]

Restore the variables to the state saved with the corresponding
evar_push call. See that function for more details.

eshopts_push [options to `set` or `shopt`]

Often times code will want to enable a shell option to change code behavior.
Since changing shell options can easily break other pieces of code (which
assume the default state), eshopts_push is used to (1) push the current shell
options onto a stack and (2) pass the specified arguments to set.

If the first argument is '-s' or '-u', we assume you want to call `shopt`
rather than `set` as there are some options only available via that.

A common example is to disable shell globbing so that special meaning/care
may be used with variables/arguments to custom functions. That would be:

Restore the shell options to the state saved with the corresponding
eshopts_push call. See that function for more details.

eumask_push <new umask>

Set the umask to the new value specified while saving the previous
value onto a stack. Useful for temporarily changing the umask.

eumask_pop

Restore the previous umask state.

isdigit <number> [more numbers]

Return true if all arguments are numbers.

EPATCH_SOURCE = "${WORKDIR}/patch"

Default directory to search for patches.

EPATCH_SUFFIX = "patch.bz2"

Default extension for patches (do not prefix the period yourself).

EPATCH_OPTS = ""

Options to pass to patch. Meant for ebuild/package-specific tweaking
such as forcing the patch level (-p#) or fuzz (-F#) factor. Note that
for single patch tweaking, you can also pass flags directly to epatch.

EPATCH_COMMON_OPTS = "-g0 -E --no-backup-if-mismatch"

Common options to pass to `patch`. You probably should never need to
change these. If you do, please discuss it with base-system first to
be sure.

List of patches not to apply. Note this is only file names,
and not the full path. Globs accepted.

EPATCH_SINGLE_MSG = ""

Change the printed message for a single patch.

EPATCH_MULTI_MSG = "Applying various patches (bugfixes/updates) ..."

Change the printed message for multiple patches.

EPATCH_FORCE = "no"

Only require patches to match EPATCH_SUFFIX rather than the extended
arch naming style.

EPATCH_USER_EXCLUDE

List of patches not to apply. Note this is only file names,
and not the full path. Globs accepted.

epatch [options] [patches] [dirs of patches]

epatch is designed to greatly simplify the application of patches. It can
process patch files directly, or directories of patches. The patches may be
compressed (bzip/gzip/etc...) or plain text. You generally need not specify
the -p option as epatch will automatically attempt -p0 to -p4 until things
apply successfully.

If you do not specify any patches/dirs, then epatch will default to the
directory specified by EPATCH_SOURCE.

Any options specified that start with a dash will be passed down to patch
for this specific invocation. As soon as an arg w/out a dash is found, then
arg processing stops.

When processing directories, epatch will apply all patches that match:

The leading ?? are typically numbers used to force consistent patch ordering.
The arch field is used to apply patches only for the host architecture with
the special value of "all" means apply for everyone. Note that using values
other than "all" is highly discouraged -- you should apply patches all the
time and let architecture details be detected at configure/compile time.

If EPATCH_SUFFIX is empty, then no period before it is implied when searching
for patches to apply.

Refer to the other EPATCH_xxx variables for more customization of behavior.

emktemp [temp dir]

Cheap replacement for when debianutils (and thus mktemp)
does not exist on the users system.

edos2unix <file> [more files ...]

A handy replacement for dos2unix, recode, fixdos, etc... This allows you
to remove all of these text utilities from DEPEND variables because this
is a script based solution. Just give it a list of files to convert and
they will all be changed from the DOS CRLF format to the UNIX LF format.

binary: what command does the app run with ?
name: the name that will show up in the menu
icon: the icon to use in the menu entry
this can be relative (to /usr/share/pixmaps) or
a full path to an icon
type: what kind of application is this?
for categories:
https://specifications.freedesktop.org/menu-spec/latest/apa.html
if unset, function tries to guess from package's category
fields: extra fields to append to the desktop file; a printf string

validate_desktop_entries [directories]

Validate desktop entries using desktop-file-utils

make_session_desktop <title> <command> [command args...]

Make a GDM/KDM Session file. The title is the file to execute to start the
Window Manager. The command is the name of the Window Manager.

You can set the name of the file via the ${wm} variable.

domenu <menus>

Install the list of .desktop menu files into the appropriate directory
(/usr/share/applications).

newmenu <menu> <newname>

Like all other new* functions, install the specified menu as newname.

doicon [options] <icons>

Install icon into the icon directory /usr/share/icons or into
/usr/share/pixmaps if "--size" is not set.
This is useful in conjunction with creating desktop/menu files.

Make sure that LINGUAS only contains languages that
a package can support. The first form allows you to
specify a list of LINGUAS. The -i builds a list of po
files found in all the directories and uses the
intersection of the lists. The -u builds a list of po
files found in all the directories and uses the union
of the lists.

preserve_old_lib <libs to preserve> [more libs]

These functions are useful when a lib in your package changes ABI SONAME.
An example might be from libogg.so.0 to libogg.so.1. Removing libogg.so.0
would break packages that link against it. Most people get around this
by using the portage SLOT mechanism, but that is not always a relevant
solution, so instead you can call this from pkg_preinst. See also the
preserve_old_lib_notify function.

preserve_old_lib_notify <libs to notify> [more libs]

Spit helpful messages about the libraries preserved by preserve_old_lib.

Deprecated: Use EAPI 2 use deps in DEPEND|RDEPEND and with has_version calls.

A temporary hack until portage properly supports DEPENDing on USE
flags being enabled in packages. This will check to see if the specified
DEPEND atom was built with the specified list of USE flags. The
--missing option controls the behavior if called on a package that does
not actually support the defined USE flags (aka listed in IUSE).
The default is to abort (call die). The -a and -o flags control
the requirements of the USE flags. They correspond to "and" and "or"
logic. So the -a flag means all listed USE flags must be enabled
while the -o flag means at least one of the listed IUSE flags must be
enabled. The --hidden option is really for internal use only as it
means the USE flag we're checking is hidden expanded, so it won't be found
in IUSE like normal USE flags.

Remember that this function isn't terribly intelligent so order of optional
flags matter.

epunt_cxx [dir to scan]

Many configure scripts wrongly bail when a C++ compiler could not be
detected. If dir is not specified, then it defaults to ${S}.

Create a shell wrapper script named wrapper in installpath
(defaults to the bindir) to execute target (default of wrapper) by
first optionally setting LD_LIBRARY_PATH to the colon-delimited
libpaths followed by optionally changing directory to chdir.

path_exists [-a|-o] <paths>

Check if the specified paths exist. Works for all types of paths
(files/dirs/etc...). The -a and -o flags control the requirements
of the paths. They correspond to "and" and "or" logic. So the -a
flag means all the paths must exist while the -o flag means at least
one of the paths must exist. The default behavior is "and". If no
paths are specified, then the return value is "false".

By default, .la files are removed whenever the static linkage can
either be performed using pkg-config or doesn't introduce additional
flags.

If '--modules' argument is passed, .la files for modules (plugins) are
removed as well. This is usually useful when the package installs
plugins and the plugin loader does not use .la files.

If '--all' argument is passed, all .la files are removed without
performing any heuristic on them. You shouldn't ever use that,
and instead report a bug in the algorithm instead.

The .a files are only removed whenever corresponding .la files state
that they should not be linked to, i.e. whenever these files
correspond to plugins.

Note: if your package installs both static libraries and .pc files
which use variable substitution for -l flags, you need to add
pkg-config to your DEPEND.

optfeature <short description> <package atom to match> [other atoms]

Print out a message suggesting an optional package (or packages) which
provide the described functionality

The following snippet would suggest app-misc/foo for optional foo support,
app-misc/bar or app-misc/baz[bar] for optional bar support
and either both app-misc/a and app-misc/b or app-misc/c for alphabet support.

Sleep for the specified number of seconds (default of 5 seconds). Useful when
printing a message the user should probably be reading and often used in
conjunction with the ebeep function. If the EPAUSE_IGNORE env var is set,
don't wait at all. Defined in EAPIs 0 1 and 2.

ebeep [number of beeps]

Issue the specified number of beeps (default of 5 beeps). Useful when
printing a message the user should probably be reading and often used in
conjunction with the epause function. If the EBEEP_IGNORE env var is set,
don't beep at all. Defined in EAPIs 0 1 and 2.

Proxy to declare usex for package managers or EAPIs that do not provide it
and use the package manager implementation when available (i.e. EAPI >= 5).
If USE flag is set, echo [true output][true suffix] (defaults to "yes"),
otherwise echo [false output][false suffix] (defaults to "no").

EPATCH_USER_SOURCE ?= ${PORTAGE_CONFIGROOT%/}/etc/portage/patches

Location for user patches, see the epatch_user function.
Should be set by the user. Don't set this in ebuilds.

epatch_user

Applies user-provided patches to the source tree. The patches are
taken from /etc/portage/patches/<CATEGORY>/<P-PR|P|PN>[:SLOT]/, where the first
of these three directories to exist will be the one to use, ignoring
any more general directories which might exist as well. They must end
in ".patch" to be applied.

User patches are intended for quick testing of patches without ebuild
modifications, as well as for permanent customizations a user might
desire. Obviously, there can be no official support for arbitrarily
patched ebuilds. So whenever a build log in a bug report mentions that
user patches were applied, the user should be asked to reproduce the
problem without these.

Not all ebuilds do call this function, so placing patches in the
stated directory might or might not work, depending on the package and
the eclasses it inherits and uses. It is safe to call the function
repeatedly, so it is always possible to add a call at the ebuild
level. The first call is the time when the patches will be
applied.

Ideally, this function should be called after gentoo-specific patches
have been applied, so that their code can be modified as well, but
before calls to e.g. eautoreconf, as the user patches might affect
autotool input files as well.

einstalldocs

Install documentation using DOCS and HTML_DOCS.

If DOCS is declared and non-empty, all files listed in it are
installed. The files must exist, otherwise the function will fail.
In EAPI 4 and subsequent EAPIs DOCS may specify directories as well,
in other EAPIs using directories is unsupported.

If DOCS is not declared, the files matching patterns given
in the default EAPI implementation of src_install will be installed.
If this is undesired, DOCS can be set to empty value to prevent any
documentation from being installed.

If HTML_DOCS is declared and non-empty, all files and/or directories
listed in it are installed as HTML docs (using dohtml).

Both DOCS and HTML_DOCS can either be an array or a whitespace-
separated list. Whenever directories are allowed, '<directory>/.' may
be specified in order to install all files within the directory
without creating a sub-directory in docdir.

Passing additional options to dodoc and dohtml is not supported.
If you needed such a thing, you need to call those helpers explicitly.

in_iuse <flag>

Determines whether the given flag is in IUSE. Strips IUSE default prefixes
as necessary.