Gentoo Development Guide

EUTILS.ECLASS

Section: portage (5)
Updated: Mar 2014
Index Return to Main Contents

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

epause [seconds]

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.

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.

ecvs_clean [list of dirs]

Remove CVS directories recursiveley. Useful when a source tarball contains internal CVS directories. Defaults to $PWD.

esvn_clean [list of dirs]

Remove .svn directories recursiveley. Useful when a source tarball contains internal Subversion directories. Defaults to $PWD.

estack_push <stack> [items to push]

Push any number of items onto the specified stack. Pick a name that is a valid variable (i.e. stick to alphanumerics), and push as many items as you like onto the stack at once.

The following code snippet will echo 5, then 4, then 3, then ...

        estack_push mystack 1 2 3 4 5
        while estack_pop mystack i ; do
                echo "${i}"
        done

estack_pop <stack> [variable]

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:

        eshopts_push -s noglob
        for x in ${foo} ; do
                if ...some check... ; then
                        eshopts_pop
                        return 0
                fi
        done
        eshopts_pop

eshopts_pop

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.

-g0 - keep RCS, ClearCase, Perforce and SCCS happy #24571
--no-backup-if-mismatch - do not leave .orig files behind
-E - automatically remove empty files

EPATCH_EXCLUDE = ""

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:

if ${EPATCH_FORCE} != "yes"
        ??_${ARCH}_foo.${EPATCH_SUFFIX}
else
        *.${EPATCH_SUFFIX}

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.

epatch_user

Applies user-provided patches to the source tree. The patches are taken from /etc/portage/patches/<CATEGORY>/<PF|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.

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.

make_desktop_entry make_desktop_entry(<command>, [name], [icon], [type], [fields])

Make a .desktop file.

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:
          http://standards.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.

 options:
 -s, --size
   !!! must specify to install into /usr/share/icons/... !!!
   size of the icon, like 48 or 48x48
   supported icon sizes are:
   16 22 24 32 36 48 64 72 96 128 192 256 scalable
 -c, --context
   defaults to "apps"
 -t, --theme
   defaults to "hicolor"

icons: list of icons

example 1: doicon foobar.png fuqbar.svg suckbar.png
results in: insinto /usr/share/pixmaps
            doins foobar.png fuqbar.svg suckbar.png

example 2: doicon -s 48 foobar.png fuqbar.png blobbar.png
results in: insinto /usr/share/icons/hicolor/48x48/apps
            doins foobar.png fuqbar.png blobbar.png

newicon [options] <icon> <newname>

Like doicon, install the specified icon as newname.

example 1: newicon foobar.png NEWNAME.png
results in: insinto /usr/share/pixmaps
            newins foobar.png NEWNAME.png

example 2: newicon -s 48 foobar.png NEWNAME.png 
results in: insinto /usr/share/icons/hicolor/48x48/apps
            newins foobar.png NEWNAME.png

strip-linguas [<allow LINGUAS>|<-i|-u> <directories of .po 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.

built_with_use [--hidden] [--missing <action>] [-a|-o] <DEPEND ATOM> <List of USE flags>

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}.

http://bugs.gentoo.org/73450

make_wrapper <wrapper> <target> [chdir] [libpaths] [installpath]

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".

in_iuse <flag>

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

Note that this function should not be used in the global scope.

use_if_iuse <flag>

Return true if the given flag is in USE and IUSE.

Note that this function should not be used in the global scope.

usex <USE flag> [true output] [false output] [true suffix] [false suffix]

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").

prune_libtool_files [--all|--modules]

Locate unnecessary libtool files (.la) and libtool static archives (.a) and remove them from installation image.

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.

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.

MAINTAINERS

base-system@gentoo.org

REPORTING BUGS

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

FILES

/usr/portage/eclass/eutils.eclass

This document was created by man2html, using the manual pages.
Time: 03:25:02 GMT, March 08, 2014