Adding a new ebuild

Adding a new ebuild + + +What (not) to put in the Portage tree + + +

+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 Portage tree. 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 NEW, ASSIGNED, REOPENED and RESOLVED (RESOLVED is important), then +submit the query. For you lazy people, click here. +

+ +

+In general, the Portage tree 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 /usr/portage/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 put onto the Gentoo mirrors 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 +Portage CVS tree. If you need to do this in another CVS tree, for +example, if you need to add a small PNG graphic for whatever reason, +be sure to add it to CVS by using the -kb option, like so: +

+ +

+# cvs add -kb myphoto.png
+

+ +

+The -kb option tells CVS that myphoto.png is a binary +file and should be treated specially. For example, merging the +differences between two different versions of this file should not be +allowed to happen, for obvious reasons. Also, speaking of merging +changes, any patches you add to Portage should generally not be +compressed. This will allow CVS 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 +Mandriva +or Debian or +Fedora for some +examples. +

+ +

+When committing to CVS, all developers should use repoman commit +instead of cvs 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 @@ -33,6 +105,73 @@ work on those architectures.

+ + + +CVS Commit Policy + + +

Always run repoman scan before you commit.
Please run repoman full before you commit.
Always test that package.mask is okay by doing +emerge --pretend mypkg before you commit and check +that it doesn't contain any conflicts.
Always update the ChangeLog before you commit.
Always commit the updated package.mask before +the updated package, in case conflicts occur while you commit +package.mask.
Always do atomic commits; if you commit a package with a new license, +or that is masked, then first commit the revised package.mask and/or license, +then commit the ebuild, ChangeLog, patches +and metadata.xml all in one go +to avoid breaking users' installations.

+ + + + + +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 because CVS does not play well with binary files. +

+ +

+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. +

+ + + + +