\documentclass[a4paper,portrait,english,mathserif]{beamer}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{url}
\usepackage{lmodern}
\usepackage{stmaryrd}
\setcounter{tocdepth}{2}

\usetheme{CambridgeUS}

\setbeamercolor{palette primary}{fg=blue!50!black,bg=gray!20!white}
\setbeamercolor{palette secondary}{fg=blue!50!black,bg=gray!40!white}
\setbeamercolor{palette tertiary}{bg=blue!50!black,fg=white}
\setbeamercolor{titlelike}{bg=gray!20!white,fg=blue!50!black}
%\setbeamerfont{block title}{family=\sffamily}
\setbeamercolor{block title}{use=structure,fg=white,bg=structure.fg!75!black}
\setbeamercolor{block title alerted}{use=alerted text,fg=white,bg=alerted text.fg!75!black}
\setbeamercolor{block title example}{use=example text,fg=white,bg=example text.fg!75!black}
\setbeamercolor{block body}{parent=normal text,use=block title,bg=block title.bg!20!bg}
\setbeamercolor{block body alerted}{parent=normal text,use=block title alerted,bg=block title alerted.bg!20!bg}
\setbeamercolor{block body example}{parent=normal text,use=block title example,bg=block title example.bg!20!bg}

%\usefonttheme{serif}

\begin{document}

\title{User- and distro-friendly packaging}
\subtitle{Recommendations to upstream tarball providers}
\author[Jan\ Engelhardt]{Jan\ Engelhardt \texttt{<jengelh@inai.de>}}
\date{2011-Sep-11--14}
%Tue 2011-Sep-13 17:00 Ballroom, Zentrifuge
\institute[\textsf{o.S.C.2011}]{Presented at the openSUSE Conference 2011}

\frame{
	\titlepage
}

\frame{
	\noindent \begin{center}
	\includegraphics[width=120mm]{r2.png}\\
	This talk is R-rated :)
	\par\end{center}
}

\frame{
	\frametitle{Table of Contents}
	\tableofcontents[hideallsubsections]
}

\AtBeginSubsection[]
{
	\begin{frame}<beamer>
	\frametitle{TOC}

	\tableofcontents[currentsection]

	\end{frame}
}

\section{Introduction}

\frame{
	\frametitle{Abstract}

	This just for the non-live audience.

	\begin{block}

	Even after the release of a software tarball, there remains work to be
	done. Not all end-users run software from tarballs, but often rely on a
	form of infrastructure to (re)provide the software in a fashion of
	their liking~--- e.~g.\ a Linux distro shipping compiled binaries~---,
	and this transition is not completely automatable. This talk wants to
	give direction on how upstream software providers can reduce the
	workload for packagers in the downstream direction, and thus increase
	chances that your software will be available to more end-users.

	\end{block}
}

\frame{
	\frametitle{\only<1>{Nomenclature}\only<2>{Target audience}}

	\visible<1>{Software Propagation Line}

	\begin{itemize}

	\item {\color<2>{black!80} upstream developers: LOC crafting}

	\item release manager: package and release source code archive
	(usually a ``tarball''), and keeper of the GPG key

	\item {\color<2>{gray!50} distro contributor: takes tarball and produces a RPM
	package}

	\item {\color<2>{gray!50} end-user: installation of tarball or RPM
	package}

	\end{itemize}
}

\frame{
	\frametitle{Why You Should Care (1/3)}

	\begin{itemize}

	\item You retain the freedom to design your tarball releases

	\item presenting guidelines~--- not binding, but recommended
	nevertheless

	\pause

	\item it's about the users

	\begin{itemize}

	\item direct: end-users

	\item indirect: administrators, distro contributors,
	help desk/support line

	\end{itemize}

	\end{itemize}
}

\frame{
	\frametitle{Why You Should Care (2/3)}

	It's all about the users...

	\begin{itemize}

	\item faster for them to apply known paradigms
	\small{(e.~g.\ ``\texttt{./configure \&\& make install}'')}

	\item users don't want to RTFM

	\item provided docs even exist

	\pause

	\end{itemize}

	\pause

	When things go wrong

	\begin{itemize}

	\item negative reviews much have more weight

	\pause

	\item software ratings (incl.\ word of mouth) playing a role

	\item $\Rightarrow$ upset as few users as possible

	\end{itemize}
}

\frame{
	\frametitle{Why You Should Care (3/3)}

	And distros...

	\begin{itemize}

	\item want to contain rank growth (de:Wildwuchs)

	\item remember Factory has some 4600+ packages

	\item fewer deviations $\rightarrow$ fewer code, fewer chances for bugs

	\end{itemize}

	\pause

	And you want users, don't you?

	\begin{itemize}

	\item distro might just silently ``fix'' it to provide a better package
	experience

	\end{itemize}
}

\section{Source Archive}

\frame{
	\frametitle{Versioning Fundamentals}

	\begin{itemize}

	\item sequenced version numbers (\texttt{3.1} $<$ \texttt{3.1.4} $<$
	\texttt{3.14})

	\begin{itemize}

	\item tools like rpm etc.\ use this interpretation

	\end{itemize}

	\item other versioning schemes need conversion e.~g.\
	the decimal point scheme (\texttt{3.1} $<$ \texttt{3.14} $<$
	\texttt{3.2})

	\begin{itemize}

	\item \texttt{3.141} $\rightarrow$ \texttt{3.1.4.1}

	\item thankfully not widespread \pause (yes, I am ware of
	\TeX)

	\end{itemize}

	\end{itemize}
}

\frame{
	\frametitle{Source Archive Basics (1/4)}

	\begin{itemize}

	\item name of the archive file: should contain name and version\\
	(or usually just name for tarred-up snapshots)

	\item archive should extract into a new directory, not \texttt{\$PWD}

	\end{itemize}

	\begin{alertblock}{}
	\texttt{\$ \textbf{tar -xvvf foo-1.0.tar.xz}\\
	-rw-r-{}-r-{}- root/root 283 2011-09-12 configure.ac}
	\end{alertblock}

	\begin{exampleblock}{Install into a new directory}
	\texttt{\$ \textbf{tar -xvvf foo-1.0.tar.xz}\\
	-rw-r-{}-r-{}- root/root 283 2011-09-12 \underbar{foo-1.0}/configure.ac}
	\end{exampleblock}
}

\frame{
	\frametitle{Source Archive Basics (2/4)}

	\begin{itemize}

	\item top-level extracted directory's version (if any) should
	match archive version

	\end{itemize}

	\begin{alertblock}{}
	\texttt{\$ \textbf{tar -xvvf gap\underbar{4r4p12}.tar.xz}\\
	-rw-r-{}-r-{}- root/root 283 2011-09-12 gap\underbar{4r4}/configure}
	\end{alertblock}

	\begin{exampleblock}{Top-level directory's version (if any) should
	match archive version}
	\texttt{\$ \textbf{tar -xvvf foo-\underbar{1.0.5}.tar.xz}\\
	-rw-r-{}-r-{}- root/root 283 2011-09-12 foo-\underbar{1.0.5}/configure}
	\end{exampleblock}
}

\frame{
	\frametitle{Source Archive Basics (3/4)}

	\begin{itemize}

	\item omit redundant components

	\end{itemize}

	\begin{block}{Just one build per version so far;
	makes build number redundant}
	VirtualBox\textbf{-4.1}-4.1.2\_\textbf{73507}\_openSUSE114-1.x86\_64.rpm\\
	VirtualBox\textbf{-4.1}-4.1.0\_\textbf{73009}\_openSUSE114-1.x86\_64.rpm\\
	VirtualBox\textbf{-4.0}-4.0.12\_\textbf{72916}\_openSUSE114-1.x86\_64.rpm\\
	\end{block}

	\begin{itemize}

	\item version provided in \texttt{\%name} also redundant, since
	vbox-4.1 cannot be installed alongside vbox-4.0

	\end{itemize}
}

\frame{
	\frametitle{Source Archive Basics (4/4)}

	\begin{itemize}

	\item preferably do not mix separators;\\
	avoid ``releases'', only do ``versions'' (rpm/deb lingo):\\
	\texttt{ebtables-v2.0.10-2.tar.gz} $\rightarrow$
	\texttt{ebtables-2.0.10.2.tar.gz} \checkmark

	\item dots preferred as a separator within distros\\
	\texttt{gap4r4p12.tar.gz} $\rightarrow$ \texttt{gap-4.4.12.tar.gz}

	\end{itemize}
}

\frame{
	\frametitle{Archive Formats (1/2)}

	\begin{itemize}

	\item \texttt{.tar} is the container of choice,

	\begin{itemize}

	\item with \texttt{.gz} (oldskool) or \texttt{.xz} (modern)

	\end{itemize}

	\item also circulating: \texttt{.zip} (archaic), \texttt{.7z}

	\end{itemize}
}

\frame{
	\frametitle{Archive Formats (2/2)}

	\begin{itemize}

	\item recompressed and/or repackaged at times to different format

	\item reduction of BRPM/SRPM sizes

	\pause

	\item object files normally should not be in the archive

	\item much less in an SCM

	\end{itemize}
}

\frame{
	\frametitle{To Split or Not To Split?}

	{[}\includegraphics[width=10mm]{w2.png}: This frame has
	{\color{green!50!black} \textbf{\small{+}w}} capabilities.{]}

	\begin{itemize}

	\item big packages introduce serialization/limit scaleout

	\item split generic libraries from big projects:

	\begin{itemize}

	\item samba $\rightarrow$ libtalloc, libtdb, libtevent

	\item util-linux $\rightarrow$ libblkid, libmount, libuuid

	\end{itemize}

	\item documentation often likes to be put into the main package

	\item success stories?

	\begin{itemize}

	\item *-data packages, mostly in the ``games'' project

	\end{itemize}

	\end{itemize}
}

\section{Code Inside}

\frame{
	\frametitle{Source Availability}

	Do provide the source in a SCM:

	\begin{itemize}

	\item to grab the HEAD and make patches against that
	instead

	\item rather important if tarball releases reflect a state
	too old to receive patches,

	\begin{itemize}

	\item classical long-winded release cycles

	\item and where stable and devel have diverged quite a bit

	\item gap 4.4 vs.\ 4.5

	\item Linux 2.4 vs.\ 2.5

	\end{itemize}

	\item can see when and how my patch was applied

	\item can package the SCM HEAD and drop my local patch

	\end{itemize}
}

\frame{
	\frametitle{Source-level Build System}

	Claim: plain Makefiles are the most buggy ones. Examples:

	\begin{itemize}

	\item wrongful population of \texttt{CFLAGS}, which is a
	user-overridable variable, with essential flags

	\item failure to properly implement \texttt{DESTDIR} for `\texttt{make
	install}`

	\item parallel make rendered non-functional

	\end{itemize}

	\pause

	Use some common (source-level) build automation system.

	\begin{itemize}
	\item C, C++: automake, cmake, scons, ...
	\item Python: setup.py
	\item Perl: Makefile.PL
	\end{itemize}
}

\frame{
	\frametitle{Source-level Build Systems (2/2)}

	\$BUILD\_SYS

	\begin{itemize}

	\item no need to figure out names of variables in Makefiles

	\item use BS for consistency

	\begin{itemize}

	\item autoconf: options commonly start
	with \texttt{-{}-enable-} or \texttt{-{}-with-}

	\item ...

	\end{itemize}

	\item for simplicity, bug surface reduction

	\begin{itemize}

	\item automake: installation taken care of automatically

	\end{itemize}

	\end{itemize}
}

\frame{
	\frametitle{Compilation (C, C++) (1/2)}

	\begin{itemize}

	\item enable warnings, and address them

	\begin{block}{\texttt{-Wall} is not enough; useful \texttt{CFLAGS}:}
	\texttt{-D\_FORTIFY\_SOURCE=2 -Wall -Waggregate-return
	-Wmissing-declarations -Wmissing-prototypes -Wredundant-decls -Wshadow
	-Wstrict-prototypes -Wformat=2}
	\end{block}

	\item compiler may warn, but incorrectly, or only half of the time

	\item fixing itself requires in-depth knowledge of the used language

	\end{itemize}
}

\frame{
	\frametitle{Compilation (2/2)}

	\begin{alertblock}{}
	\texttt{printf(\textquotedbl{}\%d\textbackslash{}n\textquotedbl{},
	\textbf{sizeof}(\textbf{int}));}
	\end{alertblock}

	\begin{block}{Emitted Warning (and only on 64-bit!)}
	test.c:4:2: warning: format ``\%d'' expects argument of type ``int'',
	but argument 2 has type ``long unsigned int'' {[}-Wformat{]}
	\end{block}

	\only<1>{
		\begin{block}{Should we tr...}
		\texttt{\%ld}?
		\end{block}
	}
	\only<2->{
		\begin{alertblock}{Bzzzt}
		\texttt{\%ld}
		\end{alertblock}
	}

	\visible<2->{
	\begin{exampleblock}{}
	\texttt{printf(\textquotedbl{}\%zu\textbackslash{}n\textquotedbl{},
	sizeof(int));\\
	/{*} or in the absence of C99: {*}/\\
	printf(\textquotedbl{}\%lu\textbackslash{}n\textquotedbl{},
	(\textbf{long})\textbf{sizeof}(\textbf{int}));}
	\end{exampleblock}
	}
}

\frame{
	\frametitle{Library Versioning (1/2)}

	\pause

	\begin{alertblock}{}
	libqt4-\textbf{4.7.1}: \texttt{libQtCore.so.\textbf{4.7.1}}
	\end{alertblock}

	\begin{itemize}

	\item so-version equaling the package version is a sign of
	a possible error

	\item other platforms do not necessarily use the same three-component
	style for SO versions

	\item meaning of SO versions is nevertheless consistent across
	platforms

	\end{itemize}

	\pause

	\begin{block}{How SO versions work}

	\begin{tabular}{cccc}
	Qt version & linux SO ver & means API range & BSD SO ver\\
	\hline
	4.7.x & \texttt{4.7.x} \pause & 4--11\phantom{$\lightning$} & \texttt{.so.11}\phantom{$\lightning$}\\
	4.8.x & \texttt{4.8.x} \pause & 4--12\phantom{$\lightning$} & \texttt{.so.12}\phantom{$\lightning$}\\
	5.6.x & \texttt{5.6.x} \pause & 5--11$\lightning$ & \texttt{.so.11}$\lightning$
	\end{tabular}
	\end{block}
}

\frame{
	\frametitle{Library Versioning (2/2)}

	\begin{exampleblock}{Actually \textrm{\textbf{\emph{do}}} SO versioning}
	\begin{tabular}{rl}
	libx264 & \texttt{libx264.so.115}
	\end{tabular}
	\end{exampleblock}

	\pause

	\begin{exampleblock}{When not caring about SO ver.:
	change basename to ensure uniqueness}
	\begin{tabular}{rl}
	binutils-2.21    & \texttt{libbfd-2.21.so}\\
	hunspell-1.2.12  & \texttt{hunspell-1.2.so.0.0.0}
	\end{tabular}
	\end{exampleblock}

	\pause

	\begin{exampleblock}{...or combine both}
	\begin{tabular}{rl}
	libpng-1.2  & \texttt{libpng12.so.0.46.0}\\
	libpng-1.4  & \texttt{libpng14.so.14.4.0}\\
	glib-2.28.0 & \texttt{libglib-2.0.so.0.2800.0}
	\footnote{arguably, \texttt{libglib-2} as a basename would have been
	enough}
	\end{tabular}
	\end{exampleblock}
}

\section{Further Considerations}

\frame{
	\frametitle{$e^3$}

	\pause

	\begin{itemize}

	\item Extract: look for distros' build scripts, and build logs
	of your package

	\begin{itemize}

	\item \texttt{build.opensuse.org}

	\item \texttt{packages.debian.org}

	\end{itemize}

	\pause

	\item Examine: see how they build it, see what workarounds they made

	\begin{itemize}

	\item CDBS has many architectures $\rightarrow$
	new compile errors/warnings

	\item OBS: rpmlint and BRP results

	\end{itemize}

	\pause

	\item Enhance: merge useful parts preemptively,
	do not wait for distro to submit

	\end{itemize}
}

\section{Conclusion}

\frame{
	\title{Conclusions}

	\begin{itemize}

	\item stick to conventions, make it easy for users

	\item if you get patches that turn your Makefile into automake
	(or something else), do consider it

	\item do not be alarmed if someone runs \texttt{spec-beautifier}
	(or \texttt{spec-cleaner}~/ \texttt{obs-service-format\_spec\_file})

	\end{itemize}

	Ask if assistance needed:
}

\frame{
	\titlepage
}

\end{document}