diff options
Diffstat (limited to 'dev/packaging/tutorials')
| -rw-r--r-- | dev/packaging/tutorials/basic.mdwn | 113 |
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 |