%% LyX 1.3 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[20pt,a4paper,english,landscape]{foils}
\usepackage{pslatex}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\pagestyle{foilheadings}
\usepackage{graphicx}

\makeatletter
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
 \usepackage{pifont}
 \usepackage{pifont}
 \newenvironment{lyxcode}
   {\begin{list}{}{
     \setlength{\rightmargin}{\leftmargin}
     \setlength{\listparindent}{0pt}% needed for AMS classes
     \raggedright
     \setlength{\itemsep}{0pt}
     \setlength{\parsep}{0pt}
     \normalfont\ttfamily}%
    \item[]}
   {\end{list}}
 \newenvironment{lyxlist}[1]
   {\begin{list}{}
     {\settowidth{\labelwidth}{#1}
      \setlength{\leftmargin}{\labelwidth}
      \addtolength{\leftmargin}{\labelsep}
      \renewcommand{\makelabel}[1]{##1\hfil}}}
   {\end{list}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
% 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}
}

\usepackage{babel}
\makeatother
\begin{document}

\rightfooter{\includegraphics[%
  scale=0.8]{glogo-small.png}}


\title{Gentoo Ebuilds 101}


\author{Arun Raghavan}


\date{Foss.in -- November 30, 2005}

\maketitle
\begin{abstract}
A basic introduction to Gentoo Linux' ebuild scripts, what they contain,
how they work, and most importantly -- how to write one.
\end{abstract}

\MyLogo{\includegraphics{glogo-small.png}}


\foilhead[-0.5in]{Overview}

\LogoOff

\begin{itemize}
\item What this talk provides

\begin{dinglist}{52}
\item An introduction to what ebuilds are
\item A quick guide to starting off on your own ebuilds, or modifying existing
ones
\end{dinglist}
\item What it isn't

\begin{dinglist}{56}
\item A detailed list of all the variables, function, eclasses%
\footnote{We'll just get to eclasses in a bit%
} you can use
\item Going to tell you how to do the more esoteric things that you can
\end{dinglist}
\item The idea is to get you on your way to hacking ebuilds, not to bog
you down with minutiae
\item The information is not always complete if I'm trying to keep things
simple
\end{itemize}

\foilhead[-0.5in]{What is this ebuild you speak of?}

\begin{itemize}
\item Basically just a \texttt{bash} script
\item Set of commands to fetch, unpack, compile, and install a package
\item \ldots{} and then some ;-)
\item File name looks like \texttt{<package-name>-<version>{[}-revision-number{]}.ebuild}
\item Organized by category under \texttt{/usr/portage/<category>/<package>},
like \texttt{media-video/mplayer} and \texttt{sys-kernel/gentoo-sources}
\item Subdirectory \texttt{files} for additional files, like patches
\item \texttt{metadata.xml} to list the maintainer and herd for this package
\item \texttt{Manifest} -- automatically created set of MD5 to verify all
associated files
\end{itemize}

\foilhead[-0.5in]{Peeping Under The Hood}

What the little pixie gnomes do when you run \texttt{emerge \ldots{}} 

\begin{enumerate}
\item Calculate the set of packages (specified and dependencies) to be installed
\item For each package:

\begin{enumerate}
\item Create \texttt{PORTAGE\_TMPDIR/portage/full-package-name}, subdirectories
\texttt{work,} \texttt{temp} and \texttt{image}
\item Fetch any files that require fetching
\item Check MD5 digests
\item Perform setup operations
\item Unpack the package
\item Compile the package
\item Perform test steps if defined
\item Install into image directory
\item Merge from the image directory to your system
\end{enumerate}
\end{enumerate}

\foilhead{Ebuild Contents: The Header}

\begin{itemize}
\item A header -- only needs to be touched for new ebuilds
\item Can be copied from \texttt{/usr/portage/header.txt}
\end{itemize}
\begin{lyxcode}
{\small \#~Copyright~1999-2005~Gentoo~Foundation}{\small \par}

{\small \#~Distributed~under~the~terms~of~the~GNU~General~Public~License~v2}{\small \par}

{\small \#~\$Header:~\$}{\small \par}
\end{lyxcode}

\foilhead[-0.5in]{Ebuild Contents: Predefined Variables}

\begin{lyxlist}{00.00.0000}
\item [P,~PN,~PV,~\ldots{}]Provide various combinations of the package
name, version, revision, etc.
\item [D]Path to install image of the package
\item [T]Directory where the ebuild can create temporary files
\item [WORKDIR]Path to the \texttt{work} directory where the package will
be built -- this is where you are when the ebuild script runs
\item [FILESDIR]Path to the \texttt{files} subdirectory
\item [DISTDIR]Path to the portage distfiles
\end{lyxlist}

\foilhead[-0.5in]{Ebuild Contents: Required Variables}

\begin{lyxlist}{00.00.0000}
\item [DESCRIPTION]A short description of the package
\item [SRC\_URI]URI from where the package files can be downloaded
\item [HOMEPAGE]Website of the package
\item [KEYWORDS]Specify the architectures the package has been tested on,
and the degree of stability
\item [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
\item [LICENSE]License under which the package is distributed -- must be
present in \texttt{/usr/portage/licenses}
\item [IUSE]Specifies the set of USE flags that allow the build to be customized\\
These should be in \texttt{/usr/portage/profiles/\{use.desc|use.local.desc\}}
\end{lyxlist}

\foilhead[-0.5in]{Ebuild Contents: Optional Variables}

\begin{lyxlist}{00.00.0000}
\item [S]Path to directory where the package is to be built (defaults to
\texttt{\$\{WORKDIR\}/\$\{P\}})
\item [DEPEND]Set of packages on which this package depends for building
-- for example \texttt{>=x11-libs/gtk+-2}
\item [RDEPEND]Set of packages on which this package has runtime dependencies
\item [PROVIDE]For any ``virtuals'' provided by this package
\end{lyxlist}

\foilhead[-0.5in]{Common Functions}

\begin{lyxlist}{00.00.0000}
\item [use]\texttt{use foo} returns true if the \texttt{foo} USE-flag is
set, false otherwise\texttt{}~\\
\texttt{use !foo} returns true if the \texttt{foo} USE-flag is not
set, false otherwise
\item [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)
\item [econf]Gentooized \texttt{./configure}\\
You can pass arguments to this just like \texttt{./configure}
\item [use\_with]\texttt{use\_with ogg} returns the string \texttt{-{}-with-ogg}
if the \texttt{ogg} USE-flag is set\\
\texttt{use\_with X x11} returns the string \texttt{-{}-with-x11}
is the \texttt{X} USE-flag is set
\item [use\_enable]Similar to \texttt{use\_with}
\item [emake]Runs \texttt{make} using the MAKEOPTS variable\\
You can pass arguments/targets as with \texttt{make}
\item [einstall]Gentooized \texttt{make install}
\item [doins,~dodoc,~dobin]A bunch of helper functions for installing
files, documentation, etc.
\item [epatch]Use this to patch the source code before compiling (works
with compressed patches too)%
\footnote{This is provided by \texttt{eutils.eclass}%
}
\item [einfo]Use this to display information messages
\item [ewarn]\ldots{}and this for warnings
\item [die]Use this when you want to kill the script (like \texttt{emake
|| die})
\end{lyxlist}

\foilhead[-0.5in]{The Workhorse (Standard) Functions}

\begin{itemize}
\item The ebuild script is basically a set of functions executed in a particular
order
\end{itemize}
\begin{lyxlist}{00.00.0000}
\item [pkg\_setup]Do anything you have to do before starting (like add
users/groups)
\item [src\_unpack]Unpack the package, apply patches (this is run in WORKDIR)
\item [src\_compile]Do that actual package compilation (this is run in
S)
\item [src\_test]Test the package
\item [src\_install]Installs all files to D (basically a \texttt{make DESTDIR=\$\{D\}
install})
\item [pkg\_preinst]Some pre-installation steps
\item [pkg\_postinst]Some post-installation steps
\end{lyxlist}
\begin{itemize}
\item There are functions that can be run while unmerging a package as well
-- discovery of these is left as an exercise for the reader ;-)
\end{itemize}

\foilhead[-0.5in]{The Sandbox}

\begin{itemize}
\item Ebuilds runs in a protected ``sandbox'' environment
\item You cannot write files above \$WORKDIR
\item This is done to make sure that bad ebuilds do not pose a threat to
your system
\item Does not apply to \texttt{pkg\_{*}} functions, so you can touch the
live system during setup, preinst, postinst
\item This might happen because of bad build systems with hardcoded paths.
If this is the case:

\begin{itemize}
\item Try to get these fixed upstream (i.e. by the creators of the package)
\item While it is being fixed, write patches to fix the offending bits
\end{itemize}
\item If there is a legitimate need to touch the live system, use \texttt{addread()},
\texttt{addpredict()}, and \texttt{addwrite()}

\begin{itemize}
\item If you need \texttt{addwrite()}, something is probably wrong
\end{itemize}
\end{itemize}

\foilhead[-0.5in]{Eclasses}

\begin{itemize}
\item Eclasses enable code reuse in Gentoo
\item Again, just a set of \texttt{bash} scripts in \texttt{/usr/portage/eclass}
\item Provide:

\begin{itemize}
\item Functions that perform common tasks, like modifying CFLAGS, adding
users/groups, and much more
\item Provide standard ebuild functions (\texttt{src\_unpack}, \texttt{src\_compile},
etc.) for non-\texttt{autotools} packages (such as Python distutils
and packages that need to be got from CVS/Subversion/Arch)
\end{itemize}
\item To use them, call the \texttt{inherit} function (just like sourcing
the script) immediately after the header \ldots{}
\end{itemize}
\begin{lyxcode}
inherit~eutils~flag-o-matic~distutils
\end{lyxcode}
\begin{itemize}
\item The standard ebuild functions for the ebuild are taken from the last
inherited eclass that provides them
\end{itemize}

\foilhead[-0.5in]{Some Useful Eclasses}

\begin{lyxlist}{00.00.0000}
\item [eutils]Lots of useful utilities, including \texttt{epatch}, \texttt{newuser},
\texttt{newgroup}
\item [cvs]Used to buld packages straight out of CVS
\item [distutils]Use this for Python packages packaged using distutils
\item [flag-o-matic]Use this to modify user-defined CFLAGS/CXXFLAGS
\item [games]For game ebuilds -- controls file locations, ownership
\item [rpm]For extracting packages distributed as RPMs
\item [libtool]Commonly used to fix bad libtool files
\item [toolchain-funcs]Utilities to get information about the toolchain
programs such as the compiler, linker, etc.
\item [versionator]Use this for all your version string manipulation
\end{lyxlist}

\foilhead[-0.5in]{Building the Manifest (we're almost there)}

\begin{itemize}
\item You need to build the \texttt{Manifest} file with the MD5 digests
of all files involved
\item This is done to make sure that none of the data used is corrupted
or malicious
\item All you need to do is \ldots{}
\end{itemize}
\begin{lyxcode}
ebuild~path/to/file.ebuild~digest
\end{lyxcode}
\begin{itemize}
\item This will process your ebuild, fetch required files, and then build
the Manifest file
\end{itemize}

\foilhead[-0.5in]{A Little Demo}

\begin{itemize}
\item Some real-life ebuilds

\begin{itemize}
\item \texttt{net-misc/logjam}
\item \texttt{net-misc/wget}
\item \texttt{net-analyzer/ethereal}
\item \texttt{sys-boot/grub}
\end{itemize}
\item Let's write a little ebuild

\begin{itemize}
\item \texttt{media-video/winki}
\item And digest it (sic)
\end{itemize}
\item Is it a bird? Is it a plane? No it's \texttt{repoman}!
\end{itemize}

\foilhead[-0.5in]{Testing}

\begin{itemize}
\item Need to make sure everything went okay
\item Run the actual program, make sure it works fine
\item Make sure USE flags cover everything, and do not conflict
\item Make sure depends are complete -- watch out for circular depends
\item Make sure documentation gets installed
\end{itemize}

\foilhead[-0.5in]{Version Bumping}

\begin{itemize}
\item What happens when a package releases the next version?
\item If there isn't any major change in functionality (like new items for
USE-flags, or new dependencies), it might be sufficient to just \texttt{cp
package-oldversion.ebuild package-newversion.ebuild} 
\item Assuming versions are not hardcoded, doing an \texttt{ebuild \ldots{}
digest} should be sufficient after this
\item For major changes, you need to figure out what the changes implt to
IUSE, DEPENDS, REDEPENDS and work accordingly
\end{itemize}

\foilhead[-0.5in]{Assorted Tips}

\begin{itemize}
\item Check bugs.gentoo.org for prior work
\item To understand the USE-flag and depends you're going to need, look
at the package README, configure.ac, etc.
\item Make sure that the package doesn't use it's own compiler/CFLAGS --
if it does, replace using \texttt{toolchain-funcs.eclass}
\item Don't \texttt{die} easily -- think about the user who started \texttt{emerge
world} overnight, and comes back to see that your script terminated
it half way
\item Run \texttt{repoman} for QA checks
\item Eclasses are neat

\begin{itemize}
\item If you need to do anything strange, see if it's been done already
and put in an eclass
\item Eclass man pages are in the \texttt{portage-manpages} package
\item You can always call an eclass' standard function like \texttt{distutils\_src\_compile}
\end{itemize}
\end{itemize}

\foilhead[-0.5in]{References}

\begin{itemize}
\item The \texttt{portage-manpages}
\item \texttt{man 5 ebuild}
\item These are well written files, that are not too difficult to understand

\begin{itemize}
\item \texttt{/usr/lib/portage/pym/portage.py}
\item \texttt{/usr/lib/portage/bin/ebuild.sh}
\item \texttt{/usr/portage/eclass/{*}} -- some of the man pages may be outdated
\end{itemize}
\item Grant Goodyear's not-at-all poor deconstruction of the scripts above
-- \href{http://dev.gentoo.org/~g2boojum/portage.html}{http://dev.gentoo.org/\textasciitilde g2boojum/portage.html}
\item The Unofficial Gentoo Development Guide -- \href{http://dev.gentoo.org/~plasmaroo/devmanual/}{http://dev.gentoo.org/\textasciitilde plasmaroo/devmanual/}
\item The Gentoo Developer Handbook -- \href{http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml}{http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml}
\item Some Gentoo sandbox documentation -- \href{http://bugday.gentoo.org/sandbox.html}{http://bugday.gentoo.org/sandbox.html}
\item \texttt{\#gentoo-dev-help} on \texttt{irc.freenode.net}
\end{itemize}

\foilhead[-0.5in]{Q\&A (a.k.a. \emph{burn} him!)}

Thanks for coming!
\end{document}