[[!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