diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/howitworks.docbook | 158 |
1 files changed, 72 insertions, 86 deletions
diff --git a/doc/howitworks.docbook b/doc/howitworks.docbook index 4472531..8b748f2 100644 --- a/doc/howitworks.docbook +++ b/doc/howitworks.docbook @@ -2,80 +2,71 @@ <title>How it works</title> <para> -In this chapter, we'll try to explain how autoepatch works, and how to -extend it to patch and fix new problems. The reason to provide a -throughout documentation about this is to make the maintainership of -autoepatch simpler, so that if the developers currently involved in -its writing would not be available, newcomers won't have to read all -the code to find how it actually works. +In this chapter, we'll try to explain how autoepatch works, and how to extend it +to patch and fix new problems. Specifically, this chapter is intended to make +maintaining autoepatch much simpler, especially for newcomers, who shouldn't +have to read all the code to understand how it works. </para> <sect1 id="requirements"> <title>Requirements</title> <para> -Being a package that is going to be in the system set, and used by -every user as a Portage component, autoepatch needs to have the -minimum impact over the dependencies of that set. For this reason, the -script is a bash script. As the targets for Gentoo software are less -wide than the general GNU or Open Source targets, there's no need to -use a portable subset of sh (as we already consider bash present), and -it can depend on a few GNU tools, or at least tools that can support -an acceptable subset of GNU parameters. +Being a package that is going to be in the system set, and used by every user as +a Portage component, autoepatch needs to have the minimum impact over the +dependencies of that set. For this reason, the script is written in bash. As the +targets for Gentoo software are less wide than the general GNU or Open Source +targets, there's no need to use a portable subset of sh (as we already consider +bash present), and it can depend on a few GNU tools, or at least tools that can +support an acceptable subset of GNU parameters. </para> <para> -There are basically two Gentoo specific softwares that are needed for -autoepatch: the first is baselayout, as autoepatch loads -/sbin/functions.sh to get functions like ebegin and eend, and -similar; the other is Portage, as autoepatch uses the portageq -command, and allows to the patchsets to use it. +There are basically two Gentoo-specific dependencies that are needed for +autoepatch: the first is baselayout, as autoepatch loads /sbin/functions.sh to +get functions like ebegin and eend; the other is Portage, as autoepatch uses the +portageq command, and allows the patchsets to use it. </para> <para> -First of all, as most of the patchsets are expected to be actual patch -files, the patch(1) command is supposed to be coming from GNU -project. While FreeBSD uses Larry Wall's patch(1) command, that -supports most of the options that GNU patch supports, there are some -tricky behaviours on fuzzyness of patches. If patch(1) is not a -GNU-compatible implementation, you can provide a GNU patch command -named <emphasis>gpatch</emphasis> that will be prioritised over the -normal patch(1). +First of all, as most of the patchsets are expected to be actual patch files, +the patch(1) command is supposed to be the GNU patch. While FreeBSD uses Larry +Wall's patch(1) command that supports most of the options that GNU patch +supports, there are some tricky behaviours on fuzzyness of patches. If patch(1) +is not a GNU-compatible implementation, you can provide a GNU patch command +named <emphasis>gpatch</emphasis> that will be prioritised over the normal +patch(1). </para> <para> -Another command on which behaviour the script relies more than just a -bit is find(1). Considering the frequency of execution of the script -itself, and thus of the targetting logic, the script tries to reduce -as much as possible the processes spawn, so instead of using xargs(1) -command to transform the find(1) output to input arguments to other -commands, autoepatch relies on find(1) to support the <emphasis>-exec -cmd {} +</emphasis> syntax. +Another command on which behaviour the script relies more than just a bit is +find(1). Considering the frequency of execution of the script itself, and thus +of the targeting logic, the script tries to reduce as much as possible the +processes spawned, so instead of using the xargs(1) command to transform the +find(1) output to input arguments to other commands, autoepatch relies on +find(1) to support the <emphasis>-exec cmd {} +</emphasis> syntax. </para> <para> -Luckily not only GNU findutils, but also FreeBSD, Darwin and NetBSD find(1) -implementations support that syntax. OpenBSD on the other hand does -not, so to allow autoepatch to work on that operating system, a -special handling for the find command was written: by replacing the -string <emphasis>@findcmd@</emphasis> with the path, or the name, of a -compatible find implementation (most likely GNU find), you can tell -autoepatch to run an alternative command. +Fortunately, FreeBSD, Darwin and NetBSD find(1) implementations support the GNU +findutils syntax. OpenBSD on the other hand does not, so to allow autoepatch to +work on that operating system, a special handling for the find command was +written: by replacing the string <emphasis>@findcmd@</emphasis> with the path, +or the name, of a compatible find implementation (most likely GNU find), you can +tell autoepatch to run an alternative command. </para> <para> -As there is often the need to get a temporary file, either for log or -debugging purposes, or to store intermediate results, the mktemp -utility is also required. Unfortunately, the mktemp utility found on -most Linux implementations (Gentoo Linux included) comes from -debianutils package, and has a syntax incompatible with the original -BSD mktemp utility. As the autoepatch script does not get the USERLAND -variable from Portage, and tries to be entirely transparent to that -matter, the choice between the two implementations is done at runtime -by checking the outcome of calling <emphasis>mktemp -V</emphasis>; on -Debian implementation, this reports the version of the command itself, -while it simply fails on BSD implementation. The emktemp wrapper is -picked up from eutils.eclass. +As there is often the need to get a temporary file, either for log or debugging +purposes, or to store intermediate results, the mktemp utility is also required. +Unfortunately, the mktemp utility found on most Linux implementations (Gentoo +Linux included) comes from debianutils package, and has a syntax incompatible +with the original BSD mktemp utility. As the autoepatch script does not get the +USERLAND variable from Portage (and tries to be entirely transparent), the +choice between the two implementations is done at runtime by checking the +outcome of calling <emphasis>mktemp -V</emphasis>. On Debian implementation, +this reports the version of the command itself, while it simply fails on BSD +implementation. The emktemp wrapper is picked up from eutils.eclass. </para> </sect1> @@ -84,11 +75,10 @@ picked up from eutils.eclass. <title>Concepts</title> <para> -There aren't many concepts to describe on autoepatch because it is, -basically, a simple set of scripts. The definitions that will be given -here are not even proper "concepts" but this section is intented to -clear up the terminology used, so that there can't be misunderstanding -in the next sections and chapters. +Autoepatch is, basically, a simple set of scripts. The definitions that will be +given here are not even proper "concepts," but this section is intended to clear +up the terminology used, to prevent any misunderstanding in the next sections +and chapters. </para> <variablelist> @@ -97,22 +87,20 @@ in the next sections and chapters. <listitem> <para> - With this term, the documentation will refer to a set of scripts - and actual patches, the base element handled by autoepatch itself. - Despite the name used seem to limit a patchset to just patches, - it's well possible that a patchset has no actual ".patch" file, - and instead consist of a single shell script that describes the - changes to apply to targets. + This is a set of scripts and actual patches, and is the base element handled + by autoepatch itself. Despite the name, it's possible that a "patchset" has + no actual ".patch" file, and instead consists of a single shell script that + describes the changes to will be applied to the targets. </para> <para> - The patchsets can be found in the repository inside the patches - directory, or for the installed copy in - /usr/share/autoepatch/patches - <footnote><para> - For alternative prefixes support, see <xref - linkend="prefixsupport" />. - </para></footnote> + The patchsets can be found in the repository inside the patches/ directory, + or for the installed copy in /usr/share/autoepatch/patches. + <footnote> + <para> + For alternative prefixes support, see <xref linkend="#prefixsupport" />. + </para> + </footnote> </para> </listitem> @@ -123,19 +111,18 @@ in the next sections and chapters. <listitem> <para> - Under this name we consider a file, or a directory, on which the - patchset applies. When the target is a directory, ad the patchset - contains actual patches, the paths inside the patches should refer - to the direct name of the files starting from the target directory - (-p0 option to gpatch); when the target is a file instead, the - patch will apply directly over the file. When instead the patchset - consist of a function (or a series of functions), the target is - passed as parameter, whichever the type it is. + This is a file or a directory on which the patchset applies. When the target + is a directory, and the patchset contains actual patches, the paths inside + the patches should refer to the direct name of the files starting from the + target directory (-p0 option to gpatch). When the target is a file, the + patch will apply directly over the file. When instead the patchset consist + of a function (or a series of functions), the target is passed as parameter, + whichever the type it is. </para> <para> - For more informations about target, look at <xref - linkend="writingpatchsets" />. + For more informations about target, look at <xref linkend="writingpatchsets" + />. </para> </listitem> @@ -188,11 +175,10 @@ to pass the result of grep -l, also add the --null parameter. <title>Alternative prefixes support</title> <para> -Although Portage, at the time of writing, it's limited to work as a -primary package manager and does not support officially a way to -install packages on an alternate prefix (like /usr/local or something -else), autoepatch is designed to support being installed in an -arbitrary prefix from day one. +At the time of writing, Portage does not officially support a way to install +packages on an alternate prefix (such as /usr/local). However, autoepatch has +been designed from the beginning to support being installed in an arbitrary +prefix. </para> <para> |