[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
None
From: |
David de Gruyl |
Subject: |
None |
Date: |
Mon, 7 Jul 2003 13:46:05 -0400 |
NNAAMMEE
emerge - Command-line interface to the Portage system
SSYYNNOOPPSSIISS
eemmeerrggee [_o_p_t_i_o_n_s] [_a_c_t_i_o_n]
[_e_b_u_i_l_d | _t_b_z_2_f_i_l_e | _c_l_a_s_s |
_d_e_p_e_n_d_e_n_c_y] ...
eemmeerrggee [_o_p_t_i_o_n_s] [_a_c_t_i_o_n]
eebbuuiillddffiillee
eemmeerrggee ssyynncc | rrssyynncc
eemmeerrggee _-_-_h_e_l_p _-_h [ssyysstteemm |
ccoonnffiigg | ssyynncc]
eemmeerrggee _-_-_v_e_r_s_i_o_n
DDEESSCCRRIIPPTTIIOONN
eemmeerrggee is the definitive command-line interface to the
Portage system. It is primarily used for
installing packages, and eemmeerrggee can automatically handle any
dependencies that the desired package
has. eemmeerrggee can also update the ppoorrttaaggee
ttrreeee, making new and updated packages available. eemmeerrggee
gracefully handles updating installed packages to newer releases as
well. It handles both source and
binary packages, and it can be used to create binary packages for
distribution.
EEBBUUIILLDDSS,, TTBBZZ22SS,, CCLLAASSSSEESS AANNDD
DDEEPPEENNDDEENNCCIIEESS
eemmeerrggee primarily installs packages. You can specify
packages to install in one of four main ways: an
_e_b_u_i_l_d, a _t_b_z_2_f_i_l_e, a _c_l_a_s_s, or a
_d_e_p_e_n_d_e_n_c_y.
eebbuuiilldd An _e_b_u_i_l_d must be, at a minimum, a valid
Portage package directory name without a version or
category, such as ppoorrttaaggee or ppyytthhoonn.
Both categories and version numbers may be used in addi-
tion, such as ssyyss--aappppss//ppoorrttaaggee or
==ppyytthhoonn--22..22..11--rr22. eemmeerrggee ignores a
trailing slash so that
filename completion can be used. The _e_b_u_i_l_d
may also be an actual filename, such as
//uussrr//ppoorrttaaggee//aapppp--aaddmmiinn//ppyytthhoonn//ppyytthhoonn--22..22..11--rr22..eebbuuiilldd.
ttbbzz22ffiillee
A _t_b_z_2_f_i_l_e must be a valid .tbz2 created with
eebbuuiilldd
<<ppaacckkaaggee>>--<<vveerrssiioonn>>..eebbuuiilldd
ppaacckkaaggee or
eemmeerrggee ----bbuuiillddppkkgg
[[ccaatteeggoorryy//]]<<ppaacckkaaggee>> or
qquuiicckkppkkgg
//vvaarr//ddbb//ppkkgg//<<ccaatteeggoorryy>>//<<ppaacckkaaggee>>.
ccllaassss Package classes are a convenient shorthand for large
groups of packages. Two classes are cur-
rently supported: ssyysstteemm and wwoorrlldd.
ssyysstteemm refers to a set of packages deemed necessary for
your system to run properly. wwoorrlldd contains all of
the packages in ssyysstteemm, along with any
other packages listed in
//vvaarr//ccaacchhee//eeddbb//wwoorrlldd. [See
FFIILLEESS below for more information.] Note
that these commands are generally used in conjunction with
----uuppddaattee.
ddeeppeennddeennccyy
A _d_e_p_e_n_d_e_n_c_y describes bounds on a
package that you wish to install. For example,
>>==ddeevv--llaanngg//ppyytthhoonn--22..22..11--rr22
matches the latest available version of Python greater than or
equal to 2.2.1-r2. Similarly,
<<ddeevv--llaanngg//ppyytthhoonn--22..00 matches the latest
available version of
Python before 2.0. Note that in many shells you will need to
escape characters such as '<'
and '='; use single- or double-quotes around the
_d_e_p_e_n_d_e_n_c_y to get around escaping problems.
AACCTTIIOONNSS
NNoo aaccttiioonn
If no action is specified, the action is to merge in the
specified packages, satisfying any
dependencies that they may have. The arguments can be
_e_b_u_i_l_d_s, _t_b_z_2_s, _c_l_a_s_s_e_s, or
_d_e_p_e_n_d_e_n_-
_c_i_e_s. NNoottee tthhaatt yyoouu nneeeedd
ttoo uussee tthhee --usepkg ooppttiioonn iiff yyoouu
wwaanntt ttoo iinnssttaallll aa ttbbzz22. The pack-
ages are added to the wwoorrlldd file at the end, so that
they are considered for later updating.
cclleeaann (--cc)
Cleans the system by removing packages that will not effect the
functionality of the system.
The arguments can be _e_b_u_i_l_d_s,
_c_l_a_s_s_e_s, or _d_e_p_e_n_d_e_n_c_i_e_s. For example,
eemmeerrggee cclleeaann bbiinnuuttiillss
cleans out old versions of binutils; eemmeerrggee
cclleeaann
nneett--wwwwww//mmoozziillllaa--00..99..99--rr22
cleans out that
specific version of Mozilla. This is generally safe to use.
NNoottee tthhaatt clean ddooeess nnoott rreemmoovvee
uunnssllootttteedd ppaacckkaaggeess..
ddeeppcclleeaann
Determines all packages installed on the system that have no
explicit reason for being there.
eemmeerrggee generates a list of packages which it
expects to be installed by checking the ssyysstteemm
package list and the wwoorrlldd file. It then compares that
list to the list of packages which are
actually installed; the differences are listed as unnecessary
packages and are suggested for
unmerging. WWAARRNNIINNGG:: RReemmoovviinngg
ssoommee ppaacckkaaggeess mmaayy ccaauussee
ppaacckkaaggeess wwhhiicchh lliinnkk ttoo tthhee
rreemmoovveedd ppaacckk--
aaggee ttoo ssttoopp wwoorrkkiinngg aanndd
ccoommppllaaiinn aabboouutt mmiissssiinngg
lliibbrraarriieess.. Re-emerge the complaining package
to fix this issue. NNoottee tthhaatt
cchhaannggeess iinn UUSSEE ffllaaggss ccaann
ddrraassttiiccaallllyy aaffffeecctt tthhee
oouuttppuutt ooff ddeepp--
cclleeaann..
hheellpp (--hh)
Displays help information for emerge. Adding one of the
additional arguments listed above
will give you more specific help information on that subject.
The internal eemmeerrggee help docu-
mentation is updated more frequently than this man page; check
it out if you are having prob-
lems that this man page does not help resolve.
iinnffoo This is a list of information to include in bug reports
which aids the developers with fixing
any problems you may report. PPlleeaassee
iinncclluuddee tthhiiss iinnffoorrmmaattiioonn
wwhheenn ssuubbmmiittttiinngg aa bbuugg rreeppoorrtt..
Expanded output can be obtained with the
_-_-_v_e_r_b_o_s_e option.
iinnjjeecctt (--ii)
Injecting a package inserts a 'stub' for that package so that
Portage thinks that it is
installed. It is handy if you need, say, a binary version of
XFree86 for esoteric hardware, or
you just like to roll your own packages. You mmuusstt
specify a category and particular version
of a package for injecting. For example, eemmeerrggee
iinnjjeecctt
ssyyss--kkeerrnneell//ggeennttoooo--ssoouurrcceess--22..44..1199.
pprruunnee (--PP)
WWAARRNNIINNGG:: TThhiiss aaccttiioonn
ccaann rreemmoovvee iimmppoorrttaanntt
ppaacckkaaggeess!! Removes all but the latest versions of
matching packages. If there are multiple SLOTs for a package, it
leaves the latest version in
each SLOT. This does no checking of dependencies, so it may
remove packages necessary for the
proper operation of your system. UUssee clean
iinnsstteeaadd uunnlleessss yyoouu rreeaallllyy
kknnooww wwhhaatt yyoouu''rree ddooiinngg.
Its arguments can be _e_b_u_i_l_d_s,
_c_l_a_s_s_e_s, or _d_e_p_e_n_d_e_n_c_i_e_s -- see
cclleeaann above for examples.
rrssyynncc See ssyynncc below.
sseeaarrcchh (--ss)
Searches for matches of the supplied string in the portage tree.
The search string is a regu-
lar expression. For example, eemmeerrggee
sseeaarrcchh ""^^kkddee"" searches for any package that starts
with
"kde"; eemmeerrggee sseeaarrcchh
""ggcccc$$"" searches for any package that ends with "gcc";
eemmeerrggee sseeaarrcchh
""ooffffiiccee"" searches for any package that contains
the word "office". If you want to search the
package descriptions as well, use the
----sseeaarrcchhddeesscc,--SS option.
ssyynncc Initiates a portage tree update with one of the
rsync.gentoo.org mirrors. NNoottee tthhaatt aannyy
cchhaannggeess yyoouu hhaavvee mmaaddee ttoo
tthhee ppoorrttaaggee ttrreeee wwiillll bbee
eerraasseedd. Except for in special circum-
stances, this uses rrssyynncc to do the update. See
make.conf's description of PORTDIR_OVERLAY for
a method to avoid deletions.
uunnmmeerrggee (--CC)
WWAARRNNIINNGG:: TThhiiss aaccttiioonn
ccaann rreemmoovvee iimmppoorrttaanntt
ppaacckkaaggeess!! Removes all matching packages. This does
no checking of dependencies, so it may remove packages
necessary for the proper operation of
your system. Its arguments can be _e_b_u_i_l_d_s,
_c_l_a_s_s_e_s, or _d_e_p_e_n_d_e_n_c_i_e_s -- see
cclleeaann above for
examples.
----vveerrssiioonn
Displays the version number of eemmeerrggee.
OOPPTTIIOONNSS
----bbuuiillddppkkgg (--bb)
Tells emerge to build binary packages for all ebuilds processed
in addition to actually merg-
ing the packages. Useful for maintainers or if you administrate
multiple Gentoo Linux systems
(build once, emerge tbz2s everywhere). The package will be
created in the _$_{_P_K_G_D_I_R_}/All
directory. An alternative for already-merged packages is to use
qquuiicckkppkkgg which creates a tbz2
from the live filesystem.
----ccoolluummnnss
Used along side _-_-_p_r_e_t_e_n_d to causes the
package, new version, and old version to be displayed
in an aligned format for easy cut-n-paste.
----ddeebbuugg (--dd)
Tells emerge to run the emerge command in --debug mode. In this
mode the bash build environ-
ment will run with the -x option, causing it to output verbose
debug information to stdout.
--debug is great for finding bash syntax errors.
----ddeeeepp When used in conjunction with
----uuppddaattee, this flag forces eemmeerrggee to consider the
entire depen-
dency tree of packages, instead of checking only the immediate
dependencies of the packages.
As an example, this catches updates in libraries that are not
directly listed in the dependen-
cies of a package.
----eemmppttyyttrreeee (--ee)
Virtually tweaks the tree of installed packages to only
contain glibc; this is great to use
together with --pretend. This allows developers to get a complete
overview of the complete
dependency tree of a package, and it enables complete trees
to be rebuilt using the latest
libraries.
----ffeettcchhoonnllyy (--ff)
Instead of doing any package building, just perform fetches for
all packages (the main package
as well as all dependencies.)
----nnooccoonnffmmeemm
Causes portage to disregard merge records indicating that a
config file inside of a CON-
FIG_PROTECT directory has been merged already. Portage will
normally merge those files only
once to prevent the user from dealing with the same config
multiple times. This flag will
cause the file to always be merged.
----nnooddeeppss
Merges specified packages without merging any dependencies. Note
that the build may fail if
the dependencies aren't satisfied.
----nnoorreeppllaaccee (--nn)
Skips the packages specified on the command-line that have
already been installed. Without
this option, any packages, ebuilds, or deps you specify on on the
command-line *will* cause
Portage to remerge the package, even if it is already
installed. Note that Portage will not
remerge dependencies by default.
----nnoossppiinnnneerr
Disables the spinner for the session. The spinner is active when
the terminal device is deter-
mined to be a TTY. This flag disables it regardless.
----oonneesshhoott
Emerge as normal, but do not add the packages to the world
profile for later updating.
----oonnllyyddeeppss (--oo)
Only merge (or pretend to merge) the dependencies of the
packages specified, not the packages
themselves.
----pprreetteenndd (--pp)
Instead of actually performing the merge, simply display what
*would* have been installed if
--pretend weren't used. Using --pretend is strongly recommended
before installing an unfamil-
iar package. In the printout, N = new, U = upgrading, R =
replacing, B = blocked by an already
installed package.
----sseeaarrcchhddeesscc (--SS)
Matches the search string against the description field as
well as the package name. TTaakkee
ccaauuttiioonn as the descriptions are also matched as
regular expressions.
----uuppddaattee (--uu)
Updates packages to the most recent version available.
NNoottee tthhaatt --update ddooeess nnoott hhaavvee
ffuullll
ffuunnccttiioonnaalliittyy yyeett. It will
not automatically update dependencies of packages in the wwoorrlldd
file, unless they too are in the wwoorrlldd file.
----uusseeppkkgg (--kk)
Tells emerge to use binary packages (from $PKGDIR) if they are
available, thus possibly avoid-
ing some time-consuming compiles. This option is useful
for CD installs; you can export
PKGDIR=/mnt/cdrom/packages and then use this option to have
emerge "pull" binary packages from
the CD in order to satisfy dependencies.
----vveerrbboossee (--vv)
Tell emerge to run in verbose mode. Currently this flag causes
emerge to print out GNU info
errors, if any.
----vveerrssiioonn
Displays the version number of eemmeerrggee. It cannot be
used in conjunction with other options;
the name and format of the action is a convention.
OOUUTTPPUUTT
While utilizing emerge and the pretend/verbose flags, the output may
be a little hard to understand
for the first time. This section exists to explain what the shorthanded
information means.
[[bblloocckkss BB ]]
aapppp--tteexxtt//ddooss22uunniixx ((ffrroomm ppkkgg
aapppp--tteexxtt//hhdd22uu--00..88..00))
Dos2unix is Blocking hd2u from being emerged. Blockers are
defined when two packages will
clobber each others files, or otherwise cause some form of
breakage in your system. However,
blockers usually do not need to be simultaneously emerged because
they usually provide the
same functionality.
[[eebbuuiilldd NN ]]
aapppp--ggaammeess//qqssttaatt--2255cc
Qstat is New to your system, and will be emerged for the first
time.
[[eebbuuiilldd RR ]]
ssyyss--aappppss//sseedd--44..00..55
Sed 4.0.5 has already been emerged, but if you run the
command, then portage will Re-emerge
the specified package (sed in this case).
[[eebbuuiilldd UU ]]
nneett--ffss//ssaammbbaa--22..22..88__pprree11
[[22..22..77aa]]
Samba 2.2.7a has already been emerged and can be Updated to
version 2.2.8_pre1.
[[eebbuuiilldd UUDD]]
mmeeddiiaa--lliibbss//lliibbggdd--11..88..44
[[22..00..1111]]
Libgd 2.0.11 is already emerged, but if you run the command, then
portage will Downgrade to
version 1.8.4 for you.
This may occur if a newer version of a package has been masked
because it is broken or it cre-
ates a security risk on your system and a fix has not been
released yet.
Another reason this may occur is if a package you are trying to
emerge requires an older ver-
sion of a package in order to emerge succesfully. In this
case, libgd 2.x is incompatible
with libgd 1.x. This means that packages that were created with
libgd 1.x will not compile
with 2.x and must downgrade libgd first before they can emerge.
[[eebbuuiilldd UU--]]
xx1111--bbaassee//xxffrreeee--44..33..00
[[44..22..9999..990022]]
The - represents lack of SSLLOOTT information about Xfree.
This will occur when the previous ver-
sion emerged was injected (see iinnjjeecctt ffoorr
mmoorree iinnffoo)) oorr vveerryy oouuttddaatteedd
((ssoo oolldd tthhaatt SSLLOOTT ddiidd
nnoott eexxiisstt)).. EEiitthheerr wwaayy,,
aa nneewweerr vveerrssiioonn ooff XXffrreeee iiss
aavvaaiillaabbee ffoorr yyoouurr uuppddaattiinngg
ddeelliigghhtt..
[[eebbuuiilldd UU ]]
nneett--aannaallyyzzeerr//nnmmaapp--33..1155__bbeettaa22
[[33..1155__bbeettaa11]] --ggttkk --ggnnoommee
The -gtk and -gnome reflect the status of UUSSEE variables
when emerging nmap. Here we see that
nmap can use the UUSSEE variables gtk and gnome, but that your
current settings have gtk and
gnome disabled. So optional support for gtk and gnome will
not be enabled in nmap when you
emerge it.
NNOOTTEESS
You should almost always precede any package install or update attempt
with a ----pprreetteenndd install or
update. This lets you see how much will be done, and shows you any
blocking packages that you will
have to rectify. This goes doubly so for the ssyysstteemm and
wwoorrlldd classes, which can update a large num-
ber of packages if the portage tree has been particularly active.
You also want to typically use ----uuppddaattee, which
ignores packages that are already fully updated but
upgrades those that are not.
When you install a package with uninstalled dependencies and do not
explicitly state those dependen-
cies in the list of parameters, they will not be added to the world
file. If you want them to be
detected for world updates, make sure to explicitly list them as
parameters to eemmeerrggee.
UUSSEE vvaarriiaabblleess may be specified on the command
line to override those specified in the default loca-
tions, letting you avoid using some dependencies you may not want to
have. UUSSEE ffllaaggss ssppeecciiffiieedd oonn
tthhee ccoommmmaanndd lliinnee aarree NNOOTT
rreemmeemmbbeerreedd. For example, UUSSEE==""--xx
--ggnnoommee"" eemmeerrggee mmcc will emerge mc with
those USE settings.
If eemmeerrggee ----uuppddaattee ssyysstteemm or
eemmeerrggee ----uuppddaattee wwoorrlldd fail with an error
message, it may be that an
ebuild uses some newer feature not present in this version of
eemmeerrggee. You can use eemmeerrggee ----uuppddaattee
ppoorrttaaggee to upgrade to the lastest version, which should
support any necessary new features.
MMAASSKKEEDD PPAACCKKAAGGEESS
_N_O_T_E_: _P_l_e_a_s_e _u_s_e _c_a_u_t_i_o_n
_w_h_e_n _u_s_i_n_g _d_e_v_e_l_o_p_m_e_n_t
_p_a_c_k_a_g_e_s_. _P_r_o_b_l_e_m_s _a_n_d _b_u_g_s
_r_e_s_u_l_t_i_n_g _f_r_o_m _m_i_s_u_s_i_n_g
_m_a_s_k_e_d _p_a_c_k_a_g_e_s _d_r_a_i_n_s
_G_e_n_t_o_o _d_e_v_e_l_o_p_e_r _t_i_m_e_.
_P_l_e_a_s_e _b_e _s_u_r_e _y_o_u _a_r_e
_c_a_p_a_b_l_e _o_f _h_a_n_d_l_i_n_g
_p_r_o_b_l_e_m_s
_t_h_a_t _m_a_y _e_n_s_u_e_.
Masks in ppoorrttaaggee provide three primary functions: they
allow a testing period where the packages can
be used in live machines; they prevent the use of a package when it will
fail, and they mask existing
packages that are broken or could pose a security risk. Masking can
be done by two methods: ppaacckk--
aaggee..mmaasskk and KEYWORDS.
ppaacckkaaggee..mmaasskk
ppaacckkaaggee..mmaasskk primarily blocks the use of
packages that cause problems or are known to have
issues on disparate systems. It resides in
_$_{_P_O_R_T_D_I_R_}_/_p_r_o_f_i_l_e_s. Packages may be
unmasked in
the file by adding a comment character (##) to the beginning of
the line which masks the pack-
age.
KKEEYYWWOORRDDSS
KEYWORDS are also used for masking packages still in testing.
There are architecture-specific
keywords for each package that let ppoorrttaaggee know
which systems are compatible with the package.
Packages which compile on an architecture, but have not been
proven to be "stable", are masked
with a tilde (~~) in front of the architecture name.
eemmeerrggee examines the AACCCCEEPPTT__KKEEYYWWOORRDDSS
envi-
ronment variable to allow or disallow the emerging of a
package masked by a KEYWORD. To
inform eemmeerrggee that it should build these
'testing' versions of packages, you may set
AACCCCEEPPTT__KKEEYYWWOORRDDSS to
"~~aarrcchh", where aarrcchh is one of xx8866, ppppcc,
ssppaarrcc, ssppaarrcc6644, or aallpphhaa. For
example,
AACCCCEEPPTT__KKEEYYWWOORRDDSS==""~~xx8866""
eemmeerrggee xxffrreeee will cause eemmeerrggee to consider
KEYWORDS-masked
versions of XFree it decides the packages to build.
WWAARRNNIINNGG:: Do _n_o_t set this variable to any-
thing other than the value corresponding to your architecture.
RREEPPOORRTTIINNGG BBUUGGSS
Please report any bugs you encounter through our website:
hhttttpp::////bbuuggss..ggeennttoooo..oorrgg//
Please include the output of eemmeerrggee iinnffoo when you
submit your bug report.
SSEEEE AALLSSOO
eemmeerrggee--help, eebbuuiilldd(1), eebbuuiilldd(5),
mmaakkee..ccoonnff(5)
A number of helper applications reside in
_/_u_s_r_/_l_i_b_/_p_o_r_t_a_g_e_/_b_i_n.
The ggeennttoooollkkiitt package contains useful scripts such
as qqppkkgg (a package query tool).
FFIILLEESS
//vvaarr//ccaacchhee//eeddbb//wwoorrlldd
Contains a list of all user-specified packages. You can safely
edit this file, adding pack-
ages that you want to be considered in wwoorrlldd class
updates and removing those that you do not
want to be considered.
//eettcc//mmaakkee..ccoonnff
Contains variables for the build process, overriding those in
mmaakkee..gglloobbaallss. YYoouu sshhoouulldd
eeddiitt
tthhiiss ffiillee iinnsstteeaadd ooff tthhee
oonneess lliisstteedd bbeellooww.
//eettcc//mmaakkee..pprrooffiillee//mmaakkee..ddeeffaauullttss
Contains profile-specific variables for the build process. DDoo
nnoott eeddiitt tthhiiss ffiillee.
//eettcc//mmaakkee..pprrooffiillee//uussee..ddeeffaauullttss
Contains the USE flags that are enabled by default. DDoo
nnoott eeddiitt tthhiiss ffiillee.
//uussrr//ppoorrttaaggee//pprrooffiilleess//uussee..ddeesscc
Contains the master list of USE flags with descriptions of
their functions. DDoo nnoott eeddiitt tthhiiss
ffiillee.
//eettcc//mmaakkee..pprrooffiillee//vviirrttuuaallss
Contains a list of default packages used to resolve virtual
dependencies. DDoo nnoott eeddiitt tthhiiss
ffiillee.
//vvaarr//ccaacchhee//eeddbb//vviirrttuuaallss
Contains a list of packages used to resolve virtual
dependencies. In the case of failing vir-
tual matches, you may reorder the entries for the corresponding
virtual here. The first pack-
age listed after the virtual is the entry used for matching the
virtual.
//eettcc//mmaakkee..pprrooffiillee//ppaacckkaaggee
Contains a list of packages used for the base system. The
ssyysstteemm and wwoorrlldd classes consult
this file. DDoo nnoott eeddiitt tthhiiss
ffiillee.
//eettcc//mmaakkee..gglloobbaallss
Contains the default variables for the build process. DDoo
nnoott eeddiitt tthhiiss ffiillee.
AAUUTTHHOORRSS
Daniel Robbins <address@hidden>
Geert Bevin <address@hidden>
Achim Gottinger <address@hidden>
Nicholas Jones <address@hidden>
Phil Bordelon <address@hidden>
CCVVSS HHEEAADDEERR
$Id: emerge.1,v 1.37 2003/05/20 09:16:00 carpaski Exp $
Portage 2.0.47 Feb 2003 EMERGE(1)
- None, cheri, 2003/07/01
- None, collinsd, 2003/07/04
- None,
David de Gruyl <=