man/portage.5

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