Developer's Handbook: Add some abuild stuff I wrote

1 files changed, 46 insertions, 6 deletions

diff --git a/src/devel/1_preparing.xml b/src/devel/1_preparing.xml
index 0966a44..4584caa 100644
--- a/src/devel/1_preparing.xml
+++ b/src/devel/1_preparing.xml
@@ -158,22 +158,62 @@
             <title>Packages and Repositories</title>
             <para>The <command>abuild</command> command enables you to build a package file for later installation on to one or more computers running the Adélie Linux dsitribution.  A <firstterm>package file</firstterm> is a kind of archive file that contains two key parts: package metadata, and package content files.</para>
             <para><firstterm>Package metadata</firstterm> is a collection of information used by a package manager, such as <command>apk</command>, to determine information about the package and the package file, including its name, version, maintainer contact information, installed size on disk, and more.  The <firstterm>package content files</firstterm> are a collection of one or more files that comprise the package itself, including executables, default configuration, data files, and any other files needed for the package to work properly.  In some cases it may also include templates, examples, or documentation.</para>
-            <para>All packages belong to a <firstterm>package repository</firstterm> or <firstterm>repo</firstterm>.  A repository is a collection of related packages.  The Adélie Linux distribution has three main repositories: the <database>system</database> repository, used for system software and important libraries; the <database>user</database> repository, used for the majority of packages that users may be interested in; and the <database>nonfree</database> repository, containing packages that do not have a free or libre license.
-                While you are developing on your own computer, you may have as many, or as few, repositories as you like.  It can use any name except the above three.  You may use a name such as <database>mypackages</database>, or just your username.  The repository is a directory on your computer's hard disk.  You may create it anywhere, but it is highly recommended that you store your repository in your home directory (<filename class="directory">/home/<userinput>yourname</userinput></filename>).</para>
+            <para>All packages belong to a <firstterm>package repository</firstterm> or <firstterm>repo</firstterm>.  A repository is a collection of related packages.  The Adélie Linux distribution has two main repositories: the <database>system</database> repository, used for system software and important libraries; and the <database>user</database> repository, used for the majority of packages that users may be interested in.
+                While you are developing on your own computer, you may have as many, or as few, repositories as you like.  It can use any name except the above two ('system' and 'user').  You may use a name such as <database>mypackages</database>, or just your username.  The repository is a directory on your computer's hard disk.  You may create it anywhere, but it is highly recommended that you store your repository as a subdirectory of your home directory (<filename class="directory">/home/<userinput>yourname</userinput>/<userinput>yourrepository</userinput></filename>).</para>
             <para>Each package you create will have its own directory inside your repository.  If you use the <command>newapkbuild</command> command (discussed later), this will be created for you automatically.  Inside this directory will be at least an <filename>APKBUILD</filename> file, which tells <command>abuild</command> the commands to run to build the package.  It may also contain patches or other files necessary for building the package, if necessary.</para>
             <para>Typically, the <command>abuild</command> command is executed inside the package's directory (for example, <filename class="directory">/home/<userinput>yourname</userinput>/packages/<userinput>pkgname</userinput></filename>).  However, by setting the <envar>APKBUILD</envar> environment variable to the absolute path on disk to an <filename>APKBUILD</filename> file, you may run <command>abuild</command> from any directory.</para>
         </section>
         <section>
             <title>Using the <command>abuild</command> Command</title>
-            <para>Running the <command>abuild</command> command with no arguments in a directory containing an <filename>APKBUILD</filename> file will cause it to install the dependencies of the package as listed in the <filename>APKBUILD</filename>, and then build the package.  Afterwards, the dependencies of the package that were not already installed on your computer are removed.
+            <para>Running the <command>abuild</command> command with no arguments in a directory containing an <filename>APKBUILD</filename> file will cause it to fetch the package's sources (if necessary), build the package, and create the package file.  Passing the <argument>-r</argument> argument to <command>abuild</command> will cause it to install the dependencies of the package as listed in the <filename>APKBUILD</filename>, and then build the package.  Afterwards, the dependencies of the package that were not already installed on your computer are removed.
                 If the build concluded successfully, the directory tree created for the source code and build system are removed by default.  You may configure what <command>abuild</command> removes when a package concludes building.
                 If the build fails to conclude successfully, no directories are removed by default.  You may configure what <command>abuild</command> removes when a package fails to build.</para>
-            <para><command>abuild</command> has many commands that you may use, for finer-grained control over the build process.  You may use the <command>abuild <parameter class="command">deps</parameter></command> command to only install the dependencies of the package, and use the <command>abuild <parameter class="command">unpack</parameter></command> command to unpack the source archive into the directory tree where it can later be built.  These and many other commands are described in more detail in the following section.</para>
+            <para><command>abuild</command> has many subcommands that you may use, for finer-grained control over the build process.  You may use the <command>abuild <parameter class="command">deps</parameter></command> subcommand to only install the dependencies of the package, and use the <command>abuild <parameter class="command">unpack</parameter></command> subcommand to unpack the source archive into the directory tree where it can later be built.  These and many other subcommands are described in more detail in the following section.</para>
             <para>There are additionally a number of options that you may pass to <command>abuild</command>, which are also described in more detail in the next section.</para>
         </section>
         <section>
-            <title><command>abuild</command> Commands</title>
-            <para><!-- XXX Write this --></para>
+            <title><command>abuild</command> Subcommands</title>
+            <para>The <command>abuild</command> command provides many subcommands that you may use while packaging software.</para>
+            <variablelist>
+                <varlistentry>
+                    <term><command>checksum</command></term>
+                    <listitem>This subcommand instructs <command>abuild</command> to recreate the checksum lines at the end of the <filename>APKBUILD</filename>.  This is typically used when "bumping" or upgrading the software package (which causes it to have new source code).  It is also used when creating, modifying, or removing patches from the package.</listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><command>fetch</command></term>
+                    <listitem>This subcommand instructs <command>abuild</command> to fetch external source(s) specified in <varname>source</varname> to the <varname>SRCDEST</varname> specified in your <filename>abuild.conf</filename>, and ensure they match the checksum(s) specified in the <filename>APKBUILD</filename>.  The default <varname>SRCDEST</varname> is <filename class="directory">/var/cache/distfiles</filename>.</listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><command>unpack</command></term>
+                    <listitem>This subcommand instructs <command>abuild</command> to unpack the archive files specified in <varname>source</varname> to the source directory.  For instance, if <varname>source</varname> contained "https://my-package.org/foobar-1.2.zip", the contents of "foobar-1.2.zip" would be extracted to the source directory</listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><command>prepare</command></term>
+                    <listitem>This subcommand instructs <command>abuild</command> to run the <function>prepare()</function> function from the <filename>APKBUILD</filename>.  If no <function>prepare()</function> is provided in the <filename>APKBUILD</filename>, <command>abuild</command> will run a default <function>prepare()</function> which will apply all patches specified in <varname>source</varname> to the source tree.</listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><command>build</command></term>
+                    <listitem>This subcommand instructs <command>abuild</command> to run the <function>build()</function> function from the <filename>APKBUILD</filename>.</listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><command>package</command></term>
+                    <listitem>This subcommand instructs <command>abuild</command> to run the <function>package()</function> function from the <filename>APKBUILD</filename>.</listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><command>rootpkg</command></term>
+                    <listitem>This subcommand </listitem>
+                </varlistentry>
+                <varlistentry>
+                </varlistentry>
+                <varlistentry>
+                </varlistentry>
+                <varlistentry>
+                </varlistentry>
+                <varlistentry>
+                </varlistentry>
+                <varlistentry>
+                </varlistentry>
+            </variablelist>
         </section>
     </section>
     <section>