doc/pkg/basic-expat: New file

Copied from dev/packaging/tutorials/basic.

1 files changed, 761 insertions, 0 deletions

diff --git a/doc/pkg/basic-expat.mdwn b/doc/pkg/basic-expat.mdwn
new file mode 100644
index 0000000..5d54a73
--- /dev/null
+++ b/doc/pkg/basic-expat.mdwn
@@ -0,0 +1,761 @@
+[[!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].
+
+This tutorial presents one possible packaging workflow that seems to work well.
+There is no mandatory workflow to packaging.  The only requirements are those
+made by the source package format and any build helper utilities that are used.
+
+[opkbuild]: http://git.proteanos.com/opkbuild/opkbuild.git/
+[spf]: http://specs.proteanos.com/spf-2.0/
+[opkhelper]: http://git.proteanos.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
+
+
+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'
+
+[spf-format]: http://specs.proteanos.com/spf-2.0/overview.html#files-format
+[expat]: http://expat.sourceforge.net/
+[spf-upstream-source]: http://specs.proteanos.com/spf-2.0/overview.html#files-src-src-ver-tar-ext
+
+
+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:
+
+    $ LC_ALL='POSIX' 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
+
+
+Building the Software
+=====================
+
+We can now write our `build` makefile to try to get the Expat software to build.
+[The `build` makefile][spf-build] "directs the process of building and
+installing data files to be provided by binary packages".
+
+Looking Through the Source
+--------------------------
+
+With a "[no-op][no-op]" target in `build`, we can make **opkbuild**(1) prepare a
+*[build work area][spf-work-area]* with the unpacked source code and stop.  This
+target isn't required by SPF 2.0, but it seems to facilitate a nice workflow.
+So begin writing `build` as follows:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+
+Note that, due to makefile syntax, the line after `nop:` must begin with a tab
+character.  This line is called a "command line" in makefile syntax.  The [`:`
+utility][posix-colon] is a "null utility" that returns an exit status of zero.
+A command prefix of `@` tells **make**(1) to not write the command to standard
+output before executing it.
+
+The `build` makefile must be executable, so set its file mode:
+
+    $ chmod 755 build
+
+We can now make **opkbuild**(1) prepare our build work area.
+
+    $ opkbuild -b -c -T nop
+
+The options are explained in the help output of opkbuild, obtained by running
+`opkbuild -h`.  The `-b` option tells **opkbuild**(1) to build only binary
+packages (no source package).  The `-c` option tells it to not clean up the work
+area after building packages.  The `-T` option specifies a target to be built
+instead of the standard `build` and `install` targets.
+
+Now look in `tmp/src/`, the location of the source code within the build work
+area.
+
+    $ ls tmp/src/
+
+Look for some documentation file that might tell us how to build Expat.  This
+kind of information is usually kept in a file called `INSTALL` or `README`.
+Expat's `README` file says to run `./configure`, then `make` and `make install`.
+
+Looking at `tmp/src/configure`, we see that it is "[g]enerated by GNU Autoconf
+2.68 for expat 2.1.0".  The `tmp/src/README` file reports that the makefile
+supports the use of either the `DESTDIR` or `INSTALL_ROOT` macro to install
+Expat somewhere other than in the root of the filesystem.  So, we should be able
+to use opkhelper's buildsystem utilities to automatically configure, build, and
+install Expat for us.
+
+Building
+--------
+
+So let's add a `build` target to our `build` makefile.  The makefile should now
+look like this:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+    
+    build:
+    	oh-autoconfigure
+    	oh-autobuild
+    	touch $@
+
+Read the manual pages and/or source code of **oh-autoconfigure**(1) and
+**oh-autobuild**(1) to learn more about what they do.
+
+The `touch $@` command is recommended by SPF 2.0:
+
+> The build target should create a file named build in the build work area to
+> prevent configuration and compilation from being performed multiple times.
+
+We can now build Expat.
+
+    $ opkbuild -b -c -T build
+
+[dpm-control]: http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-controlsyntax
+[spf-fields-src]: http://specs.proteanos.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.proteanos.com/spf-2.0/metadata.html#changelog
+[spf-build]: http://specs.proteanos.com/spf-2.0/buildsys.html#build
+[no-op]: https://en.wiktionary.org/wiki/no-op
+[spf-work-area]: http://specs.proteanos.com/spf-2.0/buildsys.html#work-area
+[posix-colon]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#colon
+
+
+Installing the Software
+=======================
+
+We can now finish our `build` makefile to install the Expat software and make
+some binary packages.
+
+Installing
+----------
+
+Add a basic `install` target to the `build` makefile.  The makefile should now
+look like this:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+    
+    build:
+    	oh-autoconfigure
+    	oh-autobuild
+    	touch $@
+    
+    install: build
+    	oh-autoinstall
+
+The `install` target is declared as depending on the `build` target:
+
+    install: build
+
+Read the manual page and/or source code of **oh-autoinstall**(1) to learn more
+about what it does.
+
+Install Expat:
+
+    $ opkbuild -b -c -T install
+
+Splitting Files Into Binary Packages
+------------------------------------
+
+Look in the *installation destination directory* `tmp/dest/` for files installed
+by Expat's build system.  This can be done with the **find**(1) command, which
+results in the following when building for the `core-linux-eglibc` architecture:
+
+    $ find tmp/dest -exec ls -Fd '{}' ';' | sed 's|^tmp/dest||'
+    /
+    /usr/
+    /usr/bin/
+    /usr/bin/xmlwf*
+    /usr/share/
+    /usr/share/man/
+    /usr/share/man/man1/
+    /usr/share/man/man1/xmlwf.1
+    /usr/lib/
+    /usr/lib/core-linux-eglibc/
+    /usr/lib/core-linux-eglibc/pkgconfig/
+    /usr/lib/core-linux-eglibc/pkgconfig/expat.pc
+    /usr/lib/core-linux-eglibc/libexpat.so@
+    /usr/lib/core-linux-eglibc/libexpat.a
+    /usr/lib/core-linux-eglibc/libexpat.la*
+    /usr/lib/core-linux-eglibc/libexpat.so.1@
+    /usr/lib/core-linux-eglibc/libexpat.so.1.6.0*
+    /usr/include/
+    /usr/include/expat_external.h
+    /usr/include/expat.h
+
+We have the `libexpat.so.1.6.0` shared library and two symbolic links to it:
+`libexpat.so.1` and `libexpat.so`.  We have the `libexpat.a` static library and
+associated `libexpat.la` library metadata file generated by GNU libtool.  We
+have a pkg-config file and two header files.  We have an executable utility and
+an associated manual page.
+
+We should therefore split these files into four binary packages: one for the
+shared library, one for the library development files, one for the utility, and
+one for the utility's documentation.
+
+To find out what we should call the library package, we can use **objdump**(1)
+to get the *SONAME* of the library:
+
+    $ objdump -p tmp/dest/usr/lib/core-linux-eglibc/libexpat.so.1.6.0 | grep SONAME
+      SONAME               libexpat.so.1
+
+We should name our library package after the SONAME of the shared library,
+without `.so`.  The binary package shall be named **`libexpat.1`**.
+
+The versionless `libexpat.so` link is only needed by **ld**(1) when linking a
+just-compiled object with the `-lexpat` linker flag.  So this can be provided by
+our library development package.  Also provided by that package will be the
+header files, the pkg-config file, and the static library.  The development
+package can be called **`libexpat.1-dev`**.
+
+The `xmlwf` utility can be provided by a package called simply **`xmlwf`**.
+
+The `xmlwf.1` manual page can be provided by a package called **`xmlwf-doc`**.
+
+
+Binary Packages
+===============
+
+Binary Package Metadata
+-----------------------
+
+Each binary package to be built needs to have [a directory for its
+metadata][spf-binpkg.pkg].  So let's create directories for our packages.
+
+    $ mkdir libexpat.1.pkg libexpat.1-dev.pkg xmlwf.pkg xmlwf-doc.pkg
+
+SPF 2.0 requires a `control` file for each binary package.  The format of this
+file is the same as that of the source package `control` file.  The required
+[binary package fields][spf-fields-bin] are `Architecture`, `Platform`, and
+`Description`.
+
+None of these binary packages are platform-specific, so they will all have a
+`Platform: all` field.  All of the binary packages except `xmlwf-doc` are
+architecture-specific; that is, they provide files whose contents depend on the
+host architecture (files like executable and linkable objects).  So `xmlwf-doc`
+will have an `Architecture: all` field while the others will have `Architecture:
+any` fields.
+
+Let's start with the `libexpat.1.pkg/control` file:
+
+    Architecture: any
+    Platform: all
+    Description: XML parser library
+     Expat is an XML parser library written in C. It is a stream-oriented parser in
+     which an application registers handlers for things the parser might find in the
+     XML document (like start tags).
+
+That's fairly simple.
+
+Now let's write a `control` file for `libexpat.1-dev`.  Because it provides
+development files for `libexpat.so.1`, `libexpat.1-dev` should depend on the
+`libexpat.1` package.  This should be a versioned dependency, because the
+`libexpat.so` symbolic link points to a specific version of `libexpat.so`.
+
+    Architecture: any
+    Platform: all
+    Depends: libexpat.1 (= 2.1.0-1)
+    Description: XML parser library - development files
+     Expat is an XML parser library written in C. It is a stream-oriented parser in
+     which an application registers handlers for things the parser might find in the
+     XML document (like start tags).
+     .
+     This package provides development files for Expat.
+
+Next is `xmlwf`, which should also depend on `libexpat.1` since the `xmlwf`
+utility is dynamically linked against the `libexpat.so.1` library.
+
+    Architecture: any 
+    Platform: all 
+    Depends: libexpat.1
+    Description: XML parser library - example application
+     This package provides an example application of Expat that determines if an XML 
+     document is well-formed.
+
+Finally, we can write metadata for `xmlwf-doc`, which should depend on `xmlwf`
+since it documents the `xmlwf` utility.
+
+    Architecture: all 
+    Platform: all 
+    Depends: xmlwf
+    Description: XML parser library - example application documentation files
+     This package provides the manual page for xmlwf, an example application of
+     Expat that determines if an XML document is well-formed.
+
+Binary Package Data Files
+-------------------------
+
+The **oh-installfiles**(1) utility of opkhelper, which we'll be using to install
+files into *binary package data directories*, requires a `files` file for each
+binary package that is to provide data files.
+
+Recall how we decided to split files between packages.  We will now write
+pathname patterns to do this.
+
+Again, let's start with `libexpat.1`.  We can write the following pattern in
+`libexpat.1.pkg/files`:
+
+    /usr/lib/*/libexpat.so.*
+
+This will match `/usr/lib/core-linux-eglibc/libexpat.so.1` and
+`/usr/lib/core-linux-eglibc/libexpat.so.1.6.0`; these two files will be provided
+by `libexpat.1`.
+
+The patterns for `libexpat.1-dev` are a little more complicated:
+
+    /usr/include
+    /usr/lib/*/libexpat.so
+    /usr/lib/*/libexpat.a
+    /usr/lib/*/pkgconfig
+
+The first pattern simply matches the directory containing header files.  The
+second matches the versionless symbolic link; remember this is used by **ld**(1)
+to link a just-compiled object against `libexpat.so.1.6.0`.  The third matches
+the static library, and the fourth matches the directory containing the
+`expat.pc` pkg-config file.
+
+`xmlwf.pkg/files` need only contain a pattern to match the directory containing
+the `xmlwf` utility.
+
+    /usr/bin
+
+`xmlwf-doc.pkg/files` is similarly simple:
+
+    /usr/share/man/man1
+
+With these pathname patterns done, we can add **oh-installfiles**(1) to our
+`build` makefile:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+    
+    build:
+    	oh-autoconfigure
+    	oh-autobuild
+    	touch $@
+    
+    install: build
+    	oh-autoinstall
+    	oh-installfiles
+
+Now run **opkbuild**(1) again:
+
+    $ opkbuild -b -c -T install
+
+You can verify that all files were installed where they should be:
+
+    $ find tmp/*.data -exec ls -Fd '{}' ';'
+    tmp/libexpat.1.data/
+    tmp/libexpat.1.data/usr/
+    tmp/libexpat.1.data/usr/lib/
+    tmp/libexpat.1.data/usr/lib/core-linux-eglibc/
+    tmp/libexpat.1.data/usr/lib/core-linux-eglibc/libexpat.so.1@
+    tmp/libexpat.1.data/usr/lib/core-linux-eglibc/libexpat.so.1.6.0*
+    tmp/libexpat.1-dev.data/
+    tmp/libexpat.1-dev.data/usr/
+    tmp/libexpat.1-dev.data/usr/lib/
+    tmp/libexpat.1-dev.data/usr/lib/core-linux-eglibc/
+    tmp/libexpat.1-dev.data/usr/lib/core-linux-eglibc/pkgconfig/
+    tmp/libexpat.1-dev.data/usr/lib/core-linux-eglibc/pkgconfig/expat.pc
+    tmp/libexpat.1-dev.data/usr/lib/core-linux-eglibc/libexpat.so@
+    tmp/libexpat.1-dev.data/usr/lib/core-linux-eglibc/libexpat.a
+    tmp/libexpat.1-dev.data/usr/include/
+    tmp/libexpat.1-dev.data/usr/include/expat_external.h
+    tmp/libexpat.1-dev.data/usr/include/expat.h
+    tmp/xmlwf.data/
+    tmp/xmlwf.data/usr/
+    tmp/xmlwf.data/usr/bin/
+    tmp/xmlwf.data/usr/bin/xmlwf*
+    tmp/xmlwf-doc.data/
+    tmp/xmlwf-doc.data/usr/
+    tmp/xmlwf-doc.data/usr/share/
+    tmp/xmlwf-doc.data/usr/share/man/
+    tmp/xmlwf-doc.data/usr/share/man/man1/
+    tmp/xmlwf-doc.data/usr/share/man/man1/xmlwf.1
+
+Cleaning Up Installed Files
+---------------------------
+
+There are few things we can do to improve our `build` makefile's `install`
+target.
+
+You may have noticed **oh-installfiles**(1) warn that something hasn't been
+installed:
+
+> oh-installfiles: Warning: Some files have not been installed into packages
+
+With **find**(1), we can see that this is the `libexpat.la` file that GNU
+libtool generated.
+
+    $ find tmp/dest -type f -exec ls -Fd '{}' ';' | sed 's|^tmp/dest||'
+    /usr/lib/core-linux-eglibc/libexpat.la*
+
+We don't need this, and we can simply delete it in the `install` target.
+
+Next, note that some file permissions aren't entirely correct.  For example,
+`libexpat.so.1.6.0` is executable, but almost all libraries need not be.
+
+So we can call **oh-fixperms**(1) in our `install` target to automatically set
+correct permissions for us.
+
+Finally, note that the executable and linkable objects are not stripped: they
+contain all of their symbols, including those only needed for debugging.
+
+    $ file tmp/libexpat.1.data/usr/lib/core-linux-eglibc/libexpat.so.1.6.0
+    tmp/libexpat.1.data/usr/lib/core-linux-eglibc/libexpat.so.1.6.0: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, BuildID[sha1]=0x2d88e36feeb8245bfa2f63f2f0e9a9f8232f6d2c, not stripped
+    $ file tmp/xmlwf.data/usr/bin/xmlwf
+    tmp/xmlwf.data/usr/bin/xmlwf: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.26, BuildID[sha1]=0xdb5f686930b13b8a5e7519efb446a2da14de9856, not stripped
+
+We can call **oh-strip**(1) in our `install` target to automatically strip
+objects for us.
+
+So our `build` makefile should now look like this:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+    
+    build:
+    	oh-autoconfigure
+    	oh-autobuild
+    	touch $@
+    
+    install: build
+    	oh-autoinstall
+    	rm -f 'dest/usr/lib/$(OPK_HOST_ARCH)/libexpat.la'
+    	oh-fixperms
+    	oh-strip
+    	oh-installfiles
+
+[spf-binpkg.pkg]: http://specs.proteanos.com/spf-2.0/overview.html#files-binpkg.pkg
+[spf-fields-bin]: http://specs.proteanos.com/spf-2.0/fields.html#fields-src
+
+
+Documentation and Finishing Touches
+===================================
+
+Source Package Documentation
+----------------------------
+
+SPF 2.0 [specifies][spf-docs] that one of the binary packages built from a
+source package provides documentation files about the source package and is
+depended upon by all of the other binary packages from the source package.
+
+So we should pick one common binary package that should be a dependency of all
+of our other binary packages.  `libexpat.1` is a good candidate for this, since
+it is already a direct dependency of `libexpat.1-dev` and `xmlwf` and an
+indirect dependency of `xmlwf-doc`.
+
+Per SPF 2.0, we can mark `libexpat.1` as providing source package documentation
+by making a `docs` file in its metadata directory.
+
+    $ touch libexpat.1.pkg/docs
+
+We should make all of our other binary packages directly depend on `libexpat.1`
+version `2.1.0-1`.  For example, `xmlwf-doc.pkg/control` should now look like
+this:
+
+    Architecture: all 
+    Platform: all 
+    Depends: libexpat.1 (= 2.1.0-1), xmlwf
+    Description: XML parser library - example application documentation files
+     This package provides the manual page for xmlwf, an example application of
+     Expat that determines if an XML document is well-formed.
+
+Substitution Variables
+----------------------
+
+We've hardcoded the `libexpat.1` binary package version in many of our control
+files.  What will we do when we make a new version of our source package?  We'll
+have to change all of these values in all of these places.
+
+[*Substitution variables*][spf-substvars] (*substvars* for short) make this
+unnecessary.  We can just use the `Binary-Version` substitution variable in our
+control files to refer to the version of our binary packages.  For example, our
+`xmlwf-doc.pkg/control` file should now look like this:
+
+    Architecture: all 
+    Platform: all 
+    Depends: libexpat.1 (= ${Binary-Version}), xmlwf
+    Description: XML parser library - example application documentation files
+     This package provides the manual page for xmlwf, an example application of
+     Expat that determines if an XML document is well-formed.
+
+But that's not all!  We can define our own variables as well.
+
+Note that the descriptions of our `libexpat.1` and `libexpat.1-dev` packages
+have a common paragraph.  We can put that in a file called `substvars`:
+
+    Common-Description:
+     Expat is an XML parser library written in C. It is a stream-oriented parser in
+     which an application registers handlers for things the parser might find in the
+     XML document (like start tags).
+
+As noted by the SPF 2.0 specification, the leading newline character in the
+value is fine:
+
+> Values may be comprised of multiple lines, and empty lines at the beginning
+> and end of each substitution variable value shall be removed.
+
+We can now use this variable in our `control` files.  Here's
+`libexpat.1.pkg/control`:
+
+    Architecture: any
+    Platform: all
+    Description: XML parser library
+     ${Common-Description}
+
+And here's `libexpat.1-dev.pkg/control`:
+
+    Architecture: any
+    Platform: all
+    Depends: libexpat.1 (= ${Binary-Version})
+    Description: XML parser library - development files
+     ${Common-Description}
+     .
+     This package provides development files for Expat.
+
+Copyright and License Information
+---------------------------------
+
+We're almost done; we just have one more important thing to do.  We need to
+document the copyright information for the upstream software and our own
+packaging work.
+
+This is done in the `copyright` file.  There is currently no standard format for
+this file.
+
+We need to collect the copyright and license information from the upstream
+source code (usually in comments at the tops of source files).
+
+There are some resources available to assist us with this.  First, we can look
+at the work already done by package maintainers in the Debian Project.  Find the
+[copyright file][deb-expat-copyright] for Debian's `expat` source package.
+
+We see the following copyright information:
+
+    Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
+                                   and Clark Cooper
+    Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006 Expat maintainers.
+
+We also see that Expat can be dealt in under the terms of, unsurprisingly, the
+Expat (a.k.a. "MIT") license.
+
+Another resource we can use is the [**licensecheck**(1) tool][licensecheck],
+maintained in Debian's `devscripts` package and originally based on a script
+from the KDE SDK.  Recursively run **licensecheck**(1) to report copyright and
+license information.
+
+    $ licensecheck -r --copyright tmp/src/
+
+We see that some source files have publication dates in their copyright notices
+that are newer than those that Debian's copyright file lists:
+
+    tmp/src/amiga/expat_lib.c: MIT/X11 (BSD like)
+      [Copyright: 2001-2009 Expat maintainers / HOLDERS BE LIABLE FOR ANY]
+
+So collect some representative copyright notices – e.g. from
+`tmp/src/lib/xmlparse.c`, `tmp/src/examples/outline.c`,
+`tmp/src/vms/expat_config.h`, and `tmp/src/amiga/expat_lib.c` – and add them to
+the `copyright` file.
+
+Then describe the license under which the software may be used.  `Expat` is a
+"common license" included under `/usr/share/common-licenses/` in this
+distribution, so you can refer to it there.
+
+You should also document the location from which the source was obtained.
+
+Finally, add your own copyright notice and license information.  You should
+allow your work to be used under the terms of a license that is equivalent to or
+compatible with the terms of the upstream software's copyright license.
+
+Your resulting `copyright` file might look something like this:
+
+    Upstream Source
+    ===============
+    
+    Location: <http://sourceforge.net/projects/expat/files/expat/>
+    
+    Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
+    Copyright 1999, Clark Cooper
+    Copyright 2000, Clark Cooper
+    Copyright (c) 2001-2009 Expat maintainers.
+    
+    These files may be reproduced, distributed, modified, and otherwise dealt in
+    under the terms of the Expat License.
+    
+    On this system, a copy of the Expat License may be found at
+    <file:///usr/share/common-licenses/Expat>.
+    
+    
+    Distribution Packaging
+    ======================
+    
+    Copyright (C) 2012 J. Random Hacker
+    
+    These files may be reproduced, distributed, modified, and otherwise dealt in
+    under the terms of the Expat License.
+    
+    On this system, a copy of the Expat License may be found at
+    <file:///usr/share/common-licenses/Expat>.
+
+Building Everything
+-------------------
+
+Now we can build all of our source and binary packages and verify that
+everything is correct.
+
+**opkbuild**(1) maintains a cache file in the work area; because we've modified
+the metadata in our packaging since the first time we ran **opkbuild**(1), this
+cache file is out-of-date.  Also, we should make sure that the entire build
+process still works.  So let's clean up the work area before going any further.
+
+    $ rm -Rf tmp/
+
+Now let's run **opkbuild**(1) again, this time completely building all of our
+source and binary packages and cleaning up automatically when we're done.
+
+    $ opkbuild
+
+After that finishes, you should see the built packages in the parent directory.
+
+    $ ls -1 ../*.opk
+    ../libexpat.1_2.1.0-2_core-linux-eglibc_all.opk
+    ../libexpat.1-dev_2.1.0-2_core-linux-eglibc_all.opk
+    ../src-expat_2.1.0-2_src_all.opk
+    ../xmlwf_2.1.0-2_core-linux-eglibc_all.opk
+    ../xmlwf-doc_2.1.0-2_all_all.opk
+
+`src-expat` is a *source binary package* – a binary package installable with the
+package manager that provides the files in our source package.  This binary
+package is a convenient way to distribute our source package to others.
+
+You can use the **tar**(1) command to verify that the control information and
+data files in packages look correct.
+
+    $ tar -xzO control.tar.gz \
+    > <../libexpat.1_2.1.0-2_core-linux-eglibc_all.opk | tar -xzO ./control
+    Package: libexpat.1
+    Source: expat
+    Version: 2.1.0-2
+    Architecture: core-linux-eglibc
+    Platform: all
+    Maintainer: "J. Random Hacker" <jrandom@example.com>
+    Installed-Size: 164
+    Description: XML parser library
+     Expat is an XML parser library written in C. It is a stream-oriented parser in
+     which an application registers handlers for things the parser might find in the
+     XML document (like start tags).
+    Homepage: http://expat.sourceforge.net/
+    $ tar -xzO data.tar.gz \
+    > <../libexpat.1_2.1.0-2_core-linux-eglibc_all.opk | tar -tz
+    ./
+    ./usr/
+    ./usr/share/
+    ./usr/share/doc/
+    ./usr/share/doc/libexpat.1/
+    ./usr/share/doc/libexpat.1/changelog.dist
+    ./usr/share/doc/libexpat.1/copyright
+    ./usr/lib/
+    ./usr/lib/core-linux-eglibc/
+    ./usr/lib/core-linux-eglibc/libexpat.so.1
+    ./usr/lib/core-linux-eglibc/libexpat.so.1.6.0
+
+Congratulations!  You've made a source package that successfully builds four
+binary packages!
+
+[spf-docs]: http://specs.proteanos.com/spf-2.0/metadata.html#docs
+[spf-substvars]: http://specs.proteanos.com/spf-2.0/substvars.html
+[deb-expat-copyright]: http://packages.debian.org/changelogs/pool/main/e/expat/current/copyright
+[licensecheck]: http://anonscm.debian.org/gitweb/?p=devscripts/devscripts.git;a=blob;f=scripts/licensecheck.pl;hb=HEAD