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