man/portage.5

   1 .TH "PORTAGE" "5" "May 2011" "Portage VERSION" "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 .BR make.conf (5)
  21 .fi
  22 .TP
  23 \fB/etc/make.profile/\fR or \fB/etc/portage/make.profile/\fR
  24 site\-specific overrides go in \fB/etc/portage/profile/\fR
  25 .nf
  26 deprecated
  27 eapi
  28 make.defaults
  29 packages
  30 packages.build
  31 package.accept_keywords
  32 package.keywords
  33 package.mask
  34 package.provided
  35 package.unmask
  36 package.use
  37 package.use.force
  38 package.use.mask
  39 parent
  40 profile.bashrc
  41 use.force
  42 use.mask
  43 virtuals
  44 .fi
  45 .TP
  46 .BR /etc/portage/
  47 .nf
  48 bashrc
  49 categories
  50 color.map
  51 license_groups
  52 make.conf
  53 mirrors
  54 modules
  55 package.accept_keywords
  56 package.env
  57 package.keywords
  58 package.license
  59 package.mask
  60 package.properties
  61 package.unmask
  62 package.use
  63 repos.conf
  64 .fi
  65 .TP
  66 .BR /etc/portage/env/
  67 package-specific bashrc files
  68 .TP
  69 .BR /etc/portage/profile/
  70 site-specific overrides of \fB/etc/make.profile/\fR
  71 .TP
  72 .BR /usr/portage/metadata/
  73 .nf
  74 layout.conf
  75 .fi
  76 .TP
  77 .BR /usr/portage/profiles/
  78 .nf
  79 arch.list
  80 categories
  81 info_pkgs
  82 info_vars
  83 license_groups
  84 make.defaults
  85 package.mask
  86 package.unmask
  87 package.use
  88 package.use.force
  89 package.use.mask
  90 profiles.desc
  91 repo_name
  92 thirdpartymirrors
  93 use.desc
  94 use.force
  95 use.local.desc
  96 use.mask
  97 .fi
  98 .TP
  99 .BR /usr/share/portage/config/
 100 .nf
 101 make.globals
 102 .fi
 103 .TP
 104 .BR /var/cache/edb/
 105 misc internal cache files
 106 .TP
 107 .BR /var/db/pkg/
 108 database to track installed packages
 109 .TP
 110 .BR /var/lib/portage/
 111 .nf
 112 config
 113 world
 114 world_sets
 115 .fi
 116 .SH "GLOSSARY"
 117 In the following sections, some terminology may be foreign to you or used
 118 with meaning specific to Portage.  Please see the referenced manpages for
 119 more detailed explanations.
 120 .RS
 121 .TP
 122 .B DEPEND atom
 123 An atom is either of the form category/package or consists of an operator
 124 followed by category/package followed by a hyphen and a version specification.
 125 An atom might be suffixed by a slot specification.
 126 .br
 127 More reading:
 128 .BR ebuild (5)
 129
 130 .B Extended Atom Syntax
 131 .br
 132 The following atom syntax extensions are only supported in user
 133 configuration files and command line arguments for programs such as
 134 \fBemerge(1)\fR:
 135 .RS
 136 .TP
 137 .B Repository Constraints
 138 Atoms with repository constraints have a '::' separator appended to the
 139 right side, followed by a repository name. Each repository name should
 140 correspond to the value of a \fBrepo_name\fR entry from one of the
 141 repositories that is configured via the \fBPORTDIR\fR or
 142 \fBPORTDIR_OVERLAY\fR variables (see \fBmake.conf\fR(5)).
 143
 144 .I Examples:
 145 .nf
 146 # match sed from the 'gentoo' repository
 147 sys\-apps/sed::gentoo
 148 # match kdelibs from the 'kde\-testing' repository
 149 kde\-base/kdelibs::kde\-testing
 150 # match empathy from the 'gnome' repository
 151 net\-im/empathy::gnome
 152 .fi
 153 .TP
 154 .B Wildcard Patterns
 155 Atoms containing wildcard patterns are of the form category/package, where
 156 the special '*' wildcard character substitutes for an arbitrary number
 157 of normal characters. More than one '*' character is allowed, but not two
 158 next to each other.
 159
 160 .I Examples:
 161 .nf
 162 # match anything from the 'sys\-apps' category
 163 sys\-apps/*
 164 # match packages named 'zlib' from any category
 165 */zlib
 166 # match any package from a category that begins with 'net\-'
 167 net\-*/*
 168 # match any package name from any category
 169 */*
 170 # match any package from the 'gentoo' repository
 171 */*::gentoo
 172 .fi
 173 .RE
 174 .TP
 175 .B KEYWORD
 176 Each architecture has a unique KEYWORD.
 177 .br
 178 More reading:
 179 .BR ebuild (5)
 180 .TP
 181 .B virtual
 182 A DEPEND atom that is part of the "virtual" category.  They are used
 183 when different packages can satisfy a dependency and only one of them is
 184 needed.
 185 .br
 186 More reading:
 187 .BR ebuild (5)
 188 .RE
 189 .SH "SPECIFIC FILE DESCRIPTIONS"
 190 .TP
 191 .BR /etc/
 192 .RS
 193 .TP
 194 .BR make.conf
 195 The global custom settings for Portage.  See \fBmake.conf\fR(5).
 196 .RE
 197 .TP
 198 \fB/etc/make.profile/\fR or \fB/etc/portage/make.profile/\fR
 199 This is usually just a symlink to the correct profile in
 200 \fB/usr/portage/profiles/\fR.  Since it is part of the portage tree, it
 201 may easily be updated/regenerated by running `emerge \-\-sync`.  It defines
 202 what a profile is (usually arch specific stuff).  If you need a custom
 203 profile, then you should make your own \fB/etc/make.profile/\fR
 204 directory and populate it.  However, if you just wish to override some
 205 settings, use \fB/etc/portage/profile/\fR (it supports all of the same file
 206 types that \fB/etc/make.profile/\fR does, except parent). Do NOT edit the
 207 settings in \fB/etc/make.profile/\fR because they WILL be lost with the next
 208 `emerge \-\-sync`. If both \fB/etc/make.profile/\fR and
 209 \fB/etc/portage/make.profile/\fR exist, then \fB/etc/make.profile/\fR
 210 will be preferred.
 211
 212 Any file in this directory, directories of other profiles or top-level
 213 "profiles" directory that begins with "package." or "use." can be more than
 214 just a flat file.  If it is a directory, then all the files in that directory
 215 will be sorted in ascending alphabetical order by file name and summed together
 216 as if it were a single file. Note that this behavior is only supported since
 217 portage-2.1.6.7, and it is not included in PMS at this time.
 218
 219 .I Example:
 220 .nf
 221 ${PORTDIR}/profiles/package.mask/removals
 222 ${PORTDIR}/profiles/package.mask/testing
 223 .fi
 224 .RS
 225 .TP
 226 .BR deprecated
 227 The existence of this file marks a profile as deprecated, meaning it is
 228 not supported by Gentoo anymore.  The first line must be the profile to which
 229 users are encouraged to upgrade, optionally followed by some instructions
 230 explaining how they can upgrade.
 231
 232 .I Example:
 233 .nf
 234 default-linux/x86/2005.0
 235 # emerge -n '>=sys-apps/portage-2.0.51'
 236 # rm -f /etc/make.profile
 237 # ln -s /usr/portage/profiles/default-linux/alpha/2005.0 /etc/make.profile
 238 .fi
 239 .TP
 240 .BR eapi
 241 The first line of this file specifies the \fBEAPI\fR to which files in the
 242 same directory conform. See \fBebuild\fR(5) for information about \fBEAPI\fR
 243 and related features.
 244 .TP
 245 .BR make.defaults
 246 The profile default settings for Portage.  The general format is described
 247 in \fBmake.conf\fR(5).  The \fImake.defaults\fR for your profile defines a
 248 few specific variables too:
 249
 250 .PD 0
 251 .RS
 252 .TP
 253 .BR ARCH
 254 Architecture type (x86/ppc/hppa/etc...).
 255 .TP
 256 .B USERLAND = \fI"GNU"\fR
 257 Support BSD/cygwin/etc...
 258 .TP
 259 .B ELIBC = \fI"glibc"\fR
 260 Support uClibc/BSD libc/etc...
 261 .TP
 262 .B PROFILE_ONLY_VARIABLES = \fI"ARCH"\fR
 263 Prevent critical variables from being changed by the user in make.conf
 264 or the env.
 265 .TP
 266 .BR PROFILE_ARCH
 267 Distinguish machines classes that have the same \fBARCH\fR.  All sparc
 268 machines have ARCH=sparc but set this to either 'sparc32' or 'sparc64'.
 269 .TP
 270 .BR STAGE1_USE
 271 Special USE flags which may be needed when bootstrapping from stage1 to stage2.
 272 .RE
 273 .PD 1
 274 .TP
 275 .BR packages
 276 Provides the list of packages that compose the special \fIsystem\fR set.
 277
 278 .I Format:
 279 .nf
 280 \- comments begin with # (no inline comments)
 281 \- one DEPEND atom per line
 282 \- packages to be added to the system set begin with a *
 283 \- atoms without * only appear for legacy reasons
 284 .fi
 285 .I Note:
 286 In a cascading profile setup, you can remove packages in children
 287 profiles which were added by parent profiles by prefixing the atom with
 288 a '\-'.
 289
 290 .I Example:
 291 .nf
 292 # i am a comment !
 293 # pull in a version of glibc less than 2.3
 294 *<sys\-libs/glibc\-2.3
 295 # pull in any version of bash
 296 *app\-shells/bash
 297 # pull in a version of readline earlier than 4.2
 298 *<sys\-libs/readline\-4.2
 299 .fi
 300 .TP
 301 .BR packages.build
 302 A list of packages (one per line) that make up a stage1 tarball.  Really only
 303 useful for stage builders.
 304 .TP
 305 .BR package.provided
 306 A list of packages (one per line) that portage should assume have been
 307 provided.  Useful for porting to non-Linux systems. Basically, it's a
 308 list that replaces the \fBemerge \-\-inject\fR syntax.
 309
 310 For example, if you manage your own copy of a 2.6 kernel, then you can
 311 tell portage that 'sys-kernel/development-sources-2.6.7' is already taken
 312 care of and it should get off your back about it.
 313
 314 Portage will not attempt to update a package that is listed here unless
 315 another package explicitly requires a version that is newer than what
 316 has been listed. Dependencies that are satisfied by package.provided
 317 entries may cause installed packages satisfying equivalent dependencies
 318 to be removed by \fBemerge\fR(1) \fB\-\-depclean\fR actions (see the
 319 \fBACTIONS\fR section of the \fBemerge\fR(1) man page for more information).
 320
 321 Virtual packages (virtual/*) should not be specified in package.provided.
 322 Depending on the type of virtual, it may be necessary to add an entry to the
 323 virtuals file and/or add a package that satisfies a virtual to
 324 package.provided.
 325
 326 .I Format:
 327 .nf
 328 \- comments begin with # (no inline comments)
 329 \- one DEPEND atom per line
 330 \- relational operators are not allowed
 331 \- must include a version
 332 .fi
 333
 334 .I Example:
 335 .nf
 336 # you take care of the kernel
 337 sys-kernel/development-sources-2.6.7
 338
 339 # you installed your own special copy of QT
 340 x11-libs/qt-3.3.0
 341
 342 # you have modular X but packages want monolithic
 343 x11-base/xorg-x11-6.8
 344 .fi
 345 .TP
 346 .BR package.use.force
 347 Per\-package USE flag forcing.
 348
 349 .I Note:
 350 In a cascading profile setup, you can remove USE flags in children
 351 profiles which were added by parent profiles by prefixing the flag with
 352 a '\-'.
 353
 354 .I Format:
 355 .nf
 356 \- comments begin with # (no inline comments)
 357 \- one DEPEND atom per line with space-delimited USE flags
 358 .fi
 359
 360 .I Example:
 361 .nf
 362 # force docs for GTK 2.x
 363 =x11\-libs/gtk+\-2* doc
 364 # unforce mysql support for QT
 365 x11\-libs/qt \-mysql
 366 .fi
 367 .TP
 368 .BR package.use.mask
 369 Per\-package USE flag masks.
 370
 371 .I Note:
 372 In a cascading profile setup, you can remove USE flags in children
 373 profiles which were added by parent profiles by prefixing the flag with
 374 a '\-'.
 375
 376 .I Format:
 377 .nf
 378 \- comments begin with # (no inline comments)
 379 \- one DEPEND atom per line with space-delimited USE flags
 380 .fi
 381
 382 .I Example:
 383 .nf
 384 # mask docs for GTK 2.x
 385 =x11\-libs/gtk+\-2* doc
 386 # unmask mysql support for QT
 387 x11\-libs/qt \-mysql
 388 .fi
 389 .TP
 390 .BR parent
 391 This contains a path to the parent profile.  It may be either relative or
 392 absolute.  The paths will be relative to the location of the profile.  Most
 393 commonly this file contains '..' to indicate the directory above.  Utilized
 394 only in cascading profiles.
 395 .TP
 396 .BR profile.bashrc
 397 If needed, this file can be used to set up a special environment for ebuilds,
 398 different from the standard root environment.  The syntax is the same as for
 399 any other bash script.
 400 .TP
 401 .BR use.force
 402 Some USE flags don't make sense to disable under certain conditions.  Here we
 403 list forced flags.
 404
 405 .I Note:
 406 In a cascading profile setup, you can remove USE flags in children
 407 profiles which were added by parent profiles by prefixing the flag with
 408 a '\-'.
 409
 410 .I Format:
 411 .nf
 412 \- comments begin with # (no inline comments)
 413 \- one USE flag per line
 414 .fi
 415 .TP
 416 .BR use.mask
 417 Some USE flags don't make sense on some archs (for example altivec on
 418 non\-ppc or mmx on non\-x86), or haven't yet been tested.  Here we list
 419 the masked ones.
 420
 421 .I Note:
 422 In a cascading profile setup, you can remove USE flags in children
 423 profiles which were added by parent profiles by prefixing the flag with
 424 a '\-'.
 425
 426 .I Format:
 427 .nf
 428 \- comments begin with # (no inline comments)
 429 \- one USE flag per line
 430 .fi
 431
 432 .I Example:
 433 .nf
 434 # mask doc
 435 doc
 436 # unmask mysql
 437 \-mysql
 438 .fi
 439 .TP
 440 .BR virtuals
 441 This controls what packages will provide a virtual by default.  For example,
 442 if a package needs to send e\-mail, it will need virtual/mta.  In the absence
 443 of a package that provides virtual/mta (like qmail, sendmail, postfix, etc...),
 444 portage will look here to see what package to use.  In this case, Gentoo uses
 445 net\-mail/ssmtp as the default (as defined in the virtuals file) because it's
 446 the package that does the very bare minimum to send e\-mail.
 447
 448 .I Format:
 449 .nf
 450 \- comments begin with # (no inline comments)
 451 \- one virtual and DEPEND atom base pair per line
 452 .fi
 453
 454 .I Example:
 455 .nf
 456 # use net\-mail/ssmtp as the default mta
 457 virtual/mta           net\-mail/ssmtp
 458 # use app\-dicts/aspell\-en as the default dictionary
 459 virtual/aspell\-dict   app\-dicts/aspell\-en
 460 .fi
 461 .RE
 462 .TP
 463 .BR /etc/portage/
 464 Any file in this directory that begins with "package." can be more than just a
 465 flat file.  If it is a directory, then all the files in that directory will be
 466 sorted in ascending alphabetical order by file name and summed together as if
 467 it were a single file.
 468
 469 .I Example:
 470 .nf
 471 /etc/portage/package.accept_keywords/common
 472 /etc/portage/package.accept_keywords/e17
 473 /etc/portage/package.accept_keywords/kde
 474 .fi
 475 .RS
 476 .TP
 477 .BR bashrc
 478 If needed, this file can be used to set up a special environment for ebuilds,
 479 different from the standard root environment.  The syntax is the same as for
 480 any other bash script.
 481
 482 Additional package-specific bashrc files can be created in /etc/portage/env.
 483 .TP
 484 .BR categories
 485 A simple list of valid categories that may be used in /usr/portage,
 486 PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)).  This allows for custom
 487 categories to be created.
 488
 489 .I Format:
 490 .nf
 491 \- one category per line
 492 .fi
 493
 494 .I Example:
 495 .nf
 496 app\-hackers
 497 media\-other
 498 .fi
 499 .TP
 500 .BR color.map
 501 Contains variables customizing colors. See \fBcolor.map\fR(5).
 502 .TP
 503 .BR make.conf
 504 The global custom settings for Portage. See \fBmake.conf\fR(5).
 505 If present, this file will override settings from /etc/make.conf.
 506 .TP
 507 .BR mirrors
 508 Whenever portage encounters a mirror:// style URI it will look up the actual
 509 hosts here.  If the mirror set is not found here, it will check the global
 510 mirrors file at /usr/portage/profiles/thirdpartymirrors.  You may also set a
 511 special mirror type called "local".  This list of mirrors will be checked
 512 before GENTOO_MIRRORS and will be used even if the package has
 513 RESTRICT="mirror" or RESTRICT="fetch".
 514
 515 .I Format:
 516 .nf
 517 \- comments begin with # (no inline comments)
 518 \- mirror type followed by a list of hosts
 519 .fi
 520
 521 .I Example:
 522 .nf
 523 # local private mirrors used only by my company
 524 local ftp://192.168.0.3/mirrors/gentoo http://192.168.0.4/distfiles
 525
 526 # people in japan would want to use the japanese mirror first
 527 sourceforge http://keihanna.dl.sourceforge.net/sourceforge
 528
 529 # people in tawain would want to use the local gnu mirror first
 530 gnu ftp://ftp.nctu.edu.tw/UNIX/gnu/
 531 .fi
 532 .TP
 533 .BR modules
 534 This file can be used to override the metadata cache implementation.  In
 535 practice, portdbapi.auxdbmodule is the only variable that the user will want to
 536 override.
 537
 538 .I Example:
 539 .nf
 540 portdbapi.auxdbmodule = portage.cache.sqlite.database
 541 .fi
 542
 543 After changing the portdbapi.auxdbmodule setting, it may be necessary to
 544 transfer or regenerate metadata cache. Users of the rsync tree need to
 545 run `emerge \-\-metadata` if they have enabled FEATURES="metadata-transfer"
 546 in \fBmake.conf\fR(5). In order to regenerate metadata for repositories
 547 listed in \fBPORTDIR_OVERLAY\fR or a cvs tree, run `emerge \-\-regen`
 548 (see \fBemerge\fR(1)). If you use something like the sqlite module and want
 549 to keep all metadata in that format alone (useful for querying), enable
 550 FEATURES="metadata-transfer" in \fBmake.conf\fR(5).
 551 .TP
 552 \fBpackage.accept_keywords\fR and \fBpackage.keywords\fR
 553 Per\-package ACCEPT_KEYWORDS.  Useful for mixing unstable packages in with a normally
 554 stable system or vice versa.  This will allow ACCEPT_KEYWORDS to be augmented
 555 for a single package. If both \fBpackage.accept_keywords\fR and
 556 \fBpackage.keywords\fR are present, both of them will be used, and values
 557 from \fBpackage.accept_keywords\fR will override values from
 558 \fBpackage.keywords\fR. The \fBpackage.accept_keywords\fR file is
 559 intended to replace the \fBpackage.keywords\fR file, since
 560 profiles support a different form of \fBpackage.keywords\fR which
 561 modifies effective KEYWORDS (rather than ACCEPT_KEYWORDS).
 562
 563 .I Format:
 564 .nf
 565 \- comment lines begin with # (no inline comments)
 566 \- one DEPEND atom per line followed by additional KEYWORDS
 567 \- lines without any KEYWORDS imply unstable host arch
 568
 569 .I Example:
 570 # always use unstable libgd
 571 media\-libs/libgd ~x86
 572 # only use stable mplayer
 573 media\-video/mplayer \-~x86
 574 # always use unstable netcat
 575 net-analyzer/netcat
 576 .fi
 577
 578 .I Note:
 579 .fi
 580 In addition to the normal values from ACCEPT_KEYWORDS package.keywords supports
 581 three special tokens:
 582
 583 .nf
 584 \fB*\fR  package is visible if it is stable on any architecture
 585 \fB~*\fR package is visible if it is in testing on any architecture
 586 \fB**\fR package is always visible (KEYWORDS are ignored completely)
 587 .fi
 588
 589 .I Additional Note:
 590 If you encounter the \fB-*\fR KEYWORD, this indicates that the package is known
 591 to be broken on all systems which are not otherwise listed in KEYWORDS.  For
 592 example, a binary only package which is built for x86 will look like:
 593
 594 games-fps/quake3-demo-1.11.ebuild:KEYWORDS="-* x86"
 595
 596 If you wish to accept this package anyways, then use one of the other keywords in your
 597 package.accept_keywords like this:
 598
 599 games-fps/quake3-demo x86
 600
 601 .TP
 602 .BR package.env
 603 Per\-package environment variable settings. Entries refer to
 604 environment files that are placed in the \fB/etc/portage/env/\fR
 605 directory and have the same format as \fBmake.conf\fR(5).
 606
 607 .I Format:
 608 .nf
 609 \- comment lines begin with # (no inline comments)
 610 \- one DEPEND atom per line followed by name(s) of environment file(s)
 611 .fi
 612
 613 .I Example:
 614 .nf
 615 # use environment variables from /etc/portage/env/glibc.conf for the glibc package
 616 sys\-libs/glibc glibc.conf
 617 .fi
 618
 619 .TP
 620 .BR package.license
 621 This will allow ACCEPT_LICENSE to be augmented for a single package.
 622
 623 .I Format:
 624 .nf
 625 \- comment lines begin with # (no inline comments)
 626 \- one DEPEND atom per line followed by additional licenses or groups
 627 .fi
 628 .TP
 629 .BR package.mask
 630 A list of package atoms to mask.  Useful if specific versions of packages do
 631 not work well for you.  For example, you swear by the Nvidia drivers, but only
 632 versions earlier than 1.0.4496.  No problem!
 633
 634 .I Format:
 635 .nf
 636 \- comment lines begin with # (no inline comments)
 637 \- one DEPEND atom per line
 638 .fi
 639
 640 .I Example:
 641 .nf
 642 # mask out versions 1.0.4496 of the nvidia
 643 # drivers and later
 644 >=media\-video/nvidia\-kernel\-1.0.4496
 645 >=media\-video/nvidia\-glx\-1.0.4496
 646 .fi
 647 .TP
 648 .BR package.properties
 649 This will allow ACCEPT_PROPERTIES to be augmented for a single package.
 650
 651 .I Format:
 652 .nf
 653 \- comment lines begin with # (no inline comments)
 654 \- one DEPEND atom per line followed by additional properties
 655 .fi
 656 .TP
 657 .BR package.unmask
 658 Just like package.mask above, except here you list packages you want to
 659 unmask.  Useful for overriding the global package.mask file (see
 660 above).  Note that this does not override packages that are masked via
 661 KEYWORDS.
 662 .TP
 663 .BR package.use
 664 Per\-package USE flags.  Useful for tracking local USE flags or for
 665 enabling USE flags for certain packages only.  Perhaps you develop GTK
 666 and thus you want documentation for it, but you don't want
 667 documentation for QT.  Easy as pie my friend!
 668
 669 .I Format:
 670 .nf
 671 \- comments begin with # (no inline comments)
 672 \- one DEPEND atom per line with space-delimited USE flags
 673 .fi
 674
 675 .I Example:
 676 .nf
 677 # turn on docs for GTK 2.x
 678 =x11\-libs/gtk+\-2* doc
 679 # disable mysql support for QT
 680 x11\-libs/qt \-mysql
 681 .fi
 682 .TP
 683 .BR repos.conf
 684 Specifies \fIsite\-specific\fR repository configuration information. Note that
 685 configuration settings which are specified here do not apply to tools
 686 such as \fBrepoman\fR(1) and \fBegencache\fR(1), since operations
 687 performed by these tools
 688 are inherently \fBnot\fR \fIsite\-specific\fR. \fBWARNING:\fR Use of
 689 \fBrepos.conf\fR is generally not recommended since resulting changes in
 690 eclass inheritance (especially due to \fBeclass\-overrides\fR) may trigger
 691 performance issues under some circumstances (see \fBbug #124041\fR). When
 692 using \fBeclass\-overrides\fR, due to bug #276264, you must ensure that
 693 your portage tree does not contain a metadata/cache/ directory. If that
 694 directory exists then you should remove it entirely, and set
 695 PORTAGE_RSYNC_EXTRA_OPTS="\-\-exclude=/metadata/cache" in
 696 make.conf in order to exclude the metadata/cache/ directory during
 697 \fBemerge\fR(1) \-\-sync operations.
 698
 699 .I Example:
 700 .nf
 701 [DEFAULT]
 702 # make all repositories inherit eclasses from the java\-overlay and
 703 # java\-experimental repositories, with eclasses from java\-experimental
 704 # taking precedence over those from java\-overlay
 705 eclass\-overrides = java\-overlay java\-experimental
 706
 707 [gentoo]
 708 # disable all eclass overrides for ebuilds from the gentoo repository
 709 eclass\-overrides =
 710 # when processing metadata/layout.conf from other repositories, substitute
 711 # 'gentoo' in place of references to repositories named 'foo' and 'bar'
 712 aliases = foo bar
 713
 714 [kde-testing]
 715 # override the metadata/layout.conf masters setting from the kde-testing repo
 716 masters = gentoo kde
 717 .fi
 718 .RE
 719 .TP
 720 .BR /etc/portage/env/
 721 .RS
 722 In this directory additional package\-specific bashrc files can be created.
 723 Note that if package\-specific environment variable settings are all that's
 724 needed, then \fB/etc/portage/package.env\fR should be used instead of the
 725 bashrc approach that is described here.
 726
 727 set_unless_changed and unset_unless_changed functions can be used to set or
 728 unset given variables only if these variable have not been set to values
 729 different than values set in make.conf. This functionality can be useful for
 730 temporary overriding of these variables during emerge invocation. Variables
 731 set without using set_unless_changed will unconditionally override variables
 732 set during emerge invocation.
 733
 734 .I Syntax:
 735 .nf
 736 set_unless_changed VARIABLE=VALUE
 737 unset_unless_changed VALUE
 738 .fi
 739
 740 Portage will source all of these bashrc files after \fB/etc/portage/bashrc\fR
 741 in the following order:
 742 .nr step 1 1
 743 .IP \n[step]. 3
 744 /etc/portage/env/${CATEGORY}/${PN}
 745 .IP \n+[step].
 746 /etc/portage/env/${CATEGORY}/${PN}:${SLOT}
 747 .IP \n+[step].
 748 /etc/portage/env/${CATEGORY}/${P}
 749 .IP \n+[step].
 750 /etc/portage/env/${CATEGORY}/${PF}
 751 .RE
 752 .TP
 753 .BR /usr/portage/metadata/
 754 .RS
 755 .TP
 756 .BR layout.conf
 757 Specifies information about the repository layout. A
 758 "masters" attribute is supported, which is used to specify names of
 759 repositories which satisfy dependencies on eclasses and/or ebuilds. Each
 760 repository name should correspond the value of a \fBrepo_name\fR entry
 761 from one of the repositories that is configured via the \fBPORTDIR\fR or
 762 \fBPORTDIR_OVERLAY\fR variables (see \fBmake.conf\fR(5)). Repositories listed
 763 toward the right of the \fBmasters\fR list take precedence over those listed
 764 toward the left of the list. An "aliases" attribute is also supported, which
 765 behaves like an "aliases" attribute in \fBrepos.conf\fR. \fISite-specific\fR
 766 overrides to \fBlayout.conf\fR settings may be specified in
 767 \fB/etc/portage/repos.conf\fR. Settings in \fBrepos.conf\fR take
 768 precedence over settings in \fBlayout.conf\fR, except tools such as
 769 \fBrepoman\fR(1) and \fBegencache\fR(1) will entirely ignore
 770 \fBrepos.conf\fR since their operations are inherently \fBnot\fR
 771 \fIsite\-specific\fR.
 772
 773 .I Example:
 774 .nf
 775 # eclasses provided by java-overlay take precedence over identically named
 776 # eclasses that are provided by gentoo
 777 masters = gentoo java-overlay
 778 # indicate that this repo can be used as a substitute for foo-overlay
 779 aliases = foo-overlay
 780 # do not sign manifests in this repo
 781 sign\-manifests = false
 782 # thin\-manifests only contain DIST entries
 783 thin\-manifests = true
 784 # indicate that this repo requires manifests for each package, and is
 785 # considered a failure if a manifest file is missing/incorrect
 786 use\-manifests = strict
 787 .fi
 788 .RE
 789 .TP
 790 .BR /usr/portage/profiles/
 791 Global Gentoo settings that are controlled by the developers.  To override
 792 these settings, you can use the files in \fB/etc/portage/\fR.
 793 .RS
 794 .TP
 795 .BR arch.list
 796 A list of all valid KEYWORDS.  This does not include modifiers.
 797
 798 .I Format:
 799 .nf
 800 \- one KEYWORD per line
 801 .fi
 802
 803 .I Example:
 804 .nf
 805 x86
 806 ppc
 807 sparc
 808 .fi
 809 .TP
 810 .BR categories
 811 A simple list of valid categories that may be used in /usr/portage,
 812 PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)).
 813
 814 .I Format:
 815 .nf
 816 \- one category per line
 817 .fi
 818
 819 .I Example:
 820 .nf
 821 app\-admin
 822 dev\-lang
 823 games\-strategy
 824 sys\-kernel
 825 .fi
 826 .TP
 827 .BR info_pkgs
 828 A list of all the packages which will be displayed when you run `emerge info`.
 829 .TP
 830 .BR info_vars
 831 A list of all the variables which will be displayed when you run `emerge info`.
 832 .TP
 833 .BR license_groups
 834 This contains groups of licenses that may be specifed in the
 835 \fBACCEPT_LICENSE\fR variable (see \fBmake.conf\fR(5)). Refer
 836 to GLEP 23 for further information:
 837 \fIhttp://www.gentoo.org/proj/en/glep/glep-0023.html\fR.
 838
 839 .I Format:
 840 .nf
 841 \- comments begin with # (no inline comments)
 842 \- one group name, followed by list of licenses and nested groups
 843 \- nested groups are prefixed with the '@' symbol
 844 .fi
 845
 846 .I Example:
 847 .nf
 848 # The FSF-APPROVED group includes the entire GPL-COMPATIBLE group and more.
 849 FSF-APPROVED @GPL-COMPATIBLE Apache-1.1 BSD-4 MPL-1.0 MPL-1.1
 850 # The GPL-COMPATIBLE group includes all licenses compatible with the GNU GPL.
 851 GPL-COMPATIBLE Apache-2.0 BSD BSD-2 GPL-2 GPL-3 LGPL-2.1 LGPL-3 X11 ZLIB
 852 .fi
 853 .TP
 854 .BR package.accept_keywords
 855 Per\-package ACCEPT_KEYWORDS for profiles. This has the same format and
 856 behavior as /etc/portage/package.accept_keywords, including the ability
 857 to list atoms without any keywords in order to accept unstable variants
 858 of all stable keywords listed in ACCEPT_KEYWORDS.
 859 .TP
 860 .BR package.keywords
 861 Per\-profile KEYWORDS. Useful for cases in which the effective KEYWORDS of a
 862 given package should vary depending on which profile the user has selected.
 863
 864 .I Format:
 865 .nf
 866 \- comment lines begin with # (no inline comments)
 867 \- one DEPEND atom per line followed by additional KEYWORDS
 868 .fi
 869
 870 .I Example:
 871 .nf
 872 # add stable keyword to libgd
 873 media\-libs/libgd x86
 874 # remove stable keyword from mplayer and add unstable keyword
 875 media\-video/mplayer \-x86 ~x86
 876 # remove all keywords from netcat
 877 net-analyzer/netcat -*
 878 .fi
 879 .TP
 880 .BR package.mask
 881 This contains a list of DEPEND atoms for packages that should not be installed
 882 in any profile.  Useful for adding the latest KDE betas and making sure no
 883 one accidentally upgrades to them.  Also useful for quickly masking specific
 884 versions due to security issues.  ALWAYS include a comment explaining WHY the
 885 package has been masked and WHO is doing the masking.
 886
 887 .I Format:
 888 .nf
 889 \- comments begin with # (no inline comments)
 890 \- one DEPEND atom per line
 891 .fi
 892
 893 .I Example:
 894 .nf
 895 # masked for security reasons
 896 <sys\-libs/zlib\-1.1.4
 897 # <caleb@gentoo.org> (10 Sep 2003)
 898 # new kde betas
 899 =kde\-base/kde\-3.2.0_beta1
 900 =kde\-base/kdeaccessibility\-3.2.0_beta1
 901 .fi
 902 .TP
 903 .BR profiles.desc
 904 List all the current stable and development profiles.  If a profile is listed
 905 here, then it will be checked by repoman.
 906 .I Format:
 907 .nf
 908 \- comments begin with # (no inline comments)
 909 \- one profile list per line in format: arch dir status
 910 \- arch must be listed in arch.list
 911 \- dir is relative to profiles.desc
 912 \- status must be 'stable', 'dev', or 'exp'
 913 .fi
 914
 915 .I Example:
 916 .nf
 917 alpha        default/linux/alpha/10.0    stable
 918 m68k         default/linux/m68k/10.0     dev
 919 x86          default/linux/x86/10.0      stable
 920 x86-linux    prefix/linux/x86            exp
 921 .fi
 922 .TP
 923 .BR repo_name
 924 The first line of the file should define a unique repository name. The name
 925 may contain any of the characters [A\-Za\-z0\-9_\-]. It must not begin with a
 926 hyphen.
 927 .TP
 928 .BR thirdpartymirrors
 929 Controls the mapping of mirror:// style URIs to actual lists of
 930 mirrors.  Keeps us from overloading a single server.
 931
 932 .I Format:
 933 .nf
 934 \- comments begin with # (no inline comments)
 935 \- mirror type followed by a list of hosts
 936 .fi
 937
 938 .I Example:
 939 .nf
 940 sourceforge http://aleron.dl.sourceforge.net/sourceforge http://unc.dl.sourceforge.net/sourceforge
 941
 942 gentoo http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles/ ftp://ftp.gtlib.cc.gatech.edu/pub/gentoo/distfiles
 943
 944 kernel http://www.kernel.org/pub http://www.us.kernel.org/pub
 945 .fi
 946 .TP
 947 .BR use.desc
 948 All global USE flags must be listed here with a description of what they do.
 949
 950 .I Format:
 951 .nf
 952 \- comments begin with # (no inline comments)
 953 \- use flag \- some description
 954 .fi
 955
 956 .I Example:
 957 .nf
 958 3dfx \- Adds support for 3dfx video cards
 959 acl \- Adds support for Access Control Lists
 960 doc \- Adds extra documentation
 961 .fi
 962 .TP
 963 .BR use.local.desc
 964 All local USE flags are listed here along with the package and a
 965 description. This file is automatically generated from the
 966 metadata.xml files that are included with each individual package.
 967 Refer to GLEP 56 for further information:
 968 \fIhttp://www.gentoo.org/proj/en/glep/glep-0056.html\fR.
 969
 970 .nf
 971 .I Format:
 972 \- comments begin with # (no inline comments)
 973 \- package:use flag \- description
 974
 975 .I Example:
 976 app\-editors/nano:justify \- Toggles the justify option
 977 dev\-libs/DirectFB:fusion \- Adds Multi Application support
 978 games\-emulation/xmess:net \- Adds network support
 979 .fi
 980 .RE
 981 .TP
 982 .BR /usr/share/portage/config/
 983 .RS
 984 .TP
 985 .BR make.globals
 986 The global default settings for Portage.  This comes from the portage package
 987 itself.  Settings in \fBmake.conf\fR or \fBpackage.env\fR
 988 override values here. The format
 989 is described extensivly in \fBmake.conf\fR(5).
 990 .RE
 991 .TP
 992 .BR /var/cache/edb/
 993 .RS
 994 This directory is used to store internal portage cache files.  The names and
 995 purpose of these files are not documented on purpose so as to keep down bitrot
 996 as internals change.  If you aren't working on portage internally, then the
 997 details most likely do not matter to you.
 998
 999 This entire directory can be safely deleted.  It is highly recommended you do
1000 not do this however as it can be a time consuming process to generate them all
1001 again.
1002 .RE
1003 .TP
1004 .BR /var/db/pkg/
1005 .RS
1006 All installed package information is recorded here.  If portage thinks you have
1007 a package installed, it is usually because it is listed here.
1008
1009 The format follows somewhat closely that of the portage tree.  There is a
1010 directory for each category and a package-version subdirectory for each package
1011 you have installed.
1012
1013 Inside each package directory are misc files that describe the installed
1014 contents of the package as well as build time information (so that the package
1015 can be unmerged without needing the portage tree).
1016
1017 The exact file contents and format are not described here again so that things
1018 can be changed quickly.  Generally though there is one file per environment
1019 variable that "matters" (like CFLAGS) with the contents stored inside of it.
1020 Another common file is the CONTENTS file which lists the path and hashes of
1021 all objects that the package installed onto your system.
1022 .RE
1023 .TP
1024 .BR /var/lib/portage/
1025 .RS
1026 .TP
1027 .BR config
1028 Hashes which are used to determine whether files in config protected
1029 directories have been modified since being installed.  Files which have not
1030 been modified will automatically be unmerged.
1031 .TP
1032 .BR world
1033 Every time you emerge a package, the package that you requested is
1034 recorded here.  Then when you run `emerge world \-up`, the list of
1035 packages is read from this file.  Note that this does not mean that the
1036 packages that were installed as dependencies are listed here.  For
1037 example, if you run `emerge mod_wsgi` and you do not have apache
1038 already, then "www\-apache/mod_wsgi" is recorded in the world file but
1039 "www\-servers/apache" is not.  For more information, review \fBemerge\fR(1).
1040
1041 .I Format:
1042 .nf
1043 \- one DEPEND atom base per line
1044 .fi
1045
1046 .I Example:
1047 .nf
1048 games\-misc/fortune\-mod\-gentoo\-dev
1049 dev\-libs/uclibc
1050 app\-cdr/cdemu
1051 .fi
1052 .TP
1053 .BR world_sets
1054 This is like the world file but instead of package atoms it contains
1055 packages sets which always begin with the @ character.
1056
1057 .I Example:
1058 .nf
1059 @kde
1060 .fi
1061 .RE
1062 .SH "REPORTING BUGS"
1063 Please report bugs via http://bugs.gentoo.org/
1064 .SH "AUTHORS"
1065 .nf
1066 Marius Mauch <genone@gentoo.org>
1067 Mike Frysinger <vapier@gentoo.org>
1068 Drake Wyrm <wyrm@haell.com>
1069 Arfrever Frehtes Taifersar Arahesis <arfrever@gentoo.org>
1070 .fi
1071 .SH "SEE ALSO"
1072 .BR emerge (1),
1073 .BR ebuild (1),
1074 .BR ebuild (5),
1075 .BR make.conf (5),
1076 .BR color.map (5)