Attachment #93645 for bug #143079

View | Details | Raw Unified | Return to bug 143079
Collapse All | Expand All




.TH "EBUILD" "1" "Dec 2005" "Portage 2.1" "Portage"
.SH "NAME"
ebuild \- a low level interface to the Portage system
the Portage system. 
.SH "SYNOPSIS"
.B ebuild
.I file command [command]\fR...

The ebuild program is a direct interface to the Portage system. It
allows for direct action upon an ebuild with specific subcommands or
groups of commands to perform in a specific ebuild's context and
functions.  Accepting an ebuild script and one or more commands
as arguments, the ebuild program parses the ebuild script and
executes the specified commands.  Commands exist to fetch sources,
unpack sources, compile sources, install object files into a temporary
directory "image", merge the image to the local filesystem, create a
bzipped tarball package out of the image, and more.

.SH "COMMANDS"
.TP
.BR help
Shows a condensed form of this man page along with a lot of package
specific information.
.TP
.BR setup
Runs all package-specific setup actions and exotic system checks.
.TP
.BR clean
Cleans the temporary build directory that Portage has created for

this variable, see \fBmake.conf\fR(5).

Note: Portage cleans up almost everything after a package has been
successfully merged unless FEATURES contains 'noclean'.  Adding noclean
to FEATURES will cause a lot of files to remain and will consume large
amounts of space, very quickly.  It is not recommended to leave this on,
unless you have use for the sources post\-merge.  Optionally, one may
manually clean these files with \fIrm \-rf /var/tmp/portage\fR.
of these files.
.TP
.BR fetch
Checks to see if all the sources specified in SRC_URI are available in

download locations are listed for a particular file, Portage pings
each location to see which location is closer. (May not be true
presently.)  The Gentoo Linux mirrors defined by GENTOO_MIRRORS is
always considered first.  If for some reason the current or
just\-downloaded sources' md5 digests don't match those recorded
in files/digest\-[package]\-[version\-rev], a warning is printed
and ebuild exits with an error code of 1.
.TP
.BR digest
Creates a digest file for the package in
/usr/portage/[category]/[package]/files/.  This digest file lists the
md5sums of all the files found in the SRC_URI.  If the fetched source
of the package is corrupt/bogus in some way, the md5sum will catch this.
.TP
.BR manifest

file.  If no src_unpack() function has been specified, a default
src_unpack() function is used that extracts all the files specified in
SRC_URI.  The sources are normally extracted to
${BUILD_PREFIX}/[package]\-[version\-rev]/work.  This particular directory
can be referenced by using the ${WORKDIR} variable.

If you're creating an ebuild, you'll want to make sure that the S
(source directory) variable defined at the top of your ebuild script
points to the directory that contains your extracted sources.  This
directory is defined by default to be ${WORKDIR}/${P}, so it is not
often required.  The src_unpack() function is also responsible for
making the appropriate patches to the sources so that they're ready
for compilation.
.TP
.BR compile
Compiles the extracted sources by running the \fIsrc_compile()\fR
function specified in the ebuild file.  When src_compile() starts, the
current working directory will be set to ${S}.  When src_compile()
completes, the sources should be fully compiled.
.TP
.BR test
Runs package-specific test cases to verify that everything was built 
properly.
.TP
.BR preinst
Runs package-specific actions that need to be done before the package
is installed into the live filesystem.
.TP
.BR install

the \fIsrc_install()\fR function.  When completed, the
\fIinstall directory\fR (${BUILD_PREFIX}/[package]\-[version\-rev]/image)
will contain all the files that should either be merged to the local
filesystem or included in a binary package.
.TP
.BR postinst
Runs package-specific actions that need to be done after the package
is installed into the live filesystem.  Usually helpful messages are
shown here.
.TP
.BR qmerge
This function installs all the files in the \fIinstall directory\fR
to the live filesystem.  The process works as follows: first, the
\fIpkg_preinst()\fR function (if specified) is run.  Then, the files
are merged into the live filesystem, and the installed files' md5
digests are recorded in

particular step doesn't complete successfully.
.TP
.BR unmerge
This function first executes the \fIpkg_prerm()\fR function (if specified).
Then it removes all files from the live filesystem that have a valid md5
checksum and mtime in the package contents file.  Any empty directories
are recursively removed.  Finally, it runs \fIpkg_postrm()\fR function (if
specified).  It is safe to merge a new version of a package first and
then unmerge the old one.  In fact, this is the recommended package
upgrade method.
.TP
.BR prerm
Runs package-specific actions that need to be executed before the package is
removed from the filesystem.  See also \fIunmerge\fR.
.TP
.BR postrm
Runs package-specific actions that need to be executed after the package is
removed from the filesystem.  See also \fIunmerge\fR.
.TP
.BR config
Runs package-specific actions that need to be executed after the emerge
process has completed.  This usually entails setup of configuration files
or other similar setups that the user may wish to run.
.TP
.BR package
This command is a lot like the \fImerge\fR command, except that after

.TP
.BR rpm
Builds a RedHat RPM package from the files in the temporary
\fIinstall directory\fR.  At the moment, the ebuild's dependency
information is not incorporated into the RPM.
.SH "REPORTING BUGS"
Please report bugs via http://bugs.gentoo.org/

Return to bug 143079

Lines 1-7 Link Here

(-)ebuild.1.orig (-31 / +29 lines)
1	.TH "EBUILD" "1" "Dec 2005" "Portage 2.1" "Portage"	1	.TH "EBUILD" "1" "Dec 2005" "Portage 2.1" "Portage"
2	.SH "NAME"	2	.SH "NAME"
3	ebuild \- manual page for the ebuild program, a low level interface to	3	ebuild \- a low level interface to the Portage system
4	the Portage system.
5	.SH "SYNOPSIS"	4	.SH "SYNOPSIS"
6	.B ebuild	5	.B ebuild
7	.I file command [command]\fR...	6	.I file command [command]\fR...
Lines 9-17 Link Here
9	The ebuild program is a direct interface to the Portage system. It	8	The ebuild program is a direct interface to the Portage system. It
10	allows for direct action upon an ebuild with specific subcommands or	9	allows for direct action upon an ebuild with specific subcommands or
11	groups of commands to perform in a specific ebuild's context and	10	groups of commands to perform in a specific ebuild's context and
12	functions. Accepting an ebuild script and one or more commands	11	functions. Accepting an ebuild script and one or more commands
13	as arguments, the ebuild program parses the ebuild script and	12	as arguments, the ebuild program parses the ebuild script and
14	execute the specified commands. Commands exist to fetch sources,	13	executes the specified commands. Commands exist to fetch sources,
15	unpack sources, compile sources, install object files into a temporary	14	unpack sources, compile sources, install object files into a temporary
16	directory "image", merge the image to the local filesystem, create a	15	directory "image", merge the image to the local filesystem, create a
17	bzipped tarball package out of the image, and more.	16	bzipped tarball package out of the image, and more.
Lines 21-31 Link Here
21	.SH "COMMANDS"	20	.SH "COMMANDS"
22	.TP	21	.TP
23	.BR help	22	.BR help
24	Show a condensed form of the man page along with a lot of package	23	Shows a condensed form of this man page along with a lot of package
25	specific information.	24	specific information.
26	.TP	25	.TP
27	.BR setup	26	.BR setup
28	Run all package specific setup actions and exotic system checks.	27	Runs all package-specific setup actions and exotic system checks.
29	.TP	28	.TP
30	.BR clean	29	.BR clean
31	Cleans the temporary build directory that Portage has created for	30	Cleans the temporary build directory that Portage has created for
Lines 38-49 Link Here
38	this variable, see \fBmake.conf\fR(5).	37	this variable, see \fBmake.conf\fR(5).
39		38
40	Note: Portage cleans up almost everything after a package has been	39	Note: Portage cleans up almost everything after a package has been
41	successfully merged unless FEATURES contains 'noclean'. Adding noclean	40	successfully merged unless FEATURES contains 'noclean'. Adding noclean
42	to FEATURES will cause a lot of files to remain and will consume large	41	to FEATURES will cause a lot of files to remain and will consume large
43	amounts of space, very quickly. It is not recommended to leave this on	42	amounts of space, very quickly. It is not recommended to leave this on,
44	unless you have use for the sources post\-merge. Optionally one may,	43	unless you have use for the sources post\-merge. Optionally, one may
45	manual clean \fIrm \-rf /var/tmp/portage\fR will take care of all	44	manually clean these files with \fIrm \-rf /var/tmp/portage\fR.
46	of these files.
47	.TP	45	.TP
48	.BR fetch	46	.BR fetch
49	Checks to see if all the sources specified in SRC_URI are available in	47	Checks to see if all the sources specified in SRC_URI are available in
Lines 53-67 Link Here
53	download locations are listed for a particular file, Portage pings	51	download locations are listed for a particular file, Portage pings
54	each location to see which location is closer. (May not be true	52	each location to see which location is closer. (May not be true
55	presently.) The Gentoo Linux mirrors defined by GENTOO_MIRRORS is	53	presently.) The Gentoo Linux mirrors defined by GENTOO_MIRRORS is
56	always considered first. If for some reason the current or	54	always considered first. If for some reason the current or
57	just\-downloaded sources' md5 digests don't match those recorded	55	just\-downloaded sources' md5 digests don't match those recorded
58	in files/digest\-[package]\-[version\-rev], a warning is printed	56	in files/digest\-[package]\-[version\-rev], a warning is printed
59	and ebuild exits with an error code of 1.	57	and ebuild exits with an error code of 1.
60	.TP	58	.TP
61	.BR digest	59	.BR digest
62	Creates a digest file for the package in	60	Creates a digest file for the package in
63	/usr/portage/[category]/[package]/files/. This digest file lists the	61	/usr/portage/[category]/[package]/files/. This digest file lists the
64	md5sum's of all the files found in the SRC_URI. If the fetched source	62	md5sums of all the files found in the SRC_URI. If the fetched source
65	of the package is corrupt/bogus in some way, the md5sum will catch this.	63	of the package is corrupt/bogus in some way, the md5sum will catch this.
66	.TP	64	.TP
67	.BR manifest	65	.BR manifest
Lines 75-103 Link Here
75	file. If no src_unpack() function has been specified, a default	73	file. If no src_unpack() function has been specified, a default
76	src_unpack() function is used that extracts all the files specified in	74	src_unpack() function is used that extracts all the files specified in
77	SRC_URI. The sources are normally extracted to	75	SRC_URI. The sources are normally extracted to
78	${BUILD_PREFIX}/[package]\-[version\-rev]/work. This particular directory	76	${BUILD_PREFIX}/[package]\-[version\-rev]/work. This particular directory
79	can be referenced by using the ${WORKDIR} variable.	77	can be referenced by using the ${WORKDIR} variable.
80		78
81	If you're creating an ebuild, you'll want to make sure that the S	79	If you're creating an ebuild, you'll want to make sure that the S
82	(source directory) variable defined at at the top of your ebuild script	80	(source directory) variable defined at the top of your ebuild script
83	points to the directory that contains your extracted sources. This	81	points to the directory that contains your extracted sources. This
84	directory is defined by default to be ${WORKDIR}/${P}, so it is not	82	directory is defined by default to be ${WORKDIR}/${P}, so it is not
85	often required. The src_unpack() function is also responsible for	83	often required. The src_unpack() function is also responsible for
86	making the appropriate patches to the sources so that they're ready	84	making the appropriate patches to the sources so that they're ready
87	for compilation.	85	for compilation.
88	.TP	86	.TP
89	.BR compile	87	.BR compile
90	Compiles the extracted sources by running the the \fIsrc_compile()\fR	88	Compiles the extracted sources by running the \fIsrc_compile()\fR
91	function specified in the ebuild file. When src_compile() starts, the	89	function specified in the ebuild file. When src_compile() starts, the
92	current working directory will be set to ${S}. When src_compile()	90	current working directory will be set to ${S}. When src_compile()
93	completes, the sources should be fully compiled.	91	completes, the sources should be fully compiled.
94	.TP	92	.TP
95	.BR test	93	.BR test
96	Run package specific test cases to verify that everything was built	94	Runs package-specific test cases to verify that everything was built
97	properly.	95	properly.
98	.TP	96	.TP
99	.BR preinst	97	.BR preinst
100	Run package specific actions that need to be done before the package	98	Runs package-specific actions that need to be done before the package
101	is installed into the live filesystem.	99	is installed into the live filesystem.
102	.TP	100	.TP
103	.BR install	101	.BR install
Lines 105-120 Link Here
105	the \fIsrc_install()\fR function. When completed, the	103	the \fIsrc_install()\fR function. When completed, the
106	\fIinstall directory\fR (${BUILD_PREFIX}/[package]\-[version\-rev]/image)	104	\fIinstall directory\fR (${BUILD_PREFIX}/[package]\-[version\-rev]/image)
107	will contain all the files that should either be merged to the local	105	will contain all the files that should either be merged to the local
108	file system or included in a binary package.	106	filesystem or included in a binary package.
109	.TP	107	.TP
110	.BR postinst	108	.BR postinst
111	Run package specific actions that need to be done after the package	109	Runs package-specific actions that need to be done after the package
112	is installed into the live filesystem. Usually helpful messages are	110	is installed into the live filesystem. Usually helpful messages are
113	shown here.	111	shown here.
114	.TP	112	.TP
115	.BR qmerge	113	.BR qmerge
116	This function installs all the files in the \fIinstall directory\fR	114	This function installs all the files in the \fIinstall directory\fR
117	to the live filesystem. The process works as follows: first, the	115	to the live filesystem. The process works as follows: first, the
118	\fIpkg_preinst()\fR function (if specified) is run. Then, the files	116	\fIpkg_preinst()\fR function (if specified) is run. Then, the files
119	are merged into the live filesystem, and the installed files' md5	117	are merged into the live filesystem, and the installed files' md5
120	digests are recorded in	118	digests are recorded in
Lines 130-155 Link Here
130	particular step doesn't complete successfully.	128	particular step doesn't complete successfully.
131	.TP	129	.TP
132	.BR unmerge	130	.BR unmerge
133	This function first executes the \fIpkg_prerm\fR function (if specified).	131	This function first executes the \fIpkg_prerm()\fR function (if specified).
134	Then it removes all files from the live filesystem that have a valid md5	132	Then it removes all files from the live filesystem that have a valid md5
135	checksum and mtime in the package contents file. Any empty directories	133	checksum and mtime in the package contents file. Any empty directories
136	are recursively removed. Finally, it runs \fIpkg_postrm\fR function (if	134	are recursively removed. Finally, it runs \fIpkg_postrm()\fR function (if
137	specified). It is safe to merge a new version of a package first and	135	specified). It is safe to merge a new version of a package first and
138	then unmerge the old one. In fact, this is the recommended package	136	then unmerge the old one. In fact, this is the recommended package
139	upgrade method.	137	upgrade method.
140	.TP	138	.TP
141	.BR prerm	139	.BR prerm
142	Run package specific actions that need to be executed before the package is	140	Runs package-specific actions that need to be executed before the package is
143	removed from the filesystem. See also \fIunmerge\fR.	141	removed from the filesystem. See also \fIunmerge\fR.
144	.TP	142	.TP
145	.BR postrm	143	.BR postrm
146	Run package specific actions that need to be executed after the package is	144	Runs package-specific actions that need to be executed after the package is
147	removed from the filesystem. See also \fIunmerge\fR.	145	removed from the filesystem. See also \fIunmerge\fR.
148	.TP	146	.TP
149	.BR config	147	.BR config
150	Run package specific actions needed to be executed after the emerge	148	Runs package-specific actions that need to be executed after the emerge
151	process has completed. This usually entails configuration file	149	process has completed. This usually entails setup of configuration files
152	setup or other similar setups that the user may wish to run.	150	or other similar setups that the user may wish to run.
153	.TP	151	.TP
154	.BR package	152	.BR package
155	This command is a lot like the \fImerge\fR command, except that after	153	This command is a lot like the \fImerge\fR command, except that after
Lines 160-166 Link Here
160	.TP	158	.TP
161	.BR rpm	159	.BR rpm
162	Builds a RedHat RPM package from the files in the temporary	160	Builds a RedHat RPM package from the files in the temporary
163	\fIinstall directory\fR. At the moment, the ebuild's dependency	161	\fIinstall directory\fR. At the moment, the ebuild's dependency
164	information is not incorporated into the RPM.	162	information is not incorporated into the RPM.
165	.SH "REPORTING BUGS"	163	.SH "REPORTING BUGS"
166	Please report bugs via http://bugs.gentoo.org/	164	Please report bugs via http://bugs.gentoo.org/