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