This article is a work in progress; treat its contents with caution - slowpoke (talk | contribs).

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.

user $mkdir -p $HOME/overlay/{,profiles,metadata}

Metadata

An overlay requires a name and some metadata.

FILE $HOME/overlay/profiles/repo_name

name-of-your-overlay

FILE $HOME/overlay/metadata/layout.conf

masters = gentoo
sign-commits = false
sign-manifests = false

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

user ~/overlay $git init

Note
From here on, it will be assumed that you are in the top level directory of your overlay when asked to execute any git commands.

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

user $git add metadata/layout.conf profiles/repo_name

Finally, we commit our changes.

user $git commit -m "Create overlay with metadata."

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

user $mkdir -p x11-terms/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.

user $mkdir dev-cobol

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

user $echo dev-cobol >> profiles/metadata

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:

user $repoman scan

To commit it:

user $

git add x11-terms/{fancyterm-1.0.ebuild,metadata.xml}

user $repoman commit -m "Add fancy-term"

User:Slowpoke/Overlay Tutorial

Contents