man/portage.5

   1 .TH "PORTAGE" "5" "Jan 2004" "Portage 2.0.51" "Portage"
   2 .SH NAME
   3 portage \- the heart of Gentoo
   4 .SH "DESCRIPTION"
   5 The current portage code uses many different configuration files, most of which
   6 are unknown to users and normal developers.  Here we will try to collect all
   7 the odds and ends so as to help users more effectively utilize portage.  This
   8 is a reference only for files which do not already have a man page.
   9
  10 All files in the make.profile directory may be tweaked via parent profiles
  11 when using cascading profiles.  For more info, please see
  12 http://www.gentoo.org/proj/en/releng/docs/cascading-profiles.xml
  13 .IP Note:
  14 If you are looking for information on how to emerge something, please see
  15 .BR emerge (1).
  16 .SH "SYNOPSIS"
  17 .TP
  18 .BR /etc/
  19 .nf
  20 make.globals
  21 .BR make.conf (5)
  22 .fi
  23 .TP
  24 .BR /etc/make.profile/
  25 .nf
  26 deprecated
  27 make.defaults
  28 packages
  29 packages.build
  30 package.provided
  31 parent
  32 use.defaults
  33 use.mask
  34 virtuals
  35 .fi
  36 .TP
  37 .BR /etc/portage/
  38 .nf
  39 bashrc
  40 package.mask
  41 package.unmask
  42 package.keywords
  43 package.use
  44 mirrors
  45 categories
  46 .fi
  47 .TP
  48 .BR /etc/portage/profile/
  49 site-specific overrides of \fB/etc/make.profile/\fR
  50 .TP
  51 .BR /usr/portage/profiles/
  52 .nf
  53 arch.list
  54 categories
  55 info_pkgs
  56 info_vars
  57 package.mask
  58 profiles.desc
  59 thirdpartymirrors
  60 use.desc
  61 use.local.desc
  62 .fi
  63 .TP
  64 .BR /var/lib/portage/
  65 world
  66 .SH "GLOSSARY"
  67 In the following sections, some terminology may be foreign to you or used
  68 with meaning specific to Portage.  Please see the referenced manpages for
  69 more detailed explanations.
  70 .RS
  71 .TP
  72 .B DEPEND atom
  73 A string which matches a package.  It is of the form category/package.
  74 It may also contain optional logical operators and versions.
  75 .br
  76 More reading:
  77 .BR ebuild (5)
  78 .TP
  79 .B KEYWORD
  80 Each architecture has a unique KEYWORD.
  81 .br
  82 More reading:
  83 .BR ebuild (5)
  84 .TP
  85 .B virtual
  86 A DEPEND atom that is part of the "virtual" category.  They are used
  87 when different packages can satisfy a dependency and only one of them is
  88 needed.
  89 .br
  90 More reading:
  91 .BR ebuild (5)
  92 .RE
  93 .SH "SPECIFIC FILE DESCRIPTIONS"
  94 .TP
  95 .BR /etc/
  96 .RS
  97 .TP
  98 .BR make.globals
  99 The global default settings for Portage.  This comes from the portage package
 100 itself.  Settings in \fBmake.conf\fR override values here.  The format
 101 is described extensivly in \fBmake.conf\fR(5).
 102 .TP
 103 .BR make.conf
 104 The global custom settings for Portage.  See \fBmake.conf\fR(5).
 105 .RE
 106 .TP
 107 .BR /etc/make.profile/
 108 This is usually just a symlink to the correct profile in
 109 \fB/usr/portage/profiles/\fR.  Since it is part of the portage tree, it
 110 may easily be updated/regenerated by running `emerge \-\-sync`.  It defines
 111 what a profile is (usually arch specific stuff).  If you need a custom
 112 profile, then you should make your own \fB/etc/make.profile/\fR
 113 directory and populate it.  However, if you just wish to override some
 114 settings, do NOT edit these files because they WILL be lost with the
 115 next `emerge \-\-sync`.  See the section below on \fB/etc/portage/\fR for
 116 overriding.
 117 .RS
 118 .TP
 119 .BR deprecated
 120 The existence of this file marks a profile as deprecated, meaning it is
 121 not supported by Gentoo anymore.  The first line must be the profile to which
 122 users are encouraged to upgrade, optionally followed by some instructions
 123 explaining how they can upgrade.
 124
 125 .I Example:
 126 .nf
 127 default-linux/x86/2005.0
 128 # emerge -n '>=sys-apps/portage-2.0.51'
 129 # rm -f /etc/make.profile
 130 # ln -s /usr/portage/profiles/default-linux/alpha/2005.0 /etc/make.profile
 131 .fi
 132 .TP
 133 .BR make.defaults
 134 The profile default settings for Portage.  The general format is described
 135 in \fBmake.conf\fR(5).  The \fImake.defaults\fR for your profile defines a
 136 few specific variables too:
 137
 138 .PD 0
 139 .RS
 140 .TP
 141 .BR ARCH
 142 Architecture type (x86/ppc/hppa/etc...).
 143 .TP
 144 .B USERLAND = \fI"GNU"\fR
 145 Support BSD/cygwin/etc...
 146 .TP
 147 .B PORTAGE_LIBC = \fI"glibc"\fR
 148 Support uClibc/BSD libc/etc...
 149 .TP
 150 .BR PROFILE_ARCH
 151 Distinguish machines classes that have the same \fBARCH\fR.  All sparc
 152 machines have ARCH=sparc but set this to either 'sparc32' or 'sparc64'.
 153 .TP
 154 .BR STAGE1_USE
 155 Special USE flags which may be needed when bootstrapping from stage1 to stage2.
 156 .TP
 157 .BR GRP_STAGE23_USE
 158 Special USE flags used by catalyst for building a stage3 and GRP sets.
 159 .RE
 160 .PD 1
 161 .TP
 162 .BR packages
 163 This file serves two purposes.  The first is to mask out specific
 164 packages/versions on a per\-profile basis.  The second is to provide the
 165 list of packages that compose the special \fIsystem\fR class.
 166
 167 .I Format:
 168 .nf
 169 \- comments begin with #
 170 \- one DEPEND atom per line of what to mask OUT
 171 \- packages to be added to the system class begin with a *
 172 .fi
 173 .I Note:
 174 In a cascading profile setup, you can remove packages in children
 175 profiles which were added by parent profiles by prefixing the atom with
 176 a '\-'.
 177
 178 .I Example:
 179 .nf
 180 # i am a comment !
 181 # only allow versions of glibc less than 2.3
 182 <sys\-libs/glibc\-2.3
 183 # add any version of bash to the system class
 184 *app\-shells/bash
 185 # only allow versions of readline earlier than 4.2
 186 # and add it to the system class
 187 *<sys\-libs/readline\-4.2
 188 .fi
 189 .TP
 190 .BR packages.build
 191 A list of packages (one per line) that make up a stage1 tarball.  Really only
 192 useful for stage builders.
 193 .TP
 194 .BR package.provided
 195 A list of packages (one per line) that portage should assume have been
 196 provided.  Useful for porting to non-Linux systems.  Portage will not
 197 attempt to update a package that is listed here unless another package
 198 explicitly requires a version that is newer than what has been listed.
 199 Basically, it's a list that replaces the \fBemerge \-\-inject\fR syntax.
 200
 201 For example, if you manage your own copy of a 2.6 kernel, then you can
 202 tell portage that 'sys-kernel/development-sources-2.6.7' is already taken
 203 care of and it should get off your back about it.
 204
 205 .I Format:
 206 .nf
 207 \- comments begin with #
 208 \- one DEPEND atom per line
 209 \- relational operators are not allowed
 210 \- must include a version
 211 .fi
 212
 213 .I Example:
 214 .nf
 215 # you take care of the kernel
 216 sys-kernel/development-sources-2.6.7
 217
 218 # you installed your own special copy of QT
 219 x11-libs/qt-3.3.0
 220 .fi
 221 .TP
 222 .BR parent
 223 This contains a path to the parent profile.  It may be either relative or
 224 absolute.  The paths will be relative to the location of the profile.  Most
 225 commonly this file contains '..' to indicate the directory above.  Utilized
 226 only in cascading profiles.
 227 .TP
 228 .BR use.defaults
 229 Here we DO NOT define the default USE flags, but the so\-called auto\-USE
 230 flags.  This rather unknown portage feature activates a USE flag if a
 231 specific package is installed and the flag was not explicitly
 232 deactivated.  This file contains the associations between USE flags and
 233 packages that trigger the auto\-USE feature.
 234
 235 In other words, if we never put "sdl" or "\-sdl" into our USE, but we
 236 have media\-libs/libsdl emerged, then portage automagically sticks "sdl"
 237 into our USE for us.
 238
 239 .I Format:
 240 .nf
 241 \- comments begin with #
 242 \- one USE flag per line with a list of DEPEND atom bases
 243 .fi
 244
 245 .I Example:
 246 .nf
 247 # media\-libs/libsdl will activate "sdl"
 248 sdl        media\-libs/libsdl
 249 # activate tcltk only if we have both
 250 # dev\-lang/tcl and dev\-lang/tk
 251 tcltk      dev\-lang/tcl   dev\-lang/tk
 252 .fi
 253 .TP
 254 .BR use.mask
 255 Some USE flags don't make sense on some archs (for example altivec on
 256 non\-ppc or mmx on non\-x86), or haven't yet been tested.  Here we list
 257 the masked ones.
 258
 259 .I Note:
 260 In a cascading profile setup, you can remove USE flags in children
 261 profiles which were added by parent profiles by prefixing the flag with
 262 a '\-'.
 263
 264 .I Format:
 265 .nf
 266 \- comments begin with #
 267 \- one USE flag per line
 268 .fi
 269 .TP
 270 .BR virtuals
 271 This controls what packages will provide a virtual by default.  For example,
 272 if a package needs to send e\-mail, it will need virtual/mta.  In the absence
 273 of a package that provides virtual/mta (like qmail, sendmail, postfix, etc...),
 274 portage will look here to see what package to use.  In this case, Gentoo uses
 275 net\-mail/ssmtp as the default (as defined in the virtuals file) because it's
 276 the package that does the very bare minimum to send e\-mail.
 277
 278 .I Format:
 279 .nf
 280 \- comments begin with #
 281 \- one virtual and DEPEND atom base pair per line
 282 .fi
 283
 284 .I Example:
 285 .nf
 286 # use net\-mail/ssmtp as the default mta
 287 virtual/mta           net\-mail/ssmtp
 288 # use app\-dicts/aspell\-en as the default dictionary
 289 virtual/aspell\-dict   app\-dicts/aspell\-en
 290 .fi
 291 .RE
 292 .TP
 293 .BR /etc/portage/
 294 .RS
 295 .TP
 296 .BR bashrc
 297 If needed, this file can be used to set up a special environment for ebuilds,
 298 different from the standard root environment.  The syntax is the same as for
 299 any other bash script.
 300 .TP
 301 .BR package.mask
 302 A list of DEPEND atoms to mask.  Useful if specific versions of packages do
 303 not work well for you.  For example, you swear by the Nvidia drivers, but only
 304 versions earlier than 1.0.4496.  No problem!
 305
 306 .I Format:
 307 .nf
 308 \- comments begin with #
 309 \- one DEPEND atom per line
 310 .fi
 311
 312 .I Example:
 313 .nf
 314 # mask out versions 1.0.4496 of the nvidia
 315 # drivers and later
 316 >=media\-video/nvidia\-kernel\-1.0.4496
 317 >=media\-video/nvidia\-glx\-1.0.4496
 318 .fi
 319 .TP
 320 .BR package.unmask
 321 Just like package.mask above, except here you list packages you want to
 322 unmask.  Useful for overriding the global package.mask file (see
 323 below).  Note that this does not override packages that are masked via
 324 KEYWORDS.
 325 .TP
 326 .BR package.keywords
 327 Per\-package KEYWORDS.  Useful for mixing unstable packages in with a normally
 328 stable machine or vice versa.  This will allow you to augment ACCEPT_KEYWORDS
 329 for a single package.
 330
 331 .nf
 332 \fINote:\fR There are two special KEYWORDS to help out here:
 333 \fB*\fR  Match any stable KEYWORD
 334 \fB~*\fR Match any unstable KEYWORD
 335
 336 .I Format:
 337 \- comments begin with #
 338 \- one DEPEND atom per line followed by additional KEYWORDS
 339 \- blank lines imply unstable host arch
 340
 341 .I Example:
 342 # always use unstable libgd
 343 media\-libs/libgd ~x86
 344 # only use stable mplayer
 345 media\-video/mplayer \-~x86
 346 # always use unstable netcat
 347 net-analyzer/netcat
 348 .fi
 349
 350 .I Additional Note:
 351 If you encounter the \fB-*\fR KEYWORD, this indicates that the package is known
 352 to be broken on all systems which are not otherwise listed in KEYWORDS.  For
 353 example, a binary only package which is built for x86 will look like:
 354
 355 games-fps/quake3-demo-1.11.ebuild:KEYWORDS="-* x86"
 356
 357 If you wish to accept this package anyways, then add \fB-*\fR to your
 358 package.keywords like this:
 359
 360 games-fps/quake3-demo -*
 361 .TP
 362 .BR package.use
 363 Per\-package USE flags.  Useful for tracking local USE flags or for
 364 enabling USE flags for certain packages only.  Perhaps you develop GTK
 365 and thus you want documentation for it, but you don't want
 366 documentation for QT.  Easy as pie my friend!
 367
 368 .I Format:
 369 .nf
 370 \- comments begin with #
 371 \- one DEPEND atom per line with space-delimited USE flags
 372 .fi
 373
 374 .I Example:
 375 .nf
 376 # turn on docs for GTK 2.x
 377 =x11\-libs/gtk+\-2* doc
 378 # disable mysql support for QT
 379 x11\-libs/qt \-mysql
 380 .fi
 381 .TP
 382 .BR mirrors
 383 Whenever portage encounters a mirror:// style URL it will look up the actual
 384 hosts here.  If the mirror set is not found here, it will check the global
 385 mirrors file at /usr/portage/profiles/thirdpartymirrors.  You may also set a
 386 special mirror type called "local".  This list of mirrors will be checked
 387 before GENTOO_MIRRORS and will be used even if the package has
 388 RESTRICT="nomirror".
 389
 390 .I Format:
 391 .nf
 392 \- comments begin with #
 393 \- mirror type followed by a list of hosts
 394 .fi
 395
 396 .I Example:
 397 .nf
 398 # local private mirrors used only by my company
 399 local ftp://192.168.0.3/mirrors/gentoo http://192.168.0.4/distfiles
 400
 401 # people in japan would want to use the japanese mirror first
 402 sourceforge http://keihanna.dl.sourceforge.net/sourceforge
 403
 404 # people in tawain would want to use the local gnu mirror first
 405 gnu ftp://ftp.nctu.edu.tw/UNIX/gnu/
 406 .fi
 407 .TP
 408 .BR categories
 409 A simple list of valid categories that may be used in /usr/portage,
 410 PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)).  This allows for custom
 411 categories to be created.
 412
 413 .I Format:
 414 .nf
 415 \- one category per line
 416 .fi
 417
 418 .I Example:
 419 .nf
 420 app\-hackers
 421 media\-other
 422 .fi
 423 .TP
 424 .BR /usr/portage/profiles/
 425 Global Gentoo settings that are controlled by the developers.  To override
 426 these settings, you can use the files in \fB/etc/portage/\fR.
 427 .RS
 428 .TP
 429 .BR arch.list
 430 A list of all valid KEYWORDS.  This does not include modifiers.
 431
 432 .I Format:
 433 .nf
 434 \- one KEYWORD per line
 435 .fi
 436
 437 .I Example:
 438 .nf
 439 x86
 440 ppc
 441 sparc
 442 .fi
 443 .TP
 444 .BR categories
 445 A simple list of valid categories that may be used in /usr/portage,
 446 PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)).
 447
 448 .I Format:
 449 .nf
 450 \- one category per line
 451 .fi
 452
 453 .I Example:
 454 .nf
 455 app\-admin
 456 dev\-lang
 457 games\-strategy
 458 sys\-kernel
 459 .fi
 460 .TP
 461 .BR info_pkgs
 462 A list of all the packages which will be displayed when you run `emerge info`.
 463 .TP
 464 .BR info_vars
 465 A list of all the variables which will be displayed when you run `emerge info`.
 466 .TP
 467 .BR package.mask
 468 This contains a list of DEPEND atoms for packages that should not be installed
 469 in any profile.  Useful for adding the latest KDE betas and making sure no
 470 one accidentally upgrades to them.  Also useful for quickly masking specific
 471 versions due to security issues.  ALWAYS include a comment explaining WHY the
 472 package has been masked and WHO is doing the masking.
 473
 474 .I Format:
 475 .nf
 476 \- comments begin with #
 477 \- one DEPEND atom per line
 478 .fi
 479
 480 .I Example:
 481 .nf
 482 # masked for security reasons
 483 <sys\-libs/zlib\-1.1.4
 484 # <caleb@gentoo.org> (10 Sep 2003)
 485 # new kde betas
 486 =kde\-base/kde\-3.2.0_beta1
 487 =kde\-base/kdeaccessibility\-3.2.0_beta1
 488 .fi
 489 .TP
 490 .BR profiles.desc
 491 List all the current stable and development profiles.  If a profile is listed
 492 here, then it will be checked by repoman.  At the moment, only 1 profile is
 493 allowed per stable/dev/KEYWORD; the last one found is the last one used.
 494
 495 .I Format:
 496 .nf
 497 \- comments begin with #
 498 \- one profile list per line in format: arch dir status
 499 \- arch must be listed in arch.list
 500 \- dir is relative to profiles.desc
 501 \- status must be 'stable' or 'dev'
 502 .fi
 503
 504 .I Example:
 505 .nf
 506 alpha default-linux/alpha/2004.3 stable
 507 m68k  default-linux/m68k         dev
 508 x86   default-linux/x86/2004.3   stable
 509 .fi
 510 .TP
 511 .BR thirdpartymirrors
 512 Controls the mapping of mirror:// style URLs to actual lists of
 513 mirrors.  Keeps us from overloading a single server.
 514
 515 .I Format:
 516 .nf
 517 \- comments begin with #
 518 \- mirror type followed by a list of hosts
 519 .fi
 520
 521 .I Example:
 522 .nf
 523 sourceforge http://aleron.dl.sourceforge.net/sourceforge http://unc.dl.sourceforge.net/sourceforge
 524
 525 gentoo http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles/ ftp://ftp.gtlib.cc.gatech.edu/pub/gentoo/distfiles
 526
 527 kernel http://www.kernel.org/pub http://www.us.kernel.org/pub
 528 .fi
 529 .TP
 530 .BR use.desc
 531 All global USE flags must be listed here with a description of what they do.
 532
 533 .I Format:
 534 .nf
 535 \- comments begin with #
 536 \- use flag \- some description
 537 .fi
 538
 539 .I Example:
 540 .nf
 541 3dfx \- Adds support for 3dfx video cards
 542 acl \- Adds support for Access Control Lists
 543 doc \- Adds extra documentation
 544 .fi
 545 .TP
 546 .BR use.local.desc
 547 All local USE flags must be listed here along with the package and a
 548 description.
 549
 550 .nf
 551 .I Format:
 552 \- comments begin with #
 553 \- package:use flag \- description
 554
 555 .I Example:
 556 app\-editors/nano:justify \- Toggles the justify option
 557 dev\-libs/DirectFB:fusion \- Adds Multi Application support
 558 games\-emulation/xmess:net \- Adds network support
 559 .fi
 560 .RE
 561 .TP
 562 .BR /var/lib/portage/
 563 .RS
 564 .TP
 565 .BR world
 566 Every time you emerge a package, the package that you requested is
 567 recorded here.  Then when you run `emerge world \-up`, the list of
 568 packages is read from this file.  Note that this does not mean that the
 569 packages that were installed as dependencies are listed here.  For
 570 example, if you run `emerge mod_php` and you do not have apache
 571 already, then "dev\-php/mod_php" is recorded in the world file but
 572 "net\-www/apache" is not.  For more information, review \fBemerge\fR(1).
 573
 574 .I Format:
 575 .nf
 576 \- one DEPEND atom base per line
 577 .fi
 578
 579 .I Example:
 580 .nf
 581 games\-misc/fortune\-mod\-gentoo\-dev
 582 dev\-libs/uclibc
 583 app\-cdr/cdemu
 584 .fi
 585 .RE
 586 .SH "AUTHORS"
 587 .nf
 588 Marius Mauch <genone@gentoo.org>
 589 Mike Frysinger <vapier@gentoo.org>
 590 Drake Wyrm <wyrm@haell.com>
 591 .fi
 592 .SH "REPORTING BUGS"
 593 Please report bugs via http://bugs.gentoo.org/
 594 .SH "SEE ALSO"
 595 .BR emerge (1),
 596 .BR ebuild (1),
 597 .BR ebuild (5),
 598 .BR make.conf (5)