path: root/doc/introduction.docbook

<chapter id="introduction">
<title>Introduction</title>

<sect1 id="motivation">
<title>Motivation</title>

<para>
To make the software as portable as possible, back in the days, GNU
created the autoconf package, that allowed them to discover the
features of the compiler and of the C library they were building, so
they could build the same code over different operating systems and
platforms.
</para>

<para>
When the complexity of the software started to arise, to autoconf it
was added a software to make simpler writing the makefiles, too, which
is automake. But one of the most complex problems was writing shared
libraries (or rather shared objects are they are called in UNIX
world), because the rules for those might change a lot between
operating systems and compilers: position independent code, shared
object names, compiler switches and so on. To resolve this issue, GNU
libtool was created.
</para>

<para>
Unfortunately considered the complexity and the variety of the rules,
GNU libtool ended up being a very complex piece of software, and to
make it worse, it had to be written in a portable sh subset, which can
be difficult to read, not only to write, and then problems and errors
in code aroused, obviously.
</para>

<para>
For this reason, Gentoo Linux had always to cope with many problems
that were caused by software whose package was prepared with a broken
version of GNU libtool... some problems were caused by simple
non-portable syntaxes, others by unsafe permissions on temporary
files, or because libtool didn't support some targets present and
supported in Gentoo (like uClibc), or again because we want to
bend the default rules to suit our needs better (for Gentoo/FreeBSD
for instance).
</para>

<para>
To avoid having to patch all and every package with a similar patch to
fix libtool misbehavious, libtool.eclass and elibtoolize functions
were created. This eclass uses the patches present in the ELT-patches
directory, trying them one by one, to fix libtool for what we need.
</para>

<para>
Unfortunately there are issues with this design: we're bound to the
portage tree for the patchsets, there's a logical size limit because
we're using the Portage Tree itself as a patch repository, and the
changes to patches and behaviour go live directly on all the ebuilds
at the same time, so there's no prope way to get a patch in "testing".
</para>

<para>
And even if the eclass was created thinking about libtool, there are
many use cases that could be handled in a similar way, because there
are classes of packages that simply suffer from a common problem that
can be fixed with a simple similar patch (KDE packages, proper GNU
packages, GNOME packages, ...).
</para>

<para>
Beside the technical issues, there are also a few maintainership
issues, as the libtool eclass is pretty complex, and there is no
maintainer currently appointed to take care of it; this means that if a
problem arise or a new patch has to be added, someone has to try to
get a clue about the eclass to start with.
</para>

<para>
To fix these issue and to improve the points where there's space to
improve, the autoepatch project started, with the objective to provide
a simpler implementation for an elibtoolize workalike program,
disengaged from eclasses and the portage tree, that could be hooked up
inside Portage itself, so that ebuilds haven't to be aware of its
presence anymore.
</para>

</sect1>

<sect1 id="standalone">
<title>Reasoning for a standalone package</title>

<para>
There are many ways to accomplish the same result. Why the choice was
done toward a standalone package, that would require a new ebuild, and
a tarball, and so on? There are a series of reasons why this approach
is probably the best compromise between the weight of maintainership
and the ability to do changes without involving all the users at once.
</para>

<para>
The current method, of storing both the logic code and the patches on
the same CVS module used for the portage tree, and thus on the RSync
servers, is obviously flawed: the eclass has to know the PORTDIR path,
there's no way to overlay the patches if one has to be changed for
some reason; the code applies to all users at the same time, as the
eclass is not versioned for stable and testing branches; the size of
patches and logic code is restricted, because the size of the CVS tree
is a main concern, as it already increases with the increase of the
number of packages available; there's no security because neither the
eclasses nor the patches are signed or signable (at the current time
at least).
</para>

<para>
Another option would be to ship the logic code with either a
standalone package or portage and then ship the patches with the RSync
tree, but this leaves us with the security issue (although it might be
possible to find a solution to this), and with the size constraints
that we have with the current solution. Even if it would be possible
to just recode the logic to allow a separation between testing and
stable packages, it would be difficult to tell from an emerge --info
output what the user is using for a given package.
</para>

<para>
By using a separate standalone package it is possible to avoid limits
on the size of both the logic and the patches (that would be on their
own archive, which could just have a "reasonable size"), it is
possible to sign the ebuild in the tree, and thus the digest for the
tarball would be signed too, covering the security issue; there can be
different versions of the tarball, with different patches, that can
have different visibility depending on keywords and masked state, and
it can be easily told by an emerge --info which version of the package
is used once the profiles are instructed to.
</para>

<para>
Probably the worst drawback is that there's the need of a standalone
repository to contain the logic and the patches, but also this can be
considered an advantage as that allows us to branch it when moving to
a stable target.
</para>

</sect1>

</chapter>