Adding a New Ebuild
What (not) to put in the Gentoo repository
Before writing a new ebuild, check bugs.gentoo.org to see if an ebuild has already been written for the package, but has not yet been added to the Gentoo repository. Go to bugs.gentoo.org, choose query and select Advanced Search; as product select Gentoo Linux, as component select ebuilds. In the search field put the name of the ebuild and as status select all possible fields, then submit the query. For you lazy people, click here.
In general, the Gentoo repository should only be used for storing
.ebuild
files, as well as any relatively small companion
files, such as patches or sample configuration files. These types of
files should be placed in the mycat/mypkg/files
directory
to keep the main mycat/mypkg
directory uncluttered.
Exceptions to this rule are for larger patch files (we recommend this
for patches above 20KB) which should be distributed as tarballs via the
Gentoo
mirror system so that people do not waste excessive amounts of
bandwidth and hard drive space. Also, you should not add binary
(non-ASCII) files to the git tree. Also, speaking of merging changes,
any patches you add to Portage should generally not be
compressed. This will allow git to merge changes and correctly inform
developers of conflicts.
Remember, the packages that you commit must be ready out of the box for end users when committed as stable. Make sure that you have a good set of default settings that will satisfy the majority of systems and users that will use your package. If your package is broken, and you are not sure how to get it to work, check some other distributions that have done their own versions of the package. You can check Debian or Fedora for some examples.
When committing to git, all developers should use repoman commit
instead of git commit
to submit their ebuilds. Before committing,
please run repoman full
to make sure you didn't forget something.
Initial Architecture Keywords
When adding a new ebuild, you should only include KEYWORDS
for
architectures on which you have actually tested the ebuild, confirming
that it works as it should and that USE
flags are properly
honoured in the resulting package which would be installed. If
possible, you should give the actual library or application thorough
testing as well, since you would be responsible for any breakages for
your architecture(s). Minimal testing such as checking that the
application starts up without any errors should always be performed.
If you are adding a user-submitted ebuild, do not assume that the
submitter has done testing on various architectures: often, KEYWORDS
are cloned across packages or generated from documentation in the
source packages, which does not signify that the package does indeed
work on those architectures.
The files Directory
As noted earlier, under each package subdirectory is
a files/
directory. Any patches, configuration files, or
other ancillary files your package might require should be added to
this directory; any files bigger than 20KB-or-so should go to the
mirrors to lower the amount of (unneeded) files our users have to
download. You may want to consider naming patches you create yourself
just to get your package to build with a version-specific name, such
as mypkg-1.0-gentoo.diff
, or more
simply, 1.0-gentoo.diff
. Also note that the
gentoo
extension informs people that this patch was created
by us, the Gentoo Linux developers, rather than having been grabbed from a
mailing list or somewhere else. Again, you should not compress these
patches.
Consider prefixing or suffixing (such as mypkg-1.0
) every file
you put into the files/
directory, so that the files used for
each individual version on an ebuild are distinguishable from one another, and
so that the changes between different revisions are visible. This is generally
a really good idea :). You may want to use a different suffix if you wish to
convey more meaning with the patch name.
If you have many files that should go into the files/
directory,
consider creating subdirectories such as files/1.0/
and putting the
relevant files in the appropriate subdirectory. If you use this method,
you do not need to add version information to the names of the files,
which is often more convenient.