man/portage.5

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