Begin writing a basic packaging tutorial.

1 files changed, 113 insertions, 0 deletions

diff --git a/dev/packaging/tutorials/basic.mdwn b/dev/packaging/tutorials/basic.mdwn
new file mode 100644
index 0000000..f8a3ee9
--- /dev/null
+++ b/dev/packaging/tutorials/basic.mdwn
@@ -0,0 +1,113 @@
+[[!meta title="Basic Packaging Tutorial"]]
+
+In this introduction to software packaging, we will package the Expat XML parser
+library.  This is a pretty simple but complete package, consisting of a shared
+library and its development files plus an executable utility and some
+documentation.
+
+We will use [opkbuild 3.0.x][opkbuild] to build a package in [Source Package
+Format 2.0][spf] (SPF 2.0) with the assistance of [opkhelper 3.0.x][opkhelper].
+
+This tutorial assumes some knowledge of the UNIX shell command language and
+utilities (see the "Shell and Utilities" volume of [POSIX.1-2008][posix]) and at
+least basic familiarity with [makefile syntax][posix-makefile].
+
+
+Getting Started
+===============
+
+Source Package Directory
+------------------------
+
+First, make a *source package directory*.  This is the directory that will
+contain all of our source package files.  SPF 2.0 makes no requirements on the
+name of this directory, but using the name of the source package is recommended.
+
+    $ mkdir expat
+    $ cd expat
+
+We need [a file called `format`][spf-format] to identify the format of our
+source package.  For SPF 2.0, it should simply contain the string `2.0`.
+
+    $ echo '2.0' >format
+
+Upstream Source Archive
+-----------------------
+
+Obviously we need the source code of the software to be packaged.  Go to
+[Expat's Web site][expat], find the expat 2.1.0 archive, and download it into
+the source package directory.
+
+    $ wget 'http://downloads.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz'
+
+SPF 2.0 requires that an [upstream source archive][spf-upstream-source] be named
+`<pkgname>-<pkgver>.orig.tar<ext>`, where `<pkgname>` is the name of the source
+package, `<pkgver>` is the upstream version of the source package, and `<ext>`
+is an optional file extension to indicate compression.  So, rename the archive
+accordingly.
+
+    $ mv 'expat-2.1.0.tar.gz' 'expat-2.1.0.orig.tar.gz'
+
+
+Source Package Metadata
+=======================
+
+Now we need some metadata for our source package.
+
+Control File
+------------
+
+First we'll make a `control` file.  The format of this file is not yet
+documented in the SPF 2.0 specification, but it is documented [in the Debian
+Policy Manual][dpm-control].  The [source package fields][spf-fields-src] are
+`Maintainer` (required), `Build-Depends` (optional), and `Homepage` (optional).
+We'll fill in the fields whose values we know right now: `Maintainer` and
+`Homepage`.
+
+`Maintainer` is the name and e-mail address of the person or team responsible
+for the package (i.e. usually you when you are making a package).  The value
+must follow the syntax of the `mailbox` symbol in [RFC 5322 section
+3.4][rfc-5322-3.4].  That is, the value must be of the form `name <address>`.
+If `name` contains any of the following characters, it must be in double quotes:
+
+    ( ) < > [ ] : ; @ \ , .
+
+`Homepage` is the URL of the Web site for the package, if such a site exists.
+
+Our expat `control` file looks like this:
+
+    Maintainer: "J. Random Hacker" <jrandom@example.com>
+    Homepage: http://expat.sourceforge.net/
+
+Change Log
+----------
+
+Now we'll make a `changelog` file.  The format of this file is documented [in
+the SPF 2.0 specification][spf-changelog].  We're making version "2.1.0-1" of
+the "expat" source package for the "trunk" distribution.  We can get the current
+date and time in the RFC 5322 format using the **date**(1) command:
+
+    $ date '+%a, %d %b %Y %H:%M:%S %z'
+
+Our expat `changelog` file looks like this:
+
+    expat (2.1.0-1) trunk
+    
+      * Initial release.
+    
+     -- "J. Random Hacker" <jrandom@example.com>  Sun, 18 Nov 2012 11:58:19 -0500
+
+TODO: Finish.
+
+[opkbuild]: http://git.os.libiquity.com/opkbuild/opkbuild.git/
+[spf]: http://specs.os.libiquity.com/spf-2.0/
+[opkhelper]: http://git.os.libiquity.com/opkhelper/opkhelper.git/
+[posix]: http://pubs.opengroup.org/onlinepubs/9699919799/
+[posix-makefile]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html#tag_20_76_13
+[spf-format]: http://specs.os.libiquity.com/spf-2.0/overview.html#files-format
+[expat]: http://expat.sourceforge.net/
+[spf-upstream-source]: http://specs.os.libiquity.com/spf-2.0/overview.html#files-src-src-ver-tar-ext
+[dpm-control]: http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax
+[spf-fields-src]: http://specs.os.libiquity.com/spf-2.0/fields.html#fields-src
+[rfc-5322-3.4]: https://tools.ietf.org/html/rfc5322#section-3.4
+[spf-changelog]: http://specs.os.libiquity.com/spf-2.0/metadata.html#changelog