Gentoo-HOWTO

Written by Peter Gavin <pete@gentoo.org> and other members of the
Gentoo Team

------------------------------------------------------------------------

This document is a work in progress, and is constantly being updated
and changed. It is by no means complete.

------------------------------------------------------------------------

Contents

I. Introduction
II. The Portage Tree
  A. What (Not) to Put in the Portage Tree
  B. Categories
  C. The files Directory
III. .ebuild Files
  A. Naming .ebuild Files
  B. Contents of an .ebuild File
  C. Rules for Writing an .ebuild File
IV. Filesystem Locations
  A. Introduction to the FHS
  B. How to Fit Your Packages into the Filesystem
V. The Portage Scripts and Utilities
  A. Public Scripts
    1. ebuild
    2. portage-merge
    3. portage-unmerge
    4. portage-maintain
    5. pkgmerge
    6. pkgname
  B. Private Scripts
    1. dobin
    2. dodeps
    3. dodir
    4. dodoc
    5. doexe
    6. dohard
    7. doinfo
    8. doins
    9. dolib
    10. dolib.a
    11. dolib.so
    12. doman
    13. domo
    14. donewins
    15. dopython
    16. dosbin
    17. dosed
    18. dosym
    19. find-packages
    20. find-requires
    21. fowners
    22. fperms
    23. import-configsettings
    24. import-settings
    25. megadigest
    26. megadownload
    27. megatouch
    28. newbin
    29. newdoc
    30. newexe
    31. newins
    32. newlib.a
    33. newlib.so
    34. newman
    36. newsbin
    37. pkgmerge
    38. pmake
    39. portage-maintain
    40. prepall
    41. prepalldocs
    42. prepallinfo
    43. prepallman
    44. prepallstrip
    45. prepinfo
    46. preplib
    47. preplib.so
    48. prepman
    49. prepstrip
    50. unpack
    51. use

------------------------------------------------------------------------

I. Introduction

	blah, blah, blah... (I'll fill this in later)

II. The Portage Tree

	The portage tree is a heirarchy, in which the first level is
	the category, and the second is the name of the package.

  A. What (Not) to Put in the Portage Tree

	The portage tree should only include ebuild files, and other
	files in the 'files' directory for each package. No binary
	files should be placed in the portage tree. No files that can
	be downloaded from other sources (such as patches written by
	other people) should be put here. No patches you write
	yourself should be compressed.

  B. Categories

	The categories are defined as follows:

	app-admin - non-critical system administration utilities

	app-arch - non-critical archival/compression utilities

	app-cdr - CD recording utilities

	app-doc - application documentation

	app-editors - non-critical text editors

	app-emulation - packages for emulating other systems/OSes

	app-misc - applications that don't fit anywhere else

	app-office - office-type (word processing, spreadsheet, etc.)
		packages

	app-shells - non-critical shells and command interpreters

	app-text - text processing, spell checkers, and document
		formatting packages

	dev-db - database libraries

	dev-java - java classes/packages/etc.

	dev-lang - compilers and interpreters for different languages

	dev-libs - miscellaneous developer's libraries

	dev-perl - perl modules

	dev-python - python modules

	dev-ruby - ruby modules

	dev-util - various developers utilities

	gnome-apps - applications for gnome

	gnome-base - base gnome packages

	gnome-libs - non-essential gnome libraries

	gnome-office - office packages for gnome

	kde-apps - applications for kde

	kde-base - base kde packages

	kde-i18n - kde internationalization packages

	media-gfx - graphics related programs

	media-libs - libraries for manipulating different media,
		including accessing multimedia peripherals of your
		computer (sound card, video card, etc.)

	media-sound - programs related to sound, including cd-audio
		and sound encoding

	media-video - programs related to video, including video
		codecs and players

	net-analyzer - network usage statistics monitors/analyzers

	net-dialup - network dialup clients and servers such as pppd

	net-fs - network filesystems

	net-ftp - ftp servers and clients

	net-irc - irc servers and clients

	net-libs - networking related libraries

	net-mail - mtas and muas

	net-misc - miscellaneous servers, clients, firewalls, etc.

	net-nds - NIS/NIS+ and other name services

	net-print - print servers and clients

	net-www - http/www servers and clients

	sys-apps - system-critical applications and utilities

	sys-devel - base development packages, such as gcc and make

	sys-kernel - linux kernels

	sys-libs - system-critical libraries such as glibc

	x11-base - xfree86 and xfree86 drivers for various video cards

	x11-libs - widget sets and other x11 specific libraries

	x11-terms - x11 terminal emulators

	x11-wm - x11 window managers

  C. The files Directory

	Under each package subdirectory is a 'files' directory. You
	should place any patches, configuration files, and other
	auxillary files your package might require in this
	directory. Patches you create yourself just to get your
	package to build should be called '${PF}-gentoo.diff'. You
	should not compress these diffs, since 1) they should not be big
	enough to require compressing, and 2) cvs does not play well
	with binary files.

	Please add a suffix or prefix such as ${PV}-r${PR} (or just
	${PV} if ${PR} is 0) to the tail of every file you put into
	the files directory, so that the files used for each
	individual version of your ebuild scripts are distinguishable
	from one another, and so that the changes between different
	revisions are visible.

	If you have many files that should go into the files
	directory, you should create a subdirectory files/${PV}-${PR}
	(or just files/${PV} if ${PR} is 0), and put all these files
	in there. If you use this method, you do not need to suffix
	the names of the files in this directory with the ebuild
	version.

III. .ebuild Files

	.ebuild files are the basis for the entire portage
	system. They contain all the information required to build a
	package, and every installed package requires one of these
	files. .ebuild files are essentially just bash scripts that
	contain a few functions and environment variable settings. The
	ebuild command takes care of the rest of the details, such as
	merging the package into the filesystem and recording the
	package into the package database.

  A. Naming .ebuild Files

	.ebuild file names are in four sections.
	
	The first section is the package name, which should only
	contain lowercase letters, the digits 0-9, and hyphen ('-')
	characters.
	
	The second section is the version of the package, which should
	normally be the same as the version on the main source
	tarball. The version is normally made up of 2 or 3 numbers
	separated by periods, such as 1.2 or 4.5.2, and may have a
	single letter immidiately following the last digit, e.g., 1.4b
	or 2.6h. This letter should *not* be used to signify alpha or
	beta status for the package. There are 3 special suffixes that
	may be used for these packages: _alpha, _beta, and _pre. Each
	of these suffixes may be immediately followed my a number,
	e.g., 'linux-2.4.0_pre10'.
	
	The third section of the package name is the revision number,
	which is specified by -r#, where '#' is a number,
	e.g. 'package-4.5.3-r3'. This revision number is independent of
	the version of the source tarball, but if you need to make
	non-trivial changes to your .ebuild file, you should copy the
	.ebuild file to a new file with the revision number
	incremented by 1. Initial releases normally have no revision
	number, e.g. 'package-4.5.3'.

	The fourth section of the .ebuild file name is always the
	.ebuild extension.

  B. Contents of an .ebuild File

    1. Variable Settings

	The first part of every ebuild file is made up of a number of
	variable settings. The variables you can set are 

  C. Rules for Writing an .ebuild File

IV. Filesystem Locations

  A. Introduction to the FHS

  B. How to Fit Your Packages into the Filesystem

V. The Portage Scripts and Utilities

  A. Public Scripts

    1. ebuild

    2. portage-merge

    3. portage-unmerge

    4. portage-maintain

    5. pkgmerge

    6. pkgname

  B. Private Scripts

    1. dobin

    2. dodeps

    3. dodir

    4. dodoc

    5. doexe

    6. dohard

    7. doinfo

    8. doins

    9. dolib

    10. dolib.a

    11. dolib.so

    12. doman

    13. domo

    14. donewins

    15. dopython

    16. dosbin

    17. dosed

    18. dosym

    19. find-packages

    20. find-requires

    21. fowners

    22. fperms

    23. import-configsettings

    24. import-settings

    25. megadigest

    26. megadownload

    27. megatouch

    28. newbin

    29. newdoc

    30. newexe

    31. newins

    32. newlib.a

    33. newlib.so

    34. newman

    36. newsbin

    37. pkgmerge

    38. pmake

    39. portage-maintain

    40. prepall

    41. prepalldocs

    42. prepallinfo

    43. prepallman

    44. prepallstrip

    45. prepinfo

    46. preplib

    47. preplib.so

    48. prepman

    49. prepstrip

    50. unpack

    51. use