Gentoo Wiki




If you are a programmer and wrote a program, or simply wrote a useful script, you might search for a simple and clean way to install it on all your machines, or give it to a friend.

We all agree that the best way to get a program is to emerge it.

This howto will provide you with the basic knowledge about how ebuilds work, and how you create them. So you can create your own overlay, with your own programs.

The knowledge of this howto is based on the "Official Ebuild Howto".

And of course this howto is for non developers, and should be as easy as possible.

Create an Overlay

First we need a place to put our ebuilds, so we create an overlay.

mkdir -p /usr/portage/local/myebuilds
echo PORTDIR_OVERLAY="/usr/portage/local/myebuilds" >> /etc/make.conf


Now lets assume you wrote a very simple script to unmask packages example:

# version 0.1
echo "$1 ~x86" >> /etc/portage/package.keywords

and we wrote a short readme

first we need a category for our script, so we look if there is already a category for this type of software

ls /usr/portage

ok, app-portage looks good, so we create a app-portage dir in our overlay

mkdir /usr/portage/local/myebuilds/app-portage

now we need a name, "unmask" would be a good one, lets see if its free

emerge unmask -p

These are the packages that would be merged, in order:

Calculating dependencies
emerge: there are no ebuilds to satisfy "unmask".

Seems like it's not used, so we create a dir with the name unmask, and cd to it.

mkdir /usr/portage/local/myebuilds/app-portage/unmask
cd /usr/portage/local/myebuilds/app-portage/unmask


Now we need a place to put our script, this could be a webserver, but in our example we store the script directly in the tree. Since our script is not very big, thats no problem. Gentoo says files smaler then 20k can be stored in the tree. we create a files dir for that purpose

mkdir files

gzip the files

gzip /path/to/unmask
gzip /path/to/readme

and copy them

cp /path/to/unmask.gz files/
cp /path/to/readme.gz files/

The Ebuild

ok, now we use our favorite editor to create the ebuild. the name of our ebuild is the package name (unmask), - and the version (0.1)

nano unmask-0.1.ebuild

every ebuild starts with a set of variables, we have to set at least these variables:

SLOT="0"		# Always set this one to 0, its only for packages with multiple versions like gcc for example
LICENSE="GPL-1"		# Licences we hate them, but we need them
KEYWORDS="~alpha ~amd64 ~arm ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~ppc-macos ~s390 ~sh ~sparc x86 ~x86-fbsd"
			# since this is only a script, it shuld run on every platform, but we only tested
			# it on x86, so to be save we only add it as arch to x86, and the others to ~arch
DESCRIPTION="A simple script to unmask packages"
			# this should be a short description of your package
SRC_URI=""		# The address where we can get our script, since we stored it in the tree, we leave
			# it empty
HOMEPAGE=""		# I think this one is clear, if your script has a homepage, you can put the link here
IUSE="doc"		# this is for useflags, because its more fun, we add doc

now we have to write some functions, emerge will call them in this order during a merge

src_unpack()	# This function unpacks our files
	mkdir -p ${S}			# S is our source dir, where we copy our source files to
	cp ${FILESDIR}/unmask.gz ${S}	# The variable FILESDIR contains the path to our files dir
					# (/usr/portage/local/myebuilds/app-portage/unmask/files)
	gzip -d ${S}/unmask.gz

# src_compile() { }			# if you need to compile something, do it in this function 

	mkdir -p ${D}/usr/sbin		# D is like a virtual / where we install our stuff, before emerge 
					# merge it with the real /
	cp unmask ${D}/usr/sbin/	# now we simply copy "unmask" to our target dir
       chmod +x ${D}/usr/sbin/unmask   # and make our script executable

	if use doc; then		# if the useflag doc is enabled we copy our readme as well
		dodoc doc /usr/share/doc/${P}
		mkdir -p ${D}/usr/share/doc/${P}
		cp ${FILESDIR}/readme.gz ${D}/usr/share/doc/${P}/

Create A Manifest

Finaly we need to create a Manifest file, simply

ebuild unmask-0.1.ebuild digest

Try it

now you are ready to emerge your first own ebuild

emerge unmask

More help

A very good sample is the file /usr/portage/skel.ebuild

For a list of variables and functions, take a look at "The official Ebuild Howto"

See also and the #gentoo-dev-help channel on Freenode

You can reach me with Jabber my jid is

Retrieved from ""

Last modified: Fri, 12 Sep 2008 09:08:00 +0000 Hits: 11,795