EUTILS.ECLASS

NAME

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

FUNCTIONS

cdrom_get_cds <cd1 file> [cd2 file] [cd n file]: Useful function to help ebuilds that need to read files off of a CD. This is most commonly used with games. Just specify a list of files, one per cd, that will be used to detect whether the cd is mounted or not. This function handles all the messy details of interaction with the user. Once this function returns, you will have access to the CDROM_ROOT variable. If you want the message to the user to name the CD in a particular way, then export the variable CDROM_NAME before calling this function. If you want to name more than one cd, and you want them to each have a different name, then export the variables CDROM_NAME_1, CDROM_NAME_2, etc... For more information on multi-cd support, see cdrom_load_next_cd.
cdrom_load_next_cd: Some packages are so big they come on multiple CDs. When you're done reading files off a CD and want access to the next one, just call this function. Again, all the messy details of user interaction are taken care of for you. Once this returns, just read the variable CDROM_ROOT for the location of the mounted CD. Note that you can only go forward in the CD list, so make sure you only call this function when you're done using the current CD.
draw_line: Simple function to draw a line consisting of '=' the same length as $*. So if you run `draw_line 1234 5678` you will get back 9 '=' characters in a line.
edos2unix <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.
enewgroup <group> [gid]: This function does not require you to understand how to properly add a group to the system. Just give it a group name to add and enewgroup will do the rest. You may specify the gid for the group or allow the group to allocate the next available one.
enewuser <user> [uid] [shell] [homedir] [groups] [params]: Same as enewgroup, you are not required to understand how to properly add a user to the system. The only required parameter is the username.
Default Values
uid: next available (pass -1 to get default behavior)
shell: /bin/false
homedir: /dev/null
groups: no groups
params: any other parameters useradd(8) accepts; see the manpage for more details
epatch: See the section on epatch below.
gen_usr_ldscript: Generate linker scripts in /usr/lib for dynamic libs in /lib. This is to fix linking problems when you have the .so in /lib, and the .a in /usr/lib. What happens is that in some cases when linking dynamic, the .a in /usr/lib is used instead of the .so in /lib due to gcc/libtool tweaking ld's library search path.
get_number_of_jobs: Checks how many cpu's are present in the system and then sets -j in MAKEOPTS accordingly.
have_NPTL: This function return true if we are using the NPTL pthreads implementation of glibc.
make_desktop_entry <binary> [name] [icon] [type] [path]: Make a little shortcut in GNOME/KDE menus for your application. Just pass the name of the binary to execute and the rest will be done for you. If you want to change the name that will show up in the menu, pass the function a name parameter. If you want to specify an icon (default is ${PN}.png) then pass a name of a graphic file relative to /usr/share/pixmaps/ or the full path to a file. If you want to specify the section of the menu that the icon will install to (rather than the default determined by ${CATEGORY}) then pass a type value (see http://www.freedesktop.org/standards/menu-spec/ for valid values). Finally, if the application needs to start up in a special directory, pass the last value as the full path name.
unpack_makeself [makeselfarchive][byteoffset]: Unpack a makeself archive rather than relying on the script to unpack itself. Useful for when the scripts use old (POSIX) syntax that is no longer supported properly. If you don't specify a file to unpack, then ${A} is used instead. If you don't specify the offset, then the proper value will be located by searching the makeself script. For more information on makeself archives, please visit: http://www.megastep.org/makeself/
unpack_pdv <pdv archive> <sizeof(off_t)>: Unpack a pdv archive rather than relying on the binary to unpack itself. Useful for when the static binary crashes randomly on systems and for when the binary doesn't provide a non-interactive extraction process. You have to specify the off_t size since I (vapier@gentoo.org) am unaware of a way to extract that information out of the binary executable automatically. The value you pass is the size of the off_t type (in bytes) on the machine that built the pdv archive. If you don't know the value yourself, try guessing the values 2, 4, or 8. For more information on pdv archives, please visit: http://pdv.sourceforge.net/

EPATCH

ABOUT

epatch is designed to make patching easy. It does all the common checks that a developer would do with the patch(1) command and then some. It will attempt to apply the patch for a range of offset values (-p0 to -p5, all relative to the working directory when epatch was called). If the patch fails to apply (by testing via dryruns), then patch will stop the emerge process by calling die. You will be given a log file of the output of the patch attempt so as to ease debugging. The output of a successful patch is a pretty formatted message showing what patches were applied. epatch can be used for bulk patching or for just one or two patches. Additionally, it can handle patches in bzip2, gzip, compress (Z), and zip formats.

USAGE

epatch <patch file>: The most common and easiest way to use epatch is by just giving it the full path to a patch file.
epatch <directory>: A more powerful use is to fill a directory with patches and then let epatch apply all the patches inside it. The patches must be in the format ??_${ARCH}_foo.${EPATCH_SUFFIX}. This ensures that there are a set order, and you can have ARCH specific patches.

01_all_misc-fix.patch.bz2

apply the misc-fix patch first for all arches
02_sparc_another-fix.patch.bz2

apply the another-fix patch second but only on sparc

VARIABLES

EPATCH_SOURCE = ${WORKDIR}/patch: The patch or directory of patches for epatch to apply. This is set automatically if you call epatch with a parameter.
EPATCH_SUFFIX = patch.bz2: When applying bulk patches this is the suffix that all patches will have.
EPATCH_OPTS =: Any extra options you may want to pass to patch(1). We can't think of everything so why restrict you :). The default is "" of course.
EPATCH_EXCLUDE =: A space delimited list (well, actually $IFS delimited ...) of patch files to skip while bulk patching. Use only file names, not full paths.
EPATCH_SINGLE_MSG = Applying <patch name>: If you only apply a single patch, then instead of displaying the default message you can change it to say anything you want, even 'Dont call me Radio Unit 51', if you are so inclined of course.
EPATCH_FORCE = [yes|no]: This allows you to apply all patches in EPATCH_SOURCE even if they dont match the ??_${ARCH}_foo.${EPATCH_SUFFIX} file naming convention. By default we want you to use the above convention.

REPORTING BUGS

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

FILES

/usr/portage/eclass/eutils.eclass

AUTHORS

Mike Frysinger <vapier@gentoo.org>

CVS HEADER

$Header: /var/cvsroot/gentoo-src/portage/man/eutils.eclass.5,v 1.5 2004/09/17 00:17:10 vapier Exp $