User:Slowpoke/Overlay Tutorial

= Overview =

Since I haven't found a good, comprehensive tutorial on how to create your own overlay (with all the gritty details), I've set out to write my own while I go along. Consider this a work in progress.

= Preparations =

Directory Structure
First, we need to set up a directory structure somewhere. For simplicity, we will use $HOME/overlay, but you could also use /usr/local/overlay or anywhere else you feel like.

Metadata
An overlay requires a name and some metadata.

Version Control
We will use git to maintain our overlay. Feel free to use another VCS if you want to - though you should really use either git, svn or cvs, which are the three VCS supported by repoman - see below.

If you have never used git or another VCS before - fear not, they have an excellent tutorial on their site.

First, we create the git repository (make sure you are in the top level directory of your overlay, $HOME/overlay in our case).

Next, we add the files we created in the previous section to the repository.

Finally, we commit our changes.

= Create a package =

Needed directories
Every package in Portage lives in a category, such as sys-kernel or app-admin. In essence, these are sub-directories in your Portage tree. The same goes for your overlay. So, for example, if you want to write an ebuild for a fancy new terminal emulator called "fancy-term", you'd create the directory "x11-terms", and in it a directory for "fancy-term".

Your own categories
If your package is something that doesn't fit in the existing categories, you can of course create your own. Let's say you - as a truly old school programmer - want to create an overlay for tools related to COBOL programming. Keeping consistent with the categories for other languages, such as Python (dev-python) or Lisp (dev-lisp), you call it dev-cobol.

To prevent repoman (see below) from shouting at you when committing your ebuild, you should now also record it in profiles/categories.

Writing the ebuild
There are already a great many tutorials that teach you to create ebuilds, such as the Official Gentoo Development Guide. Consult one of them about how to write an ebuild.

More metadata
Don't forget to create a metadata.xml for your shiny new package. An explanation about this file is also found in the Development Guide. You don't need all the values in there, but you should at least list a Maintainer (i.e. yourself), a long description and, if available, an URL or email adress (prefixed with "mailto:") to report bugs upstream.

Committing the package
Finally, we commit the package to the repository. To do this, we will not use git (or svn/csv), but rather repoman, which is a tool that does some basic checking and generates manifests for you.

To check your package:

To commit it:

= See also =


 * Gentoo Developer Handbook