From 389182014e2fd12d87a3b676354a7c8ce8ed259f Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pehjota>
Date: Sun, 18 Nov 2012 12:50:09 -0500
Subject: Add to packaging tutorial a section on building.

---
(limited to 'dev/packaging/tutorials')

diff --git a/dev/packaging/tutorials/basic.mdwn b/dev/packaging/tutorials/basic.mdwn
index f8a3ee9..263fd0d 100644
--- a/dev/packaging/tutorials/basic.mdwn
+++ b/dev/packaging/tutorials/basic.mdwn
@@ -97,8 +97,101 @@ Our expat `changelog` file looks like this:
     
      -- "J. Random Hacker" <jrandom@example.com>  Sun, 18 Nov 2012 11:58:19 -0500
 
+
+Building the Software
+=====================
+
+We can now write our `build` makefile to try to get the Expat software to build.
+[The `build` makefile][spf-build] "directs the process of building and
+installing data files to be provided by binary packages".
+
+Looking Through the Source
+--------------------------
+
+With a ["no-op"][no-op] target in `build`, we can make **opkbuild**(1) prepare a
+[work area][spf-work-area] with the unpacked source code and stop.  So begin
+writing `build` as follows:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+
+Note that, due to makefile syntax, the line after `nop:` must begin with a tab
+character.  This line is called a "command line" in makefile syntax.  The [`:`
+utility][posix-colon] is a "null utility" that returns an exit status of zero.
+A command prefix of `@` tells make to not write the command to standard output
+before executing it.
+
+The `build` makefile must be executable, so set its file mode:
+
+    $ chmod 755 build
+
+We can now make **opkbuild**(1) prepare our build work area.
+
+    $ opkbuild -b -c -T nop
+
+The options are explained in the help output of opkbuild, obtained by running
+`opkbuild -h`.  The `-b` option tells **opkbuild**(1) to build only binary
+packages (no source package).  The `-c` option tells it to not clean up the work
+area after building packages.  The `-T` option specifies a target to be built
+instead of the standard `build` and `install` targets.
+
+Now look in `tmp/src/`, the location of the source code within the build work
+area.
+
+    $ ls tmp/src/
+
+Look for some documentation file that might tell us how to build Expat.  This
+kind of information is usually kept in a file called `INSTALL` or `README`.
+Expat's `README` file says to run `./configure`, then `make` and `make install`.
+
+Looking at `tmp/src/configure`, we see that it is "[g]enerated by GNU Autoconf
+2.68 for expat 2.1.0".  The `tmp/src/README` file reports that the makefile
+supports the use of either the `DESTDIR` or `INSTALL_ROOT` macro to install
+Expat somewhere other than in the root of the filesystem.  So, we should be able
+to use opkhelper's buildsystem utilities to automatically configure, build, and
+install Expat for us.
+
+Building
+--------
+
+So let's add a `build` target to our `build` makefile.  The makefile should now
+look like this:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+    
+    build:
+    	oh-autoconfigure
+    	oh-autobuild
+    	touch $@
+    
+    install: build
+    	oh-autoinstall
+
+Read the manual pages and/or source code of **oh-autoconfigure**(1),
+**oh-autobuild**(1), and **oh-autoinstall**(1) to learn more about what they do.
+
+The `touch $@` command is recommended by SPF 2.0:
+
+> The build target should create a file named build in the build work area to
+> prevent configuration and compilation from being performed multiple times.
+
+The `install` target is declared as depending on the `build` target:
+
+    install: build
+
+We can now build Expat.
+
+    $ opkbuild -b -c -T build
+
+
 TODO: Finish.
 
+
 [opkbuild]: http://git.os.libiquity.com/opkbuild/opkbuild.git/
 [spf]: http://specs.os.libiquity.com/spf-2.0/
 [opkhelper]: http://git.os.libiquity.com/opkhelper/opkhelper.git/
@@ -111,3 +204,7 @@ TODO: Finish.
 [spf-fields-src]: http://specs.os.libiquity.com/spf-2.0/fields.html#fields-src
 [rfc-5322-3.4]: https://tools.ietf.org/html/rfc5322#section-3.4
 [spf-changelog]: http://specs.os.libiquity.com/spf-2.0/metadata.html#changelog
+[spf-build]: http://specs.os.libiquity.com/spf-2.0/buildsys.html#build
+[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
--
cgit v0.9.1