summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorP. J. McDermott <pehjota>2012-11-18 12:50:09 (EST)
committer P. J. McDermott <pjm@nac.net>2012-11-18 12:50:09 (EST)
commit389182014e2fd12d87a3b676354a7c8ce8ed259f (patch)
tree64cb9e10b90b11471c3bfc69e8084f0786d34c12
parentec182f03464037ef91e5371c7622f24f724c655a (diff)
Add to packaging tutorial a section on building.
-rw-r--r--dev/packaging/tutorials/basic.mdwn97
1 files changed, 97 insertions, 0 deletions
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