man/ebuild.5

   1 .TH "EBUILD" "5" "Jun 2007" "Portage 2.1.3" "Portage"
   2 .SH "NAME"
   3 ebuild \- the internal format, variables, and functions in an ebuild script
   4 .SH "DESCRIPTION"
   5 The
   6 .BR ebuild (1)
   7 program accepts a single ebuild script as an argument.  This script
   8 contains variables and commands that specify how to download, unpack,
   9 patch, compile, install and merge a particular software package from
  10 its original sources.  In addition to all of this, the ebuild script
  11 can also contain pre/post install/remove commands, as required.  All
  12 ebuild scripts are written in bash.
  13 .SH "EXAMPLES"
  14 Here's a simple example ebuild:
  15
  16 .DS
  17 .nf
  18 # Copyright 1999\-2007 Gentoo Foundation
  19 # Distributed under the terms of the GNU General Public License v2
  20 # $Header: $
  21
  22 inherit some_eclass another_eclass
  23
  24 DESCRIPTION="Super\-useful stream editor (sed)"
  25 HOMEPAGE="http://www.gnu.org/software/sed/sed.html"
  26 SRC_URI="ftp://alpha.gnu.org/pub/gnu/sed/${P}.tar.gz"
  27
  28 LICENSE="GPL\-2"
  29 SLOT="0"
  30 KEYWORDS="~x86"
  31 IUSE=""
  32
  33 RDEPEND=""
  34 DEPEND="nls? ( sys-devel/gettext )"
  35
  36 src_compile() {
  37         econf \\
  38                 \-\-bindir=/bin \\
  39                 || die "could not configure"
  40         emake || die "emake failed"
  41 }
  42
  43 src_install() {
  44         emake install DESTDIR="${D}" || die "Install failed"
  45         dodoc NEWS README* THANKS AUTHORS BUGS ChangeLog
  46 }
  47 .fi
  48 .SH "VARIABLES"
  49 .TP
  50 .B MISC USAGE NOTES
  51 \- All variables defined in \fBmake.conf\fR(5) are available for use in
  52 ebuilds (such as the PORTAGE* and PORTDIR* variables)
  53 .br
  54 \- When assigning values to variables in ebuilds, you \fBcannot have a
  55 space\fR between the variable name and the equal sign.
  56 .TP
  57 .B P
  58 This variable contains the package name without the ebuild revision.
  59 This variable must NEVER be modified.
  60 .br
  61 \fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$P\fR=='\fIxfree\-4.2.1\fR'
  62 .TP
  63 .B PN
  64 Contains the name of the script without the version number.
  65 .br
  66 \fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PN\fR=='\fIxfree\fR'
  67 .TP
  68 .B PV
  69 Contains the version number without the revision.
  70 .br
  71 \fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PV\fR=='\fI4.2.1\fR'
  72 .TP
  73 .B PR
  74 Contains the revision number or 'r0' if no revision number exists.
  75 .br
  76 \fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PR\fR=='\fIr2\fR'
  77 .TP
  78 .B PVR
  79 Contains the version number with the revision.
  80 .br
  81 \fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PVR\fR=='\fI4.2.1\-r2\fR'
  82 .TP
  83 .B PF
  84 Contains the full package name \fI[PN]\-[PVR]\fR
  85 .br
  86 \fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PF\fR=='\fIxfree\-4.2.1\-r2\fR'
  87 .TP
  88 .B CATEGORY
  89 Contains the package category name.
  90 .TP
  91 .B A
  92 Contains all source files required for the package.  This variable must
  93 not be defined. It is autogenerated from the \fISRC_URI\fR variable.
  94 .TP
  95 \fBWORKDIR\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/work"\fR
  96 Contains the path to the package build root.  Do not modify this variable.
  97 .TP
  98 \fBFILESDIR\fR = \fI"${PORTDIR}/${CATEGORY}/${PN}/files"\fR
  99 Contains the path to the 'files' sub folder in the package specific
 100 location in the portage tree.  Do not modify this variable.
 101 .TP
 102 \fBS\fR = \fI"${WORKDIR}/${P}"\fR
 103 Contains the path to the temporary \fIbuild directory\fR.  This variable
 104 is used by the functions \fIsrc_compile\fR and \fIsrc_install\fR.  Both
 105 are executed with \fIS\fR as the current directory.  This variable may
 106 be modified to match the extraction directory of a tarball for the package.
 107 .TP
 108 \fBT\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/temp"\fR
 109 Contains the path to a \fItemporary directory\fR.  You may use this for
 110 whatever you like.
 111 .TP
 112 \fBD\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/image"\fR
 113 Contains the path to the temporary \fIinstall directory\fR.  Every write
 114 operation that does not involve the helper tools and functions (found below)
 115 should be prefixed with ${D}.  Do not modify this variable.
 116 .TP
 117 .B PORTAGE_LOG_FILE
 118 Contains the path of the build log. If \fBPORT_LOGDIR\fR variable is unset then
 119 \fBPORTAGE_LOG_FILE\fR=\fB"${T}/build.log"\fR.
 120 .TP
 121 \fBROOT\fR = \fI"/"\fR
 122 Contains the path that portage should use as the root of the live filesystem.
 123 When packages wish to make changes to the live filesystem, they should do so in
 124 the tree prefixed by ${ROOT}.  Do not modify this variable.
 125 .TP
 126 \fBDESCRIPTION\fR = \fI"A happy little package"\fR
 127 Should contain a short description of the package.
 128 .TP
 129 \fBSRC_URI\fR = \fI"http://happy.com/little/${P}.tar.gz"\fR
 130 Contains a list of URI's for the required source files.  It can contain
 131 multiple URI's for a single source file.  The list is processed in order
 132 if the file was not found on any of the \fIGENTOO_MIRRORS\fR.
 133 .TP
 134 \fBHOMEPAGE\fR = \fI"http://happy.com/"\fR
 135 Should contain a list of URL's for the sources main sites and other further
 136 package dependent information.
 137 .TP
 138 \fBKEYWORDS\fR = \fI[\-~][x86,ppc,sparc,mips,alpha,arm,hppa]\fR
 139 Should contain appropriate list of arches that the ebuild is know to
 140 work/not work.  By default if you do not know if an ebuild runs under
 141 a particular arch simply omit that KEYWORD.  If the ebuild will not
 142 work on that arch include it as \-ppc for example.  If the ebuild is
 143 being submitted for inclusion, it must have ~arch set for architectures
 144 where it has been PROVEN TO WORK.  (Packages KEYWORDed this way may be
 145 unmasked for testing by setting ACCEPT_KEYWORDS="~arch" on the command
 146 line, or in \fBmake.conf\fR(5)) For an authoritative list please review
 147 /usr/portage/profiles/arch.list.  Please keep this list in alphabetical order.
 148 .TP
 149 \fBSLOT\fR
 150 This sets the SLOT for packages that may need to have multiple versions
 151 co\-exist.  By default you should set \fBSLOT\fR="0".  If you are unsure, then
 152 do not fiddle with this until you seek some guidance from some guru.  This
 153 value should \fINEVER\fR be left undefined.
 154 .TP
 155 \fBLICENSE\fR
 156 This should be a space delimited list of licenses that the package falls
 157 under.  This \fB_must_\fR be set to a matching license in
 158 /usr/portage/licenses/. If the license does not exist in portage yet, you
 159 must add it first.
 160 .TP
 161 \fBIUSE\fR
 162 This should be a list of any and all USE flags that are leveraged within
 163 your build script.  The only USE flags that should not be listed here are
 164 arch related flags (see \fBKEYWORDS\fR).
 165 .TP
 166 \fBDEPEND\fR
 167 This should contain a list of all packages that are required for the
 168 program to compile.
 169 .RS
 170 .TP
 171 .B DEPEND Atoms
 172 A depend atom is simply a dependency that is used by portage when calculating
 173 relationships between packages.  Please note that if the atom has not already
 174 been emerged, then the latest version available is matched.
 175 .RS
 176 .TP
 177 .B Atom Bases
 178 The base atom is just a full category/packagename.  Hence, these are base atoms:
 179
 180 .nf
 181 .I sys\-apps/sed
 182 .I sys\-libs/zlib
 183 .I net\-misc/dhcp
 184 .fi
 185 .TP
 186 .B Atom Versions
 187 It is nice to be more specific and say that only certain versions of atoms are
 188 acceptable.  Note that versions must be combined with a prefix (see below).
 189 Hence you may add a version number as a postfix to the base:
 190
 191 .nf
 192 sys\-apps/sed\fI\-4.0.5\fR
 193 sys\-libs/zlib\fI\-1.1.4\-r1\fR
 194 net\-misc/dhcp\fI\-3.0_p2\fR
 195 .fi
 196
 197 Versions are normally made up of two or three numbers separated by periods, such
 198 as 1.2 or 4.5.2.  This string may be followed by a character such as 1.2a or
 199 4.5.2z.  Note that this letter is \fBnot\fR meant to indicate alpha, beta,
 200 etc... status.  For that, use the optional suffix; either _alpha, _beta, _pre
 201 (pre\-release), _rc (release candidate), or _p (patch).  This means for the
 202 3rd pre\-release of a package, you would use something like 1.2_pre3.  The
 203 suffixes here can be arbitrarily chained without limitation.
 204 .TP
 205 .B Atom Prefix Operators [> >= = <= <]
 206 Sometimes you want to be able to depend on general versions rather than specifying
 207 exact versions all the time.  Hence we provide standard boolean operators:
 208
 209 .nf
 210 \fI>\fRmedia\-libs/libgd\-1.6
 211 \fI>=\fRmedia\-libs/libgd\-1.6
 212 \fI=\fRmedia\-libs/libgd\-1.6
 213 \fI<=\fRmedia\-libs/libgd\-1.6
 214 \fI<\fRmedia\-libs/libgd\-1.6
 215 .fi
 216 .TP
 217 .B Extended Atom Prefixes [!~] and Postfixes [*]
 218 Now to get even fancier, we provide the ability to define blocking packages and
 219 version range matching.  Also note that these extended prefixes/postfixes may
 220 be combined in any way with the atom classes defined above.  Here are some common
 221 examples you may find in the portage tree:
 222
 223 .nf
 224 \fI!\fRapp\-text/dos2unix
 225 =dev\-libs/glib\-2\fI*\fR
 226 \fI!\fR=net\-fs/samba\-2\fI*\fR
 227 \fI~\fRnet\-libs/libnet\-1.0.2a
 228 .fi
 229
 230 \fI!\fR means block packages from being installed at the same time.
 231 .br
 232 \fI*\fR means match any version of the package so long as the specified base
 233 is matched.  So with a version of '2*', we can match '2.1', '2.2', '2.2.1',
 234 etc... and not match version '1.0', '3.0', '4.1', etc...
 235 .br
 236 \fI~\fR means match any revision of the base version specified.  So in the
 237 above example, we would match versions '1.0.2a', '1.0.2a\-r1', '1.0.2a\-r2',
 238 etc...
 239 .RE
 240 .TP
 241 .B Dynamic DEPENDs
 242 Sometimes programs may depend on different things depending on the USE
 243 variable.  Portage offers a few options to handle this.  Note that when
 244 using the following syntaxes, each case is considered as 1 Atom in the
 245 scope it appears.  That means that each Atom both conditionally include
 246 multiple Atoms and be nested to an infinite depth.
 247 .RS
 248 .TP
 249 .B usevar? ( DEPEND Atom )
 250 To include the jpeg library when the user has jpeg in \fBUSE\fR, simply use the
 251 following syntax:
 252 .br
 253 .B jpeg? ( media\-libs/jpeg )
 254 .TP
 255 .B !usevar? ( Atom )
 256 If you want to include a package only if the user does not have a certain option
 257 in their \fBUSE\fR variable, then use the following syntax:
 258 .br
 259 .B !nophysfs? ( dev\-games/physfs )
 260 .br
 261 This is often useful for those times when you want to want to add optional support
 262 for a feature and have it enabled by default.
 263 .TP
 264 .B usevar? ( Atom if true ) !usevar? ( Atom if false )
 265 For functionality like the tertiary operator found in C you must use
 266 two statements, one normal and one inverted.  If a package uses
 267 GTK2 or GTK1, but not both, then you can handle that like this:
 268 .br
 269 .B gtk2? ( =x11\-libs/gtk+\-2* ) !gtk2? ( =x11\-libs/gtk+\-1* )
 270 .br
 271 That way the default is the superior GTK2 library.
 272 .TP
 273 .B || ( Atom Atom ... )
 274 When a package can work with a few different packages but a virtual is not
 275 appropriate, this syntax can easily be used.
 276 .nf
 277 .B || (
 278 .B      app\-games/unreal\-tournament
 279 .B      app\-games/unreal\-tournament\-goty
 280 .B )
 281 .fi
 282 Here we see that unreal\-tournament has a normal version and it has a goty
 283 version.  Since they provide the same base set of files, another package can
 284 use either.  Adding a virtual is inappropriate due to the small scope of it.
 285 .br
 286 Another good example is when a package can be built with multiple video
 287 interfaces, but it can only ever have just one.
 288 .nf
 289 .B || (
 290 .B      sdl? ( media\-libs/libsdl )
 291 .B      svga? ( media\-libs/svgalib )
 292 .B      opengl? ( virtual/opengl )
 293 .B      ggi? ( media\-libs/libggi )
 294 .B      virtual/x11
 295 .B )
 296 .fi
 297 Here only one of the packages will be chosen, and the order of preference is
 298 determined by the order in which they appear.  So sdl has the best chance of
 299 being chosen, followed by svga, then opengl, then ggi, with a default of X if
 300 the user does not specify any of the previous choices.
 301 .br
 302 Note that if any of the packages listed are already merged, the package manager
 303 will use that to consider the dependency satisfied.
 304 .RE
 305
 306 .RE
 307 .TP
 308 \fBRDEPEND\fR
 309 This should contain a list of all packages that are required for this
 310 program to run (aka runtime depend).  If this is not set, then it
 311 defaults to the value of \fBDEPEND\fR.
 312 .br
 313 You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR.
 314 .TP
 315 \fBPDEPEND\fR
 316 This should contain a list of all packages that should be merged after this one,
 317 but may be merged before if need be.
 318 .br
 319 You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR.
 320 .TP
 321 \fBRESTRICT\fR = \fI[strip,mirror,fetch,userpriv]\fR
 322 This should be a space delimited list of portage features to restrict.
 323 You may use conditional syntax to vary restrictions as seen above in DEPEND.
 324 .PD 0
 325 .RS
 326 .TP
 327 .I binchecks
 328 Disable all QA checks for binaries.  This should ONLY be used in packages
 329 for which binary checks make no sense (linux\-headers and kernel\-sources, for
 330 example, can safely be skipped since they have no binaries).  If the binary
 331 checks need to be skipped for other reasons (such as proprietary binaries),
 332 see the \fBQA CONTROL VARIABLES\fR section for more specific exemptions.
 333 .TP
 334 .I bindist
 335 Distribution of binary packages is restricted.
 336 .TP
 337 .I fetch
 338 like \fImirror\fR but the files will not be fetched via \fBSRC_URI\fR either.
 339 .TP
 340 .I mirror
 341 files in \fBSRC_URI\fR will not be downloaded from the \fBGENTOO_MIRRORS\fR.
 342 .TP
 343 .I primaryuri
 344 fetch from URL's in \fBSRC_URI\fR before \fBGENTOO_MIRRORS\fR.
 345 .TP
 346 .I strip
 347 final binaries/libraries will not be stripped of debug symbols.
 348 .TP
 349 .I test
 350 do not run src_test even if user has \fBFEATURES\fR=test.
 351 .TP
 352 .I userpriv
 353 Disables userpriv for specific packages.
 354 .RE
 355 .PD 1
 356 .TP
 357 \fBPROVIDE\fR = \fI"virtual/TARGET"\fR
 358 This variable should only be used when a package provides a virtual target.
 359 For example, blackdown\-jdk and sun\-jdk provide \fIvirtual/jdk\fR.  This
 360 allows for packages to depend on \fIvirtual/jdk\fR rather than on blackdown
 361 or sun specifically.
 362 .SH "QA CONTROL VARIABLES"
 363 .TP
 364 .B USAGE NOTES
 365 Several QA variables are provided which allow an ebuild to manipulate some
 366 of the QA checks performed by portage.  Use of these variables in ebuilds
 367 should be kept to an absolute minimum otherwise they defeat the purpose
 368 of the QA checks, and their use is subject to agreement of the QA team.
 369 They are primarily intended for use by ebuilds that install closed\-source
 370 binary objects that cannot be altered.
 371 .br
 372 Note that objects that violate these rules may fail on some architectures.
 373 .TP
 374 \fBQA_TEXTRELS\fR
 375 This variable can be set to a list of file paths, relative to the image
 376 directory, of files that contain text relocations that cannot be eliminated.
 377 The paths may contain regular expressions.
 378 .br
 379 This variable is intended to be used on closed\-source binary objects that
 380 cannot be altered.
 381 .TP
 382 \fBQA_EXECSTACK\fR
 383 This should contain a list of file paths, relative to the image directory, of
 384 objects that require executable stack in order to run.
 385 The paths may contain regular expressions.
 386 .br
 387 This variable is intended to be used on objects that truly need executable
 388 stack (i.e. not those marked to need it which in fact do not).
 389 .TP
 390 \fBQA_WX_LOAD\fR
 391 This should contain a list of file paths, relative to the image directory, of
 392 files that contain writable and executable segments.  These are rare.
 393 The paths may contain regular expressions.
 394 .SH "PORTAGE DECLARATIONS"
 395 .TP
 396 .B inherit
 397 Inherit is portage's maintenance of extra classes of functions that are
 398 external to ebuilds and provided as inheritable capabilities and data. They
 399 define functions and set data types as drop\-in replacements, expanded, and
 400 simplified routines for extremely common tasks to streamline the build
 401 process.  Inherit may only be called once in an ebuild and it may \fBnever be
 402 wrapped within any conditionals\fR of any kind.  Specification of the eclasses
 403 contains only their name and not the \fI.eclass\fR extension.  Also note that
 404 the inherit statement must come before other variable declarations.
 405 .SH "FUNCTIONS"
 406 .TP
 407 .B pkg_nofetch
 408 If you turn on \fIfetch\fR in \fBRESTRICT\fR, then this function will be
 409 run when the files in \fBSRC_URI\fR cannot be found.  Useful for
 410 displaying information to the user on *how* to obtain said files.  All
 411 you have to do is output a message and let the function return.  Do not
 412 end the function with a call to \fBdie\fR.
 413 .TP
 414 .B pkg_setup
 415 This function can be used if the package needs specific setup actions or
 416 checks to be preformed before anything else.
 417 .br
 418 Initial working directory of ${PORTAGE_TMPDIR}.
 419 .TP
 420 .B src_unpack
 421 This function is used to unpack all the sources in \fIA\fR to \fIWORKDIR\fR.
 422 If not defined in the \fIebuild script\fR it calls \fIunpack ${A}\fR. Any
 423 patches and other pre configure/compile modifications should be done here.
 424 .br
 425 Initial working directory of $WORKDIR.
 426 .TP
 427 .B src_compile
 428 All necessary steps for configuration and compilation should be done in here.
 429 .br
 430 Initial working directory of $S.
 431 .TP
 432 .B src_test
 433 Run all package specific test cases.  The default is to run 'make check'
 434 followed 'make test'.
 435 .br
 436 Initial working directory of $S.
 437 .TP
 438 .B src_install
 439 Should contain everything required to install the package in the temporary
 440 \fIinstall directory\fR.
 441 .br
 442 Initial working directory of $S.
 443 .TP
 444 .B pkg_preinst pkg_postinst
 445 All modifications required on the live\-filesystem before and after the
 446 package is merged should be placed here. Also commentary for the user
 447 should be listed here as it will be displayed last.
 448 .br
 449 Initial working directory of $PWD.
 450 .TP
 451 .B pkg_prerm pkg_postrm
 452 Like the pkg_*inst functions but for unmerge.
 453 .br
 454 Initial working directory of $PWD.
 455 .TP
 456 .B pkg_config
 457 This function should contain optional basic configuration steps.
 458 .br
 459 Initial working directory of $PWD.
 460 .SH "HELPER FUNCTIONS: GENERAL"
 461 .TP
 462 \fBdie\fR \fI[reason]\fR
 463 Causes the current emerge process to be aborted. The final display will
 464 include \fIreason\fR.
 465 .TP
 466 \fBuse\fR \fI<USE item>\fR
 467 If \fIUSE item\fR is in the \fBUSE\fR variable, the function will silently
 468 return 0 (aka shell true).  If \fIUSE item\fR is not in the \fBUSE\fR
 469 variable, the function will silently return 1 (aka shell false).  \fBusev\fR
 470 is a verbose version of \fBuse\fR.
 471 .RS
 472 .TP
 473 .I Example:
 474 .nf
 475 if use gnome ; then
 476         guiconf="\-\-enable\-gui=gnome \-\-with\-x"
 477 elif use gtk ; then
 478         guiconf="\-\-enable\-gui=gtk \-\-with\-x"
 479 elif use X ; then
 480         guiconf="\-\-enable\-gui=athena \-\-with\-x"
 481 else
 482         # No gui version will be built
 483         guiconf=""
 484 fi
 485 .fi
 486 .RE
 487 .TP
 488 \fBuse_with\fR \fI<USE item>\fR \fI[configure name]\fR \fI[configure opt]\fR
 489 Useful for creating custom options to pass to a configure script. If \fIUSE
 490 item\fR is in the \fBUSE\fR variable and a \fIconfigure opt\fR is specified,
 491 then the string \fI\-\-with\-[configure name]=[configure opt]\fR will be echoed.
 492 If \fIconfigure opt\fR is not specified, then just \fI\-\-with\-[configure
 493 name]\fR will be echoed.  If \fIUSE item\fR is not in the \fBUSE\fR variable,
 494 then the string \fI\-\-without\-[configure name]\fR will be echoed. If
 495 \fIconfigure name\fR is not specified, then \fIUSE item\fR will be used in
 496 its place.
 497 .RS
 498 .TP
 499 .I Examples:
 500 .nf
 501 USE="opengl"
 502 myconf=$(use_with opengl)
 503 (myconf now has the value "\-\-with\-opengl")
 504
 505 USE="jpeg"
 506 myconf=$(use_with jpeg libjpeg)
 507 (myconf now has the value "\-\-with\-libjpeg")
 508
 509 USE=""
 510 myconf=$(use_with jpeg libjpeg)
 511 (myconf now has the value "\-\-without\-libjpeg")
 512
 513 USE="sdl"
 514 myconf=$(use_with sdl SDL all\-plugins)
 515 (myconf now has the value "\-\-with\-SDL=all\-plugins")
 516 .fi
 517 .RE
 518 .TP
 519 \fBuse_enable\fR \fI<USE item>\fR \fI[configure name]\fR \fI[configure opt]\fR
 520 Same as \fBuse_with\fR above, except that the configure options are
 521 \fI\-\-enable\-\fR instead of \fI\-\-with\-\fR and \fI\-\-disable\-\fR instead of
 522 \fI\-\-without\-\fR.
 523 .TP
 524 \fBhas\fR \fI<item>\fR \fI<item list>\fR
 525 If \fIitem\fR is in \fIitem list\fR, then \fIitem\fR is echoed and \fBhas\fR
 526 returns 0.  Otherwise, nothing is echoed and 1 is returned. As indicated with
 527 use, there is a non\-echoing version \fBhasq\fR. Please use \fBhasq\fR in all
 528 places where output is to be disregarded. Never use the output for calculation.
 529 .br
 530 The \fIitem list\fR is delimited by the \fIIFS\fR variable.  This variable
 531 has a default value of ' ', or a space.  It is a \fBbash\fR(1) setting.
 532 .TP
 533 \fBhas_version\fR \fI<category/package\-version>\fR
 534 Check to see if \fIcategory/package\-version\fR is installed on the system.
 535 The parameter accepts all values that are acceptable in the \fBDEPEND\fR
 536 variable.  The function returns 0 if \fIcategory/package\-version\fR is
 537 installed, 1 otherwise.
 538 .TP
 539 \fBbest_version\fR \fI<package name>\fR
 540 This function will look up \fIpackage name\fR in the database of currently
 541 installed programs and echo the "best version" of the package that is
 542 currently installed.
 543 .RS
 544 .TP
 545 .I Example:
 546 VERINS="$(best_version net\-ftp/glftpd)"
 547 .br
 548 (VERINS now has the value "net\-ftp/glftpd\-1.27" if glftpd\-1.27 is installed)
 549 .RE
 550 .SH "HELPER FUNCTIONS: OUTPUT"
 551 .TP
 552 \fBeinfo\fR \fI"disposable message"\fR
 553 Same as \fBelog\fR, but should be used when the message isn't important to the
 554 user (like progress or status messages during the build process).
 555 .TP
 556 \fBelog\fR \fI"informative message"\fR
 557 If you need to display a message that you wish the user to read and take
 558 notice of, then use \fBelog\fR.  It works just like \fBecho\fR(1), but
 559 adds a little more to the output so as to catch the user's eye. The message
 560 will also be logged by portage for later review.
 561 .TP
 562 \fBewarn\fR \fI"warning message"\fR
 563 Same as \fBeinfo\fR, but should be used when showing a warning to the user.
 564 .TP
 565 \fBeerror\fR \fI"error message"\fR
 566 Same as \fBeinfo\fR, but should be used when showing an error to the user.
 567 .TP
 568 \fBebegin\fR \fI"helpful message"\fR
 569 Like \fBeinfo\fR, we output a \fIhelpful message\fR and then hint that the
 570 following operation may take some time to complete.  Once the task is
 571 finished, you need to call \fBeend\fR.
 572 .TP
 573 \fBeend\fR \fI<status>\fR \fI["error message"]\fR
 574 Followup the \fBebegin\fR message with an appropriate "OK" or "!!" (for
 575 errors) marker.  If \fIstatus\fR is non\-zero, then the additional \fIerror
 576 message\fR is displayed.
 577 .SH "HELPER FUNCTIONS: UNPACK"
 578 .TP
 579 \fBunpack\fR \fI<source>\fR \fI[list of more sources]\fR
 580 This function uncompresses and/or untars a list of sources into the current
 581 directory. The function will append \fIsource\fR to the \fBDISTDIR\fR variable.
 582 .SH "HELPER FUNCTIONS: COMPILE"
 583 .TP
 584 \fBeconf\fR \fI[configure options]\fR
 585 This is used as a replacement for configure.  Performs:
 586 .nf
 587 ${\fIECONF_SOURCE\fR:-.}/configure \\
 588         \-\-prefix=/usr \\
 589         \-\-host=${CHOST} \\
 590         \-\-mandir=/usr/share/man \\
 591         \-\-infodir=/usr/share/info \\
 592         \-\-datadir=/usr/share \\
 593         \-\-sysconfdir=/etc \\
 594         \-\-localstatedir=/var/lib \\
 595         \fI${EXTRA_ECONF}\fR \\
 596         \fIconfigure options\fR
 597 .fi
 598 Note that the \fIEXTRA_ECONF\fR is for users only, not for ebuild
 599 writers.  If you wish to pass more options to configure, just pass the
 600 extra arguements to \fBeconf\fR.
 601 .TP
 602 \fBemake\fR \fI[make options]\fR
 603 This is used as a replacement for make.  Performs 'make ${MAKEOPTS}
 604 \fImake options\fR' (as set in /etc/make.globals), default is MAKEOPTS="\-j2".
 605
 606 \fB***warning***\fR
 607 .br
 608 if you are going to use \fBemake\fR, make sure your build is happy with
 609 parallel makes (make \-j2).  It should be tested thoroughly as parallel
 610 makes are notorious for failing _sometimes_ but not always.  If you determine
 611 that your package fails to build in parallel, and you are unable to resolve
 612 the issue, then you should run '\fBemake\fR \-j1' instead of 'make'.
 613 .SH "HELPER FUNCTIONS: INSTALL"
 614 .TP
 615 \fBeinstall\fR \fI[make options]\fR
 616 This is used as a replacement for make install.  Performs:
 617 .nf
 618 make \\
 619         prefix=${D}/usr \\
 620         datadir=${D}/usr/share \\
 621         infodir=${D}/usr/share/info \\
 622         localstatedir=${D}/var/lib \\
 623         mandir=${D}/usr/share/man \\
 624         sysconfdir=${D}/etc \\
 625         \fI${EXTRA_EINSTALL}\fR \\
 626         \fImake options\fR \\
 627         install
 628 .fi
 629 Please do \fBnot\fR use this in place of 'emake install DESTDIR=${D}'.
 630 That is the preferred way of installing make\-based packages.  Also, do
 631 not utilize the \fIEXTRA_EINSTALL\fR variable since it is for users.
 632
 633 .PD 0
 634 .TP
 635 .B prepall
 636 .TP
 637 .B prepalldocs
 638 .TP
 639 .B prepallinfo
 640 .TP
 641 .B prepallman
 642 .TP
 643 .B prepallstrip
 644 .PD 1
 645 Useful for when a package installs into \fB${D}\fR via scripts
 646 (i.e. makefiles).  If you want to be sure that libraries are executable,
 647 aclocal files are installed into the right place, doc/info/man files are
 648 all compressed, and that executables are all stripped of debugging symbols,
 649 then use these suite of functions.
 650 .RS
 651 .PD 0
 652 .TP
 653 .B prepall:
 654 Runs \fBprepallman\fR, \fBprepallinfo\fR, \fBprepallstrip\fR, sets
 655 libraries +x, and then checks aclocal directories.  Please note this
 656 does \fI*not*\fR run \fBprepalldocs\fR.
 657 .TP
 658 .B prepalldocs:
 659 Compresses all doc files in ${D}/usr/share/doc.
 660 .TP
 661 .B prepallinfo:
 662 Compresses all info files in ${D}/usr/share/info.
 663 .TP
 664 .B prepallman:
 665 Compresses all man files in ${D}/usr/share/man.
 666 .TP
 667 .B prepallstrip:
 668 Strips all executable files of debugging symboles.  This includes libraries.
 669 .RE
 670
 671 .TP
 672 \fBprepinfo\fR \fI[dir]\fR
 673 .TP
 674 \fBprepman\fR \fI[dir]\fR
 675 .TP
 676 \fBprepstrip\fR \fI[dir]\fR
 677 .PD 1
 678 Similiar to the \fBprepall\fR functions, these are subtle in their differences.
 679 .RS
 680 .PD 0
 681 .TP
 682 .B prepinfo:
 683 If a \fIdir\fR is not specified, then \fBprepinfo\fR will assume the dir
 684 \fIusr\fR. \fBprepinfo\fR will then compress all the files in
 685 ${D}/\fIdir\fR/info.
 686 .TP
 687 .B prepman:
 688 If a \fIdir\fR is not specified, then \fBprepman\fR will assume the dir
 689 \fIusr\fR. \fBprepman\fR will then compress all the files in
 690 ${D}/\fIdir\fR/man/*/.
 691 .TP
 692 .B prepstrip:
 693 All the files found in ${D}/\fIdir\fR will be stripped.  You may specify
 694 multiple directories.
 695 .RE
 696 .PD 1
 697 .TP
 698 \fBdosed\fR \fI"s:orig:change:g" <filename>\fR
 699 Performs sed (including cp/mv \fIfilename\fR) on \fIfilename\fR.
 700 .br
 701 .BR 'dosed\ "s:/usr/local:/usr:g"\ /usr/bin/some\-script'
 702 runs sed on ${D}/usr/bin/some\-script
 703 .TP
 704 \fBdodir\fR \fI<path>\fR
 705 Creates a directory inside of ${D}.
 706 .br
 707 .BR 'dodir\ /usr/lib/apache'
 708 creates ${D}/usr/lib/apache.  Note that the do* functions will run
 709 \fBdodir\fR for you.
 710 .TP
 711 \fBdiropts\fR \fI[options for install(1)]\fR
 712 Can be used to define options for the install function used in
 713 \fBdodir\fR.  The default is \fI\-m0755\fR.
 714 .TP
 715 \fBinto\fR \fI<path>\fR
 716 Sets the root (\fIDESTTREE\fR) for other functions like \fBdobin\fR,
 717 \fBdosbin\fR, \fBdoman\fR, \fBdoinfo\fR, \fBdolib\fR.
 718 .br
 719 The default root is /usr.
 720 .TP
 721 \fBkeepdir\fR \fI<path>\fR
 722 Tells portage to leave a directory behind even if it is empty.  Functions
 723 the same as \fBdodir\fR.
 724 .TP
 725 \fBdobin\fR \fI<binary> [list of more binaries]\fR
 726 Installs a \fIbinary\fR or a list of binaries into \fIDESTTREE\fR/bin.
 727 Creates all necessary dirs.
 728 .TP
 729 \fBdosbin\fR \fI<binary> [list of more binaries]\fR
 730 Installs a \fIbinary\fR or a list of binaries into \fIDESTTREE\fR/sbin.
 731 Creates all necessary dirs.
 732 .TP
 733 \fBdoinitd\fR \fI<init.d script> [list of more init.d scripts]\fR
 734 Install Gentoo \fIinit.d scripts\fR.  They will be installed into the
 735 correct location for Gentoo init.d scripts (/etc/init.d/).  Creates all
 736 necessary dirs.
 737 .TP
 738 \fBdoconfd\fR \fI<conf.d file> [list of more conf.d file]\fR
 739 Install Gentoo \fIconf.d files\fR.  They will be installed into the
 740 correct location for Gentoo conf.d files (/etc/conf.d/).  Creates all
 741 necessary dirs.
 742 .TP
 743 \fBdoenvd\fR \fI<env.d entry> [list of more env.d entries]\fR
 744 Install Gentoo \fIenv.d entries\fR.  They will be installed into the
 745 correct location for Gentoo env.d entries (/etc/env.d/).  Creates all
 746 necessary dirs.
 747
 748 .PD 0
 749 .TP
 750 \fBdolib\fR \fI<library>\fR \fI[list of more libraries]\fR
 751 .TP
 752 \fBdolib.a\fR \fI<library>\fR \fI[list of more libraries]\fR
 753 .TP
 754 \fBdolib.so\fR \fI<library>\fR \fI[list of more libraries]\fR
 755 .PD 1
 756 Installs a library or a list of libraries into \fIDESTTREE\fR/lib.
 757 Creates all necessary dirs.
 758 .TP
 759 \fBlibopts\fR \fI[options for install(1)]\fR
 760 Can be used to define options for the install function used in
 761 the \fBdolib\fR functions.  The default is \fI\-m0644\fR.
 762 .TP
 763 \fBdoman\fR \fI[\-i18n=<locale>]\fR \fI<man\-page> [list of more man\-pages]\fR
 764 Installs manual\-pages into /usr/share/man/man[0\-9n] depending on the
 765 manual file ending.  The files are compressed if they are not already.  You
 766 can specify locale\-specific manpages with the \fI\-i18n\fR option.  Then the
 767 man\-page will be installed into /usr/share/man/\fI<locale>\fR/man[0\-9n].
 768 .PD 0
 769 .TP
 770 \fBdohard\fR \fI<filename> <linkname>\fR
 771 .TP
 772 \fBdosym\fR \fI<filename> <linkname>\fR
 773 .PD 1
 774 Performs the ln command as either a hard link or symlink.
 775 .TP
 776 \fBdohtml\fR \fI [\-a filetypes] [\-r] [\-x list\-of\-dirs\-to\-ignore] [list\-of\-files\-and\-dirs]\fR
 777 Installs the files in the list of files (space\-separated list) into
 778 /usr/share/doc/${PF}/html provided the file ends in .html, .png, .js, .jpg,
 779 or .css.  Setting \fI\-a\fR limits what types of files will be included,
 780 \fI\-A\fR appends to the default list, setting \fI\-x\fR sets which dirs to
 781 exclude (CVS excluded by default), \fI\-r\fR sets recursive.
 782 .TP
 783 \fBdoinfo\fR \fI<info\-file> [list of more info\-files]\fR
 784 Installs info\-pages into \fIDESTDIR\fR/info.  Files are automatically
 785 gzipped.  Creates all necessary dirs.
 786 .TP
 787 \fBdomo\fR \fI<locale\-file> [list of more locale\-files] \fR
 788 Installs locale\-files into \fIDESTDIR\fR/usr/share/locale/[LANG]
 789 depending on local\-file's ending.  Creates all necessary dirs.
 790
 791 .PD 0
 792 .TP
 793 \fBfowners\fR \fI<permissions> <file> [files]\fR
 794 .TP
 795 \fBfperms\fR \fI<permissions> <file> [files]\fR
 796 .PD 1
 797 Performs chown (\fBfowners\fR) or chmod (\fBfperms\fR), applying
 798 \fIpermissions\fR to \fIfiles\fR.
 799 .TP
 800 \fBinsinto\fR \fI[path]\fR
 801 Sets the destination path for the \fBdoins\fR function.
 802 .br
 803 The default path is /.
 804 .TP
 805 \fBinsopts\fR \fI[options for install(1)]\fR
 806 Can be used to define options for the install function used in
 807 \fBdoins\fR.  The default is \fI\-m0644\fR.
 808 .TP
 809 \fBdoins\fR \fI<file> [list of more files]\fR
 810 Installs files into the path controlled by \fBinsinto\fR.  This function
 811 uses \fBinstall\fR(1).  Creates all necessary dirs.
 812 .TP
 813 \fBexeinto\fR \fI[path]\fR
 814 Sets the destination path for the \fBdoexe\fR function.
 815 .br
 816 The default path is /.
 817 .TP
 818 \fBexeopts\fR \fI[options for install(1)]\fR
 819 Can be used to define options for the install function used in \fBdoexe\fR.
 820 The default is \fI\-m0755\fR.
 821 .TP
 822 \fBdoexe\fR \fI<executable> [list of more executables]\fR
 823 Installs executables into the path controlled by \fBexecinto\fR.  This function
 824 uses \fBinstall\fR(1).  Creates all necessary dirs.
 825 .TP
 826 \fBdocinto\fR \fI[path]\fR
 827 Sets the subdir used by \fBdodoc\fR when installing into the document tree
 828 (based in /usr/share/doc/${PF}/).  Default is no subdir, or just "".
 829 .TP
 830 \fBdodoc\fR \fI<document> [list of more documents]\fR
 831 Installs a document or a list of documents into /usr/share/doc/${PF}/\fI<docinto path>\fR.
 832 Documents are marked for compression.  Creates all necessary dirs.
 833
 834 .PD 0
 835 .TP
 836 \fBnewbin\fR \fI<old file> <new filename>\fR
 837 .TP
 838 \fBnewsbin\fR \fI<old file> <new filename>\fR
 839 .TP
 840 \fBnewinitd\fR \fI<old file> <new filename>\fR
 841 .TP
 842 \fBnewconfd\fR \fI<old file> <new filename>\fR
 843 .TP
 844 \fBnewenvd\fR \fI<old file> <new filename>\fR
 845 .TP
 846 \fBnewlib\fR \fI<old file> <new filename>\fR
 847 .TP
 848 \fBnewlib.so\fR \fI<old file> <new filename>\fR
 849 .TP
 850 \fBnewlib.a\fR \fI<old file> <new filename>\fR
 851 .TP
 852 \fBnewman\fR \fI<old file> <new filename>\fR
 853 .TP
 854 \fBnewinfo\fR \fI<old file> <new filename>\fR
 855 .TP
 856 \fBnewins\fR \fI<old file> <new filename>\fR
 857 .TP
 858 \fBnewexe\fR \fI<old file> <new filename>\fR
 859 .TP
 860 \fBnewdoc\fR \fI<old file> <new filename>\fR
 861 .PD 1
 862 All these functions act like the do* functions, but they only work with one
 863 file and the file is installed as \fI[new filename]\fR.
 864 .SH "REPORTING BUGS"
 865 Please report bugs via http://bugs.gentoo.org/
 866 .SH "AUTHORS"
 867 .nf
 868 Achim Gottinger <achim@gentoo.org>
 869 Mark Guertin <gerk@gentoo.org>
 870 Nicholas Jones <carpaski@gentoo.org>
 871 Mike Frysinger <vapier@gentoo.org>
 872 Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA@gmail.com>
 873 .fi
 874 .SH "FILES"
 875 .TP
 876 The \fI/usr/sbin/ebuild.sh\fR script.
 877 .TP
 878 The helper apps in \fI/usr/lib/portage/bin\fR.
 879 .TP
 880 .B /etc/make.conf
 881 Contains variables for the build\-process and overwrites those in make.defaults.
 882 .TP
 883 .B /etc/make.globals
 884 Contains the default variables for the build\-process, you should edit
 885 \fI/etc/make.conf\fR instead.
 886 .TP
 887 .B /etc/portage/color.map
 888 Contains variables customizing colors.
 889 .SH "SEE ALSO"
 890 .BR ebuild (1),
 891 .BR make.conf (5),
 892 .BR color.map (5)