man/portage.5

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