#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass foils
\begin_preamble
% No logo
%\LogoOff

% Wrap-around
\raggedright

% This must be last in the preamble
\usepackage{hyperref}
\hypersetup{colorlinks,
        urlcolor=blue,
        urlbordercolor={0 0 0},
        linkbordercolor={0 0 0}
}
\end_preamble
\options landscape
\language english
\inputencoding auto
\fontscheme pslatex
\graphics default
\paperfontsize 20
\spacing single 
\papersize a4paper
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle foilheadings

\layout Right Footer


\begin_inset Graphics
	filename glogo-small.png
	lyxscale 80
	scale 80

\end_inset 


\layout Title

Gentoo Ebuilds 101
\layout Author

Arun Raghavan
\layout Date

Foss.in -- November 30, 2005
\layout Abstract

A basic introduction to Gentoo Linux' ebuild scripts, what they contain,
 how they work, and most importantly -- how to write one.
\layout My Logo


\begin_inset Graphics
	filename glogo-small.png

\end_inset 


\layout ShortFoilhead

Overview
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
LogoOff
\end_inset 


\layout Itemize

What this talk provides
\begin_deeper 
\layout TickList

An introduction to what ebuilds are
\layout TickList

A quick guide to starting off on your own ebuilds, or modifying existing
 ones
\end_deeper 
\layout Itemize

What it isn't
\begin_deeper 
\layout CrossList

A detailed list of all the variables, function, eclasses
\begin_inset Foot
collapsed true

\layout Standard

We'll just get to eclasses in a bit
\end_inset 

 you can use
\layout CrossList

Going to tell you how to do the more esoteric things that you can
\end_deeper 
\layout Itemize

The idea is to get you on your way to hacking ebuilds, not to bog you down
 with minutiae
\layout Itemize

The information is not always complete if I'm trying to keep things simple
\layout ShortFoilhead

What is this ebuild you speak of?
\layout Itemize

Basically just a 
\family typewriter 
bash
\family default 
 script
\layout Itemize

Set of commands to fetch, unpack, compile, and install a package
\layout Itemize

\SpecialChar \ldots{}
 and then some ;-)
\layout Itemize

File name looks like 
\family typewriter 
<package-name>-<version>[-revision-number].ebuild
\layout Itemize

Organized by category under 
\family typewriter 
/usr/portage/<category>/<package>
\family default 
, like 
\family typewriter 
media-video/mplayer
\family default 
 and 
\family typewriter 
sys-kernel/gentoo-sources
\layout Itemize

Subdirectory 
\family typewriter 
files
\family default 
 for additional files, like patches
\layout Itemize


\family typewriter 
metadata.xml
\family default 
 to list the maintainer and herd for this package
\layout Itemize


\family typewriter 
Manifest
\family default 
 -- automatically created set of MD5 to verify all associated files
\layout ShortFoilhead

Peeping Under The Hood
\layout Standard

What the little pixie gnomes do when you run 
\family typewriter 
emerge \SpecialChar \ldots{}

\family default 
 
\layout Enumerate

Calculate the set of packages (specified and dependencies) to be installed
\layout Enumerate

For each package:
\begin_deeper 
\layout Enumerate

Create 
\family typewriter 
PORTAGE_TMPDIR/portage/full-package-name
\family default 
, subdirectories 
\family typewriter 
work,
\family default 
 
\family typewriter 
temp 
\family default 
and 
\family typewriter 
image
\layout Enumerate

Fetch any files that require fetching
\layout Enumerate

Check MD5 digests
\layout Enumerate

Perform setup operations
\layout Enumerate

Unpack the package
\layout Enumerate

Compile the package
\layout Enumerate

Perform test steps if defined
\layout Enumerate

Install into image directory
\layout Enumerate

Merge from the image directory to your system
\end_deeper 
\layout Foilhead

Ebuild Contents: The Header
\layout Itemize

A header -- only needs to be touched for new ebuilds
\layout Itemize

Can be copied from 
\family typewriter 
/usr/portage/header.txt
\layout LyX-Code


\size small 
# Copyright 1999-2005 Gentoo Foundation
\layout LyX-Code


\size small 
# Distributed under the terms of the GNU General Public License v2
\layout LyX-Code


\size small 
# $Header: $
\layout ShortFoilhead

Ebuild Contents: Predefined Variables
\layout List
\labelwidthstring 00.00.0000

P,\SpecialChar ~
PN,\SpecialChar ~
PV,\SpecialChar ~
\SpecialChar \ldots{}
 Provide various combinations of the package name, version, revision,
 etc.
\layout List
\labelwidthstring 00.00.0000

D Path to install image of the package
\layout List
\labelwidthstring 00.00.0000

T Directory where the ebuild can create temporary files
\layout List
\labelwidthstring 00.00.0000

WORKDIR Path to the 
\family typewriter 
work
\family default 
 directory where the package will be built -- this is where you are when
 the ebuild script runs
\layout List
\labelwidthstring 00.00.0000

FILESDIR Path to the 
\family typewriter 
files
\family default 
 subdirectory
\layout List
\labelwidthstring 00.00.0000

DISTDIR Path to the portage distfiles
\layout ShortFoilhead

Ebuild Contents: Required Variables
\layout List
\labelwidthstring 00.00.0000

DESCRIPTION A short description of the package
\layout List
\labelwidthstring 00.00.0000

SRC_URI URI from where the package files can be downloaded
\layout List
\labelwidthstring 00.00.0000

HOMEPAGE Website of the package
\layout List
\labelwidthstring 00.00.0000

KEYWORDS Specify the architectures the package has been tested on, and the
 degree of stability
\layout List
\labelwidthstring 00.00.0000

SLOT Defines a ``slot''.
 This allows multiple versions of a package to coexist (think GTK+ v1 and
 v2).
 Set to 0 if there are no slots
\layout List
\labelwidthstring 00.00.0000

LICENSE License under which the package is distributed -- must be present
 in 
\family typewriter 
/usr/portage/licenses
\layout List
\labelwidthstring 00.00.0000

IUSE Specifies the set of USE flags that allow the build to be customized
\newline 
These should be in 
\family typewriter 
/usr/portage/profiles/{use.desc|use.local.desc}
\layout ShortFoilhead

Ebuild Contents: Optional Variables
\layout List
\labelwidthstring 00.00.0000

S Path to directory where the package is to be built (defaults to 
\family typewriter 
${WORKDIR}/${P}
\family default 
)
\layout List
\labelwidthstring 00.00.0000

DEPEND Set of packages on which this package depends for building -- for
 example 
\family typewriter 
>=x11-libs/gtk+-2
\layout List
\labelwidthstring 00.00.0000

RDEPEND Set of packages on which this package has runtime dependencies
\layout List
\labelwidthstring 00.00.0000

PROVIDE For any ``virtuals'' provided by this package
\layout ShortFoilhead

Common Functions
\layout List
\labelwidthstring 00.00.0000

use 
\family typewriter 
use foo
\family default 
 returns true if the 
\family typewriter 
foo
\family default 
 USE-flag is set, false otherwise
\family typewriter 

\newline 
use !foo
\family default 
 returns true if the 
\family typewriter 
foo
\family default 
 USE-flag is not set, false otherwise
\layout List
\labelwidthstring 00.00.0000

unpack Useful function to unpack your gz/bz2/rar/zip/jar packages (just
 pass it the filename to unpack -- picks it up from DISTDIR by default)
\layout List
\labelwidthstring 00.00.0000

econf Gentooized 
\family typewriter 
./configure
\family default 

\newline 
You can pass arguments to this just like 
\family typewriter 
./configure
\layout List
\labelwidthstring 00.00.0000

use_with 
\family typewriter 
use_with ogg
\family default 
 returns the string 
\family typewriter 
--with-ogg
\family default 
 if the 
\family typewriter 
ogg
\family default 
 USE-flag is set
\newline 

\family typewriter 
use_with X x11
\family default 
 returns the string 
\family typewriter 
--with-x11
\family default 
 is the 
\family typewriter 
X
\family default 
 USE-flag is set
\layout List
\labelwidthstring 00.00.0000

use_enable Similar to 
\family typewriter 
use_with
\layout List
\labelwidthstring 00.00.0000

emake Runs 
\family typewriter 
make
\family default 
 using the MAKEOPTS variable
\newline 
You can pass arguments/targets as with 
\family typewriter 
make
\layout List
\labelwidthstring 00.00.0000

einstall Gentooized 
\family typewriter 
make install
\layout List
\labelwidthstring 00.00.0000

doins,\SpecialChar ~
dodoc,\SpecialChar ~
dobin A bunch of helper functions for installing files, documentatio
n, etc.
\layout List
\labelwidthstring 00.00.0000

epatch Use this to patch the source code before compiling (works with compressed
 patches too)
\begin_inset Foot
collapsed true

\layout Standard

This is provided by 
\family typewriter 
eutils.eclass
\end_inset 


\layout List
\labelwidthstring 00.00.0000

einfo Use this to display information messages
\layout List
\labelwidthstring 00.00.0000

ewarn \SpecialChar \ldots{}
and this for warnings
\layout List
\labelwidthstring 00.00.0000

die Use this when you want to kill the script (like 
\family typewriter 
emake || die
\family default 
)
\layout ShortFoilhead

The Workhorse (Standard) Functions
\layout Itemize

The ebuild script is basically a set of functions executed in a particular
 order
\layout List
\labelwidthstring 00.00.0000

pkg_setup Do anything you have to do before starting (like add users/groups)
\layout List
\labelwidthstring 00.00.0000

src_unpack Unpack the package, apply patches (this is run in WORKDIR)
\layout List
\labelwidthstring 00.00.0000

src_compile Do that actual package compilation (this is run in S)
\layout List
\labelwidthstring 00.00.0000

src_test Test the package
\layout List
\labelwidthstring 00.00.0000

src_install Installs all files to D (basically a 
\family typewriter 
make DESTDIR=${D} install
\family default 
)
\layout List
\labelwidthstring 00.00.0000

pkg_preinst Some pre-installation steps
\layout List
\labelwidthstring 00.00.0000

pkg_postinst Some post-installation steps
\layout Itemize

There are functions that can be run while unmerging a package as well --
 discovery of these is left as an exercise for the reader ;-)
\layout ShortFoilhead

The Sandbox
\layout Itemize

Ebuilds runs in a protected ``sandbox'' environment
\layout Itemize

You cannot write files above $WORKDIR
\layout Itemize

This is done to make sure that bad ebuilds do not pose a threat to your
 system
\layout Itemize

Does not apply to 
\family typewriter 
pkg_*
\family default 
 functions, so you can touch the live system during setup, preinst, postinst
\layout Itemize

This might happen because of bad build systems with hardcoded paths.
 If this is the case:
\begin_deeper 
\layout Itemize

Try to get these fixed upstream (i.e.
 by the creators of the package)
\layout Itemize

While it is being fixed, write patches to fix the offending bits
\end_deeper 
\layout Itemize

If there is a legitimate need to touch the live system, use
\family typewriter 
 addread()
\family default 
, 
\family typewriter 
addpredict()
\family default 
, and 
\family typewriter 
addwrite()
\begin_deeper 
\layout Itemize

If you need 
\family typewriter 
addwrite()
\family default 
, something is probably wrong
\end_deeper 
\layout ShortFoilhead

Eclasses
\layout Itemize

Eclasses enable code reuse in Gentoo
\layout Itemize

Again, just a set of 
\family typewriter 
bash
\family default 
 scripts in 
\family typewriter 
/usr/portage/eclass
\layout Itemize

Provide:
\begin_deeper 
\layout Itemize

Functions that perform common tasks, like modifying CFLAGS, adding users/groups,
 and much more
\layout Itemize

Provide standard ebuild functions (
\family typewriter 
src_unpack
\family default 
, 
\family typewriter 
src_compile
\family default 
, etc.) for non-
\family typewriter 
autotools
\family default 
 packages (such as Python distutils and packages that need to be got from
 CVS/Subversion/Arch)
\end_deeper 
\layout Itemize

To use them, call the 
\family typewriter 
inherit
\family default 
 function (just like sourcing the script) immediately after the header \SpecialChar \ldots{}

\layout LyX-Code

inherit eutils flag-o-matic distutils
\layout Itemize

The standard ebuild functions for the ebuild are taken from the last inherited
 eclass that provides them
\layout ShortFoilhead

Some Useful Eclasses
\layout List
\labelwidthstring 00.00.0000

eutils Lots of useful utilities, including 
\family typewriter 
epatch
\family default 
, 
\family typewriter 
newuser
\family default 
, 
\family typewriter 
newgroup
\layout List
\labelwidthstring 00.00.0000

cvs Used to buld packages straight out of CVS
\layout List
\labelwidthstring 00.00.0000

distutils Use this for Python packages packaged using distutils
\layout List
\labelwidthstring 00.00.0000

flag-o-matic Use this to modify user-defined CFLAGS/CXXFLAGS
\layout List
\labelwidthstring 00.00.0000

games For game ebuilds -- controls file locations, ownership
\layout List
\labelwidthstring 00.00.0000

rpm For extracting packages distributed as RPMs
\layout List
\labelwidthstring 00.00.0000

libtool Commonly used to fix bad libtool files
\layout List
\labelwidthstring 00.00.0000

toolchain-funcs Utilities to get information about the toolchain programs
 such as the compiler, linker, etc.
\layout List
\labelwidthstring 00.00.0000

versionator Use this for all your version string manipulation
\layout ShortFoilhead

Building the Manifest (we're almost there)
\layout Itemize

You need to build the 
\family typewriter 
Manifest
\family default 
 file with the MD5 digests of all files involved
\layout Itemize

This is done to make sure that none of the data used is corrupted or malicious
\layout Itemize

All you need to do is \SpecialChar \ldots{}

\layout LyX-Code

ebuild path/to/file.ebuild digest
\layout Itemize

This will process your ebuild, fetch required files, and then build the
 Manifest file
\layout ShortFoilhead

A Little Demo
\layout Itemize

Some real-life ebuilds
\begin_deeper 
\layout Itemize


\family typewriter 
net-misc/logjam
\layout Itemize


\family typewriter 
net-misc/wget
\layout Itemize


\family typewriter 
net-analyzer/ethereal
\layout Itemize


\family typewriter 
sys-boot/grub
\end_deeper 
\layout Itemize

Let's write a little ebuild
\begin_deeper 
\layout Itemize


\family typewriter 
media-video/winki
\layout Itemize

And digest it (sic)
\end_deeper 
\layout Itemize

Is it a bird? Is it a plane? No it's 
\family typewriter 
repoman
\family default 
!
\layout ShortFoilhead

Testing
\layout Itemize

Need to make sure everything went okay
\layout Itemize

Run the actual program, make sure it works fine
\layout Itemize

Make sure USE flags cover everything, and do not conflict
\layout Itemize

Make sure depends are complete -- watch out for circular depends
\layout Itemize

Make sure documentation gets installed
\layout ShortFoilhead

Version Bumping
\layout Itemize

What happens when a package releases the next version?
\layout Itemize

If there isn't any major change in functionality (like new items for USE-flags,
 or new dependencies), it might be sufficient to just 
\family typewriter 
cp package-oldversion.ebuild package-newversion.ebuild
\family default 
 
\layout Itemize

Assuming versions are not hardcoded, doing an 
\family typewriter 
ebuild \SpecialChar \ldots{}
 digest
\family default 
 should be sufficient after this
\layout Itemize

For major changes, you need to figure out what the changes implt to IUSE,
 DEPENDS, REDEPENDS and work accordingly
\layout ShortFoilhead

Assorted Tips
\layout Itemize

Check bugs.gentoo.org for prior work
\layout Itemize

To understand the USE-flag and depends you're going to need, look at the
 package README, configure.ac, etc.
\layout Itemize

Make sure that the package doesn't use it's own compiler/CFLAGS -- if it
 does, replace using 
\family typewriter 
toolchain-funcs.eclass
\layout Itemize

Don't 
\family typewriter 
die
\family default 
 easily -- think about the user who started 
\family typewriter 
emerge world
\family default 
 overnight, and comes back to see that your script terminated it half way
\layout Itemize

Run 
\family typewriter 
repoman
\family default 
 for QA checks
\layout Itemize

Eclasses are neat
\begin_deeper 
\layout Itemize

If you need to do anything strange, see if it's been done already and put
 in an eclass
\layout Itemize

Eclass man pages are in the 
\family typewriter 
portage-manpages
\family default 
 package
\layout Itemize

You can always call an eclass' standard function like 
\family typewriter 
distutils_src_compile
\end_deeper 
\layout ShortFoilhead

References
\layout Itemize

The 
\family typewriter 
portage-manpages
\layout Itemize


\family typewriter 
man 5 ebuild
\layout Itemize

These are well written files, that are not too difficult to understand
\begin_deeper 
\layout Itemize


\family typewriter 
/usr/lib/portage/pym/portage.py
\layout Itemize


\family typewriter 
/usr/lib/portage/bin/ebuild.sh
\layout Itemize


\family typewriter 
/usr/portage/eclass/*
\family default 
 -- some of the man pages may be outdated
\end_deeper 
\layout Itemize

Grant Goodyear's not-at-all poor deconstruction of the scripts above --
 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
href{http://dev.gentoo.org/~g2boojum/portage.html}{http://dev.gentoo.org/
\backslash 
textasciitilde g2boojum/portage.html}
\end_inset 


\layout Itemize

The Unofficial Gentoo Development Guide -- 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
href{http://dev.gentoo.org/~plasmaroo/devmanual/}{http://dev.gentoo.org/
\backslash 
textasciitilde plasmaroo/devmanual/}
\end_inset 


\layout Itemize

The Gentoo Developer Handbook -- 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
href{http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml}{http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml}
\end_inset 


\layout Itemize

Some Gentoo sandbox documentation -- 
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
href{http://bugday.gentoo.org/sandbox.html}{http://bugday.gentoo.org/sandbox.html}
\end_inset 


\layout Itemize


\family typewriter 
#gentoo-dev-help
\family default 
 on 
\family typewriter 
irc.freenode.net
\layout ShortFoilhead

Q&A (a.k.a.
 
\emph on 
burn
\emph default 
 him!)
\layout Standard

Thanks for coming!
\the_end