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 New packages. In the search field put the name of the ebuild and as status and resolution select all possible fields, then submit the query. For you lazy people, here is a Bugzilla advanced search link.

The Gentoo repository should only be used for storing .ebuild files, as well as any small companion files, such as patches or sample configuration files. These files should have a size of at most 20 KiB and must be placed in the mycat/mypkg/files directory, which can be referenced as ${FILESDIR} from within ebuilds.

Larger patches should be placed in your developer space on dev.gentoo.org instead of the tree, in order to minimize the repository size. Non-developers such as proxied maintainers can host patches at some stable location of their own — there is no security issue here as the Manifest will record patch checksums at the time of commit.

The files in the repository should be uncompressed plain text files, i.e., no binaries. This will allow the version control system 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 pkgdev commit with pkgdev push instead of git commit to submit their ebuilds. Before committing, please run pkgcheck scan --commits 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.patch, or more simply, 1.0-gentoo.patch. 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.