diff options
Diffstat (limited to 'dev')
| -rw-r--r-- | dev/packaging/tutorials/basic.mdwn | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/dev/packaging/tutorials/basic.mdwn b/dev/packaging/tutorials/basic.mdwn index fc2ec65..4852908 100644 --- a/dev/packaging/tutorials/basic.mdwn +++ b/dev/packaging/tutorials/basic.mdwn @@ -496,6 +496,91 @@ So our `build` makefile should now look like this: oh-installfiles +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. + + TODO: Finish. @@ -517,3 +602,5 @@ TODO: Finish. [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 +[spf-docs]: http://specs.os.libiquity.com/spf-2.0/metadata.html#docs +[spf-substvars]: http://specs.os.libiquity.com/spf-2.0/substvars.html |