From a3c55cc0e374dc7a8598211ec92f2fdebacc8cf4 Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pehjota>
Date: Sun, 18 Nov 2012 16:57:27 -0500
Subject: Add tut sections on <binpkg>.pkg/{control,files}.
---
(limited to 'dev/packaging')
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
--
cgit v0.9.1