man/portage.5

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