From 07a0d42ed1d963709739ffd509bf2b365355cf32 Mon Sep 17 00:00:00 2001 From: Christian Faulhammer Date: Mon, 13 Apr 2009 12:11:54 +0200 Subject: [PATCH] Desk reference for quick look-up This contains a short summary of all EAPI features so far, similar to appendix E of PMS, but with more information. --- Makefile | 8 +- cheatsheet/eapi_cheatsheet.tex | 207 ++++++++++++++++++++++++++++++++++++++++ credits.tex | 5 +- pms.cls | 1 + pms.tex | 2 + 5 files changed, 219 insertions(+), 4 deletions(-) create mode 100644 cheatsheet/eapi_cheatsheet.tex diff --git a/Makefile b/Makefile index e9c3dd4..b585411 100644 --- a/Makefile +++ b/Makefile @@ -5,13 +5,14 @@ clean : rm -f *~ *.pdf *.dvi *.log *.aux *.bbl *.blg *.toc *.lol *.loa *.lox \ *.lot *.out *.html *.css *.png *.4ct *.4tc *.idv *.lg *.tmp *.xref vc.tex || true -LATEXFILES = $(shell ls *.tex) pms.cls +LATEXFILES = $(shell find -name '*.tex') pms.cls LISTINGFILES = $(shell ls *.listing) SOURCEFILES = $(LATEXFILES) $(LISTINGFILES) -pms.pdf: $(SOURCEFILES) pms.bbl vc.tex +pms.pdf: $(SOURCEFILES) pms.bbl vc.tex eapi_cheatsheet.pdf pdflatex pms pdflatex pms + pdflatex cheatsheet/eapi_cheatsheet pdflatex pms pms.html: $(SOURCEFILES) pms.bbl @@ -31,6 +32,9 @@ pms.bbl: pms.bib pms.tex vc.tex latex pms bibtex pms +eapi_cheatsheet.pdf: vc.tex + pdflatex cheatsheet/eapi_cheatsheet + vc.tex: pms.tex /bin/sh ./vc diff --git a/cheatsheet/eapi_cheatsheet.tex b/cheatsheet/eapi_cheatsheet.tex new file mode 100644 index 0000000..169318e --- /dev/null +++ b/cheatsheet/eapi_cheatsheet.tex @@ -0,0 +1,207 @@ +\documentclass[a4paper,notumble]{leaflet} +\input{vc} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{ + url, + hyperref, + listings, + ifthen, + xr-hyper, + mathptmx, + courier +} +\usepackage[orig,english]{isodate} +\usepackage[scaled=.90]{helvet} +\newcommand{\code}[1]{\texttt{#1}} +\newcommand{\version}{0.2} +\newcommand{\featureref}[1]{\textsc{#1} on page~\pageref{feat:#1}} +\renewcommand{\familydefault}{\sfdefault} +\urlstyle{sf} +\externaldocument{pms} + +\title{EAPI Cheat Sheet} +\author{Christian + Faulhammer\thanks{\href{mailto:fauli@g.o}{fauli@g.o}}} +\ifthenelse{\equal{\VCDateISO}{}} +{ + \date{Version \version{}, generated on: \\\today} +}{ + \date{Version \version\\\printdate{\VCDateISO}} +} +\CutLine*{1} +\CutLine*{3} +\CutLine*{4} +\CutLine*{6} +\hypersetup{% + urlcolor=black, + colorlinks=true, + citecolor=black, + linkcolor=black, + pdftitle={EAPI Desk Reference}, + pdfauthor={Christian Faulhammer}, + pdfsubject={Making look-up faster for EAPI features}, + pdflang={en}, + pdfkeywords={Gentoo, package manager, reference}, + pdfproducer={pdfLaTeX and hyperref}, +} +\begin{document} +\maketitle +\thispagestyle{empty} +\begin{abstract} + An overview of the main EAPI changes in Gentoo, for ebuild authors. + For full details, consult the Package Manager + Specification\footnote{\url{http://www.gentoo.org/proj/en/qa/pms/}}; + this is an incomplete summary only. + + Official Gentoo EAPIs are consecutively numbered integers (0, 1, 2, + \dots). Except where otherwise noted, an EAPI is the same as the + previous EAPI. All label refer to the PMS document itself, built + from the same checkout as this overview. + + Please report mistakes or enhancements to this document via the + Gentoo bug tracking system\footnote{\url{http://bugs.gentoo.org/}} + to the original author or the PMS team. + + This document is released under the Creative Commons + Attribution-Share Alike 3.0 + Licence\footnote{\url{http://creativecommons.org/licenses/by-sa/3.0/}}. +\end{abstract} +\section{EAPI 0} +\label{sec:cs:eapi0} +If there is no EAPI explicitely specified, EAPI 0 is assumed. +Currently there is no full specification what EAPI 0 includes. +Portage, official ebuild documentation and existing ebuilds set the +standard here, although obvious errors are still errors. +\newpage +\section{EAPI 1} +\label{sec:cs:eapi1} +\subsection{Additions/Changes} +\label{sec:cs:eapi1-additions} +\begin{description} +\item[IUSE defaults] An USE flag can be marked as mandatory (if not + disabled explicitely by user configuration) with a \code{+} sign in + front. See \featureref{iuse-defaults}. +\item[Named slot dependencies] Dependencies can explicitely request a + specific slot by using the \code{dev-libs/foo:SLOT} syntax. + See \featureref{slot-deps}. +\end{description} +\section{EAPI 2 (2008-09-25)} +\label{sec:cs:eapi2} +\subsection{Additions/Changes} +\label{sec:cs:eapi2-additions} +\begin{description} +\item[\code{SRC\_URI} arrows] Allows redirection of upstream file + naming scheme by using an "arrow" (\code{->}) to a new file name in + DISTDIR. See \featureref{src-uri-arrows}. +\item[USE dependencies] Dependencies can be specified to be built with + or without a specific USE flag, thus getting rid of countless + \code{built\_with\_use} checks. A more sophisticated syntax is + available in EAPI 3. + \begin{description} + \item[{[opt]}] The flag must be enabled. + \item[{[opt=]}] The flag must be enabled if the flag is enabled for the + package with the dependency, or disabled otherwise. + \item[{[!opt=]}] The flag must be disabled if the flag is enabled for + the package with the dependency, or enabled otherwise. + \item[{[opt?]}] The flag must be enabled if the flag is enabled for the + package with the dependency. + \item[{[!opt?]}] The flag must be disabled if the use flag is disabled + for the package with the dependency. + \item[{[-opt]}] The flag must be disabled. + \end{description} + See \featureref{use-deps}. +\item[Blocker syntax] A single exclamation mark as a blocker may be + ignored by the package manager as long as the stated package is + uninstalled later on. Two exclamation marks are a strong blocker + and will always be respected. See \featureref{bang-strength}. +\item[\code{src\_configure, src\_prepare}] Both new phases provide + finer granularity in the ebuild's structure. Configure calls should + be moved from \code{src\_compile} to \code{src\_configure}. + Patching and other preparing tasks must no longer take place in + \code{src\_unpack} but in \code{src\_prepare}. + See \featureref{src-prepare} and \featureref{src-configure}. +\item[Default phase functions] The default functions for the phases + \code{pkg\_nofetch}, \code{src\_unpack}, \code{src\_prepare}, + \code{src\_configure}, \code{src\_compile} and \code{src\_test} can + be called via \code{default\_\emph{phasename}}, so small additions + you need will not be accompanied by a complete reimplementation of + the phase. Additionally as a shorthand for the current phase's + default definition \code{default} can be invoked. + See \featureref{default-phase-funcs} and \featureref{default-func}. +\item[\code{doman} language support] The \code{doman} installation + function recognizes lanugage specific man page extensions and + behaves accordingly. See \featureref{doman-langs} +\end{description} +\newpage +\section{EAPI 3 (not yet approved)} +\label{sec:cs:eapi3} +\subsection{Additions/Changes} +\begin{description} +\item[\code{pkg\_pretend}] Some useful checks (kernel options for + example) can be placed in this new phase to inform the user early. + Duplicating checks from the \code{pkg\_setup} phase may be + necessary. See \featureref{pkg-pretend}. +\item[\code{src\_install}] The \code{src\_install} phase is no longer + empty but has a default now. This comes along with an accompanying + \code{default} function. See \featureref{src-install-3}. +\item[\code{pkg\_info} on non-installed packages] The \code{pkg\_info} + phase can be called even for non-installed packages. Do not depend + on any outside programs in that case! See \featureref{pkg-info}. +\item[No RDEPEND fall-back] The package manager will not fall back to + \code{RDEPEND=DEPEND} if RDEPEND is undefined. + See \featureref{rdepend-depend} +\item[Support for \code{.xz}] Unpack of \code{.xz} and \code{.tar.xz} + files is possible. See \featureref{unpack-extensions}. +\item[Slot operators] There are two ways to define a wanted slot in a + dependency string: + \begin{description} + \item[\code{:*}] Indicates that any slot value is acceptable. In addition, + for runtime dependencies, indicates that the package will not + break if the matched package is uninstalled and replaced by a + different matching package in a different slot. + \item[\code{:=}] Indicates that any slot value is acceptable. In addition, + for runtime dependencies, indicates that the package will break + unless a matching package with slot equal to the slot of the best + installed version at the time the package was installed is + available. + \end{description} + See \featureref{slot-operator-deps}. +\item[USE dependency defaults] Additionally to the features offered in + EAPI 2 for USE dependencies, a \code{(+)} or \code{(-)} can be added + after a USE flag (mind the braces). The former leads to the + assumption that the USE flag is available when not found in the + dependency, the latter leads to the reverse behaviour. This mimicks + parts of the behaviour of \code{-{}-missing} in + \code{built\_with\_use}. See \featureref{use-dep-defaults}. +\item[Controllable compression] All items in + \code{/usr/share\{doc,info,man\}} are compressed on-disk after + \code{src\_install}, except for \code{/usr/share/doc/\$\{PF\}/html}. + With \code{docompress} all arguments are passed to the inclusion + list, while the behaviour can be inverted with the \code{-x} + switch. See \featureref{controllable-compress}. +\item[\code{dodoc} recursion] If the \code{-r} switch is given as + first argument and followed by directories, files from there are + installed recursively. See \featureref{dodoc}. +\item[\code{doins} symlink support] Symbolic links are now properly + installed when using recursion (\code{-r} switch). + See \featureref{doins}. +\item[New installation functions] \code{doexample}, \code{newexample}, + \code{doinclude} and \code{newinclude} install example and include + files respectively in the known manner. See \featureref{doexample} and + \featureref{doinclude}. +\item[\code{nonfatal} for commands] If you call \code{nonfatal} the + command given as argument will not abort the build process in case + of a failure but preserve the exit status nonetheless. See + \featureref{nonfatal}. +\end{description} +\label{sec:cs:eapi3-additions} +\subsection{Removals/Bans} +\label{sec:cs:eapi3-removalsbans} +\begin{description} +\item[USE flags in any-of] Inside of \code{||} constructs USE flag + conditionals are forbidden (with exceptions). See \featureref{any-use} +\item[\code{dohard}, \code{dosed}] Both functions are not allowed + anymore. See \featureref{banned-commands}. +\end{description} +\end{document} diff --git a/credits.tex b/credits.tex index 8494516..ceec6cf 100644 --- a/credits.tex +++ b/credits.tex @@ -3,8 +3,9 @@ Thanks to Mike Kelly (package manager provided utilities, section~\ref{sec:pkg-mgr-commands}), Danny van Dyk (ebuild functions, section~\ref{sec:ebuild-functions}), David Leverton (various sections) and Petteri Räty (environment state, section~\ref{sec:ebuild-env-state}) for contributions. Thanks to -Christian Faulhammer for fixing some of the more horrible formatting screwups. Thanks also to Mike -Frysinger and Brian Harring for proof-reading and suggestions for fixes and/or clarification. +Christian Faulhammer for fixing some of the more horrible formatting screwups and providing the EAPI +cheat sheet. Thanks also to Mike Frysinger and Brian Harring for proof-reading and suggestions for +fixes and/or clarification. \section*{Copyright and Licence} diff --git a/pms.cls b/pms.cls index ca0874c..acbcf00 100644 --- a/pms.cls +++ b/pms.cls @@ -32,6 +32,7 @@ marginnote, paralist, parskip, + pdfpages, verbatim, algorithm, algorithmic diff --git a/pms.tex b/pms.tex index 8426706..745882b 100644 --- a/pms.tex +++ b/pms.tex @@ -46,6 +46,8 @@ \bibliography{pms} +\includepdf[pages=-,landscape]{eapi_cheatsheet} + \end{document} % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : -- 1.6.0.6