summaryrefslogtreecommitdiffstats
path: root/dev/packaging/tutorials
diff options
context:
space:
mode:
authorP. J. McDermott <pehjota>2012-11-18 20:03:43 (EST)
committer P. J. McDermott <pjm@nac.net>2012-11-18 20:03:43 (EST)
commit853a06b6be016bf6ba22de30579b0ae7a108a892 (patch)
treecf6108f9db7399ece878955efd7882d4bd81e392 /dev/packaging/tutorials
parent9ce352059f31135c8e846ed3bd9a19210e5f0e39 (diff)
Add tutorial sections on docs and substvars.
Diffstat (limited to 'dev/packaging/tutorials')
-rw-r--r--dev/packaging/tutorials/basic.mdwn87
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