man/ebuild.1

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