man/ebuild.1

   1 .TH "EBUILD" "1" "Oct 2009" "Portage VERSION" "Portage"
   2 .SH "NAME"
   3 ebuild \- a low level interface to the Portage system
   4 .SH "SYNOPSIS"
   5 .B ebuild
   6 .I file command [command]\fR...
   7 .SH "DESCRIPTION"
   8 The ebuild program is a direct interface to the Portage system. It
   9 allows for direct action upon an ebuild with specific subcommands or
  10 groups of commands to perform in a specific ebuild's context and
  11 functions.  Accepting an ebuild script and one or more commands
  12 as arguments, the ebuild program parses the ebuild script and
  13 executes the specified commands.  Commands exist to fetch sources,
  14 unpack sources, compile sources, install object files into a temporary
  15 directory "image", merge the image to the local filesystem, create a
  16 bzipped tarball package out of the image, and more.
  17 .SH "FILE"
  18 This must be a valid ebuild script.  For further information read
  19 \fBebuild\fR(5).
  20 .SH "COMMANDS"
  21 By default, portage will execute all the functions in order up to the
  22 one actually specified.  For example, simply issuing the command \fBcompile\fR
  23 will trigger the functions before it to also be run (such as \fBsetup\fR
  24 and \fBunpack\fR).  If you wish to only have the specified command run, then
  25 you should use the \fInoauto\fR option in the \fBFEATURES\fR environment
  26 variable.  See the \fBmake.conf\fR(5) man page for more information.
  27
  28 .TP
  29 .BR help
  30 Shows a condensed form of this man page along with a lot of package
  31 specific information.
  32 .TP
  33 .BR setup
  34 Runs all package-specific setup actions and exotic system checks.
  35 .TP
  36 .BR clean
  37 Cleans the temporary build directory that Portage has created for
  38 this particular ebuild file.  The temporary build directory normally
  39 contains the extracted source files as well as a possible
  40 "install image" (all the files that will be merged to the local
  41 filesystem or stored in a package).  The location of the build
  42 directory is set by the PORTAGE_TMPDIR variable.  For information
  43 on what this variable is, run \fIemerge \-\-info\fR, or to override
  44 this variable, see \fBmake.conf\fR(5).
  45
  46 Note: Portage cleans up almost everything after a package has been
  47 successfully merged unless FEATURES contains 'noclean'.  Adding noclean
  48 to FEATURES will cause a lot of files to remain and will consume large
  49 amounts of space, very quickly.  It is not recommended to leave this on,
  50 unless you have use for the sources post\-merge.  Optionally, one may
  51 manually clean these files with \fIrm \-rf /var/tmp/portage\fR.
  52 .TP
  53 .BR fetch
  54 Checks to see if all the sources specified in SRC_URI are available in
  55 DISTDIR (see \fBmake.conf\fR(5) for more information) and have a valid
  56 md5 checksum.  If the sources aren't available, an attempt is made to
  57 download them from the locations specified in SRC_URI.  If multiple
  58 download locations are listed for a particular file, Portage pings
  59 each location to see which location is closer. (May not be true
  60 presently.)  The Gentoo Linux mirrors defined by GENTOO_MIRRORS is
  61 always considered first.  If for some reason the current or
  62 just\-downloaded sources' md5 digests don't match those recorded
  63 in files/digest\-[package]\-[version\-rev], a warning is printed
  64 and ebuild exits with an error code of 1.
  65 .TP
  66 .BR digest
  67 This is now equivalent to the \fImanifest\fR command.
  68 .TP
  69 .BR manifest
  70 Updates the manifest file for the package.  This creates checksums for all
  71 of the files found in the same directory as the current ebuild as well as
  72 the recursive contents of the files subdirectory. It also creates checksums
  73 for all of the files listed in SRC_URI for each ebuild. For further
  74 information regarding the behavior of this command, see the documentation for
  75 the \fIassume\-digests\fR value of the \fBFEATURES\fR variable in
  76 \fBmake.conf\fR(5). See the \fB\-\-force\fR option if you would like to
  77 prevent digests from being assumed.
  78 .TP
  79 .BR unpack
  80 Extracts the sources to a subdirectory in the \fIbuild directory\fR
  81 (BUILD_PREFIX) by running the \fIsrc_unpack()\fR function in the ebuild
  82 file.  If no src_unpack() function has been specified, a default
  83 src_unpack() function is used that extracts all the files specified in
  84 SRC_URI.  The sources are normally extracted to
  85 ${BUILD_PREFIX}/[package]\-[version\-rev]/work.  This particular directory
  86 can be referenced by using the ${WORKDIR} variable.
  87
  88 If you're creating an ebuild, you'll want to make sure that the S
  89 (source directory) variable defined at the top of your ebuild script
  90 points to the directory that contains your extracted sources.  This
  91 directory is defined by default to be ${WORKDIR}/${P}, so it is not
  92 often required.  The src_unpack() function is also responsible for
  93 making the appropriate patches to the sources so that they're ready
  94 for compilation.
  95 .TP
  96 .BR prepare
  97 Prepares the extracted sources by running the \fIsrc_prepare()\fR
  98 function specified in the ebuild file. When src_prepare() starts, the
  99 current working directory will be set to ${S}. This function is supported
 100 beginning with \fBEAPI 2\fR.
 101 .TP
 102 .BR configure
 103 Configures the extracted sources by running the \fIsrc_configure()\fR
 104 function specified in the ebuild file. When src_configure() starts, the
 105 current working directory will be set to ${S}. This function is supported
 106 beginning with \fBEAPI 2\fR.
 107 .TP
 108 .BR compile
 109 Compiles the extracted sources by running the \fIsrc_compile()\fR
 110 function specified in the ebuild file.  When src_compile() starts, the
 111 current working directory will be set to ${S}.  When src_compile()
 112 completes, the sources should be fully compiled.
 113 .TP
 114 .BR test
 115 Runs package-specific test cases to verify that everything was built
 116 properly.
 117 .TP
 118 .BR preinst
 119 Runs package-specific actions that need to be done before the package
 120 is installed into the live filesystem.
 121 .TP
 122 .BR install
 123 Installs the package to the temporary \fIinstall directory\fR by running
 124 the \fIsrc_install()\fR function.  When completed, the
 125 \fIinstall directory\fR (${BUILD_PREFIX}/[package]\-[version\-rev]/image)
 126 will contain all the files that should either be merged to the local
 127 filesystem or included in a binary package.
 128 .TP
 129 .BR postinst
 130 Runs package-specific actions that need to be done after the package
 131 is installed into the live filesystem.  Usually helpful messages are
 132 shown here.
 133 .TP
 134 .BR qmerge
 135 This function installs all the files in the \fIinstall directory\fR
 136 to the live filesystem.  The process works as follows: first, the
 137 \fIpkg_preinst()\fR function (if specified) is run.  Then, the files
 138 are merged into the live filesystem, and the installed files' md5
 139 digests are recorded in
 140 \fI/var/db/pkg/${CATEGORY}/${PN}\-${PVR}/CONTENTS\fR.  After
 141 all the files have been merged, the \fIpkg_postinst()\fR function
 142 (if specified) is executed.
 143 .TP
 144 .BR merge
 145 Normally, to merge an ebuild, you need to \fIfetch\fR, \fIunpack\fR,
 146 \fIcompile\fR, \fIinstall\fR and \fIqmerge\fR.  If you're simply
 147 interested in merging the ebuild, you can use this command, which
 148 will perform all these steps for you, stopping along the way if a
 149 particular step doesn't complete successfully.
 150 .TP
 151 .BR unmerge
 152 This function first executes the \fIpkg_prerm()\fR function (if specified).
 153 Then it removes all files from the live filesystem that have a valid md5
 154 checksum and mtime in the package contents file.  Any empty directories
 155 are recursively removed.  Finally, it runs \fIpkg_postrm()\fR function (if
 156 specified).  It is safe to merge a new version of a package first and
 157 then unmerge the old one.  In fact, this is the recommended package
 158 upgrade method.
 159 .TP
 160 .BR prerm
 161 Runs package-specific actions that need to be executed before the package is
 162 removed from the filesystem.  See also \fIunmerge\fR.
 163 .TP
 164 .BR postrm
 165 Runs package-specific actions that need to be executed after the package is
 166 removed from the filesystem.  See also \fIunmerge\fR.
 167 .TP
 168 .BR config
 169 Runs package-specific actions that need to be executed after the emerge
 170 process has completed.  This usually entails setup of configuration files
 171 or other similar setups that the user may wish to run.
 172 .TP
 173 .BR package
 174 This command is a lot like the \fImerge\fR command, except that after
 175 fetching, unpacking, compiling and installing, a .tbz2 binary package
 176 tarball is created and stored in \fBPKGDIR\fR (see \fBmake.conf\fR(5)).
 177 .TP
 178 .BR rpm
 179 Builds a RedHat RPM package from the files in the temporary
 180 \fIinstall directory\fR.  At the moment, the ebuild's dependency
 181 information is not incorporated into the RPM.
 182 .SH OPTIONS
 183 .TP
 184 .BR "\-\-debug"
 185 Run bash with the \-x option, causing it to output verbose debugging
 186 information to stdout.
 187 .TP
 188 .BR "\-\-color < y | n >"
 189 Enable or disable color output.  This option will override \fINOCOLOR\fR
 190 (see \fBmake.conf\fR(5)) and may also be used to force color output when stdout
 191 is not a tty (by default, color is disabled unless stdout is a tty).
 192 .TP
 193 .BR "\-\-force"
 194 When used together with the digest or manifest command,
 195 this option forces regeneration of
 196 digests for all distfiles associated with the current ebuild. Any distfiles
 197 that do not already exist in ${DISTDIR} will be automatically fetched.
 198 .TP
 199 .BR "\-\-ignore\-default\-opts"
 200 Do not use the \fIEBUILD_DEFAULT_OPTS\fR environment variable.
 201 .TP
 202 .BR "\-\-skip\-manifest"
 203 Skip all manifest checks.
 204 .SH "REPORTING BUGS"
 205 Please report bugs via http://bugs.gentoo.org/
 206 .SH "AUTHORS"
 207 .nf
 208 Achim Gottinger <achim@gentoo.org>
 209 Daniel Robbins <drobbins@gentoo.org>
 210 Nicholas Jones <carpaski@gentoo.org>
 211 Mike Frysinger <vapier@gentoo.org>
 212 .fi
 213 .SH "FILES"
 214 .TP
 215 .B /etc/make.conf
 216 Contains variables for the build\-process and overwrites those
 217 in make.globals.
 218 .TP
 219 .B /etc/portage/color.map
 220 Contains variables customizing colors.
 221 .SH "SEE ALSO"
 222 .BR emerge (1),
 223 .BR ebuild (5),
 224 .BR make.conf (5),
 225 .BR color.map (5)
 226 .TP
 227 The \fI/usr/sbin/ebuild.sh\fR script.
 228 .TP
 229 The helper apps in \fI/usr/lib/portage/bin\fR.