man/portage.5

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