Add tut sections on <binpkg>.pkg/{control,files}.

1 files changed, 161 insertions, 0 deletions

diff --git a/dev/packaging/tutorials/basic.mdwn b/dev/packaging/tutorials/basic.mdwn
index 160a9ba..d51190e 100644
--- a/dev/packaging/tutorials/basic.mdwn
+++ b/dev/packaging/tutorials/basic.mdwn
@@ -278,6 +278,165 @@ 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 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 xmlwf xmlwf-doc
+
+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
+
 
 TODO: Finish.
 
@@ -298,3 +457,5 @@ TODO: Finish.
 [no-op]: https://en.wiktionary.org/wiki/no-op
 [spf-work-area]: http://specs.os.libiquity.com/spf-2.0/buildsys.html#work-area
 [posix-colon]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#colon
+[spf-binpkg.pkg]: http://specs.os.libiquity.com/spf-2.0/overview.html#files-binpkg.pkg
+[spf-fields-bin]: http://specs.os.libiquity.com/spf-2.0/fields.html#fields-src