From ab6dd6348e9188e81d9ff68a9a38c1d948e60078 Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pehjota>
Date: Sun, 18 Nov 2012 14:31:29 -0500
Subject: Begin tutorial sections on installing/splitting.

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

diff --git a/dev/packaging/tutorials/basic.mdwn b/dev/packaging/tutorials/basic.mdwn
index fffc27b..bf3b0ee 100644
--- a/dev/packaging/tutorials/basic.mdwn
+++ b/dev/packaging/tutorials/basic.mdwn
@@ -173,9 +173,6 @@ look like this:
     	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.
@@ -185,13 +182,101 @@ 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:
+We can now build Expat.
+
+    $ opkbuild -b -c -T build
+
 
+Installing the Software
+=======================
+
+We can now finish our `build` makefile to install the Expat software and make
+some binary packages.
+
+Installing
+----------
+
+Add a basic `install` target to the `build` makefile.  The makefile should now
+look like this:
+
+    #!/usr/bin/make -f
+    
+    nop:
+    	@:
+    
+    build:
+    	oh-autoconfigure
+    	oh-autobuild
+    	touch $@
+    
     install: build
+    	oh-autoinstall
 
-We can now build Expat.
+The `install` target is declared as depending on the `build` target:
 
-    $ opkbuild -b -c -T build
+    install: build
+
+Install Expat:
+
+    $ opkbuild -b -c -T install
+
+Splitting Files Into Binary Packages
+------------------------------------
+
+Look in the *installation destination directory* `tmp/dest/` for files installed
+by Expat's build system.  This can be done with the **find**(1) command, which
+results in the following when building for the `core-linux-eglibc` architecture:
+
+    $ find tmp/dest -exec ls -Fd '{}' ';' | sed 's|^tmp/dest||'
+    /
+    /usr/
+    /usr/bin/
+    /usr/bin/xmlwf*
+    /usr/share/
+    /usr/share/man/
+    /usr/share/man/man1/
+    /usr/share/man/man1/xmlwf.1
+    /usr/lib/
+    /usr/lib/core-linux-eglibc/
+    /usr/lib/core-linux-eglibc/pkgconfig/
+    /usr/lib/core-linux-eglibc/pkgconfig/expat.pc
+    /usr/lib/core-linux-eglibc/libexpat.so@
+    /usr/lib/core-linux-eglibc/libexpat.a
+    /usr/lib/core-linux-eglibc/libexpat.la*
+    /usr/lib/core-linux-eglibc/libexpat.so.1@
+    /usr/lib/core-linux-eglibc/libexpat.so.1.6.0*
+    /usr/include/
+    /usr/include/expat_external.h
+    /usr/include/expat.h
+
+We have the `libexpat.so.1.6.0` shared library and two symbolic links to it:
+`libexpat.so.1` and `libexpat.so`.  We have the `libexpat.a` static library and
+associated `libexpat.la` library metadata file generated by GNU libtool.  We
+have a pkg-config file and two header files.  We have an executable utility and
+an associated manual page.
+
+We should therefore split these files into four binary packages: one for the
+shared library, one for the library development files, one for the utility, and
+one for the utility's documentation.
+
+To find out what we should call the library package, we can use **objdump**(1)
+to get the *SONAME* of the library:
+
+    $ objdump -p tmp/dest/usr/lib/core-linux-eglibc/libexpat.so.1.6.0 | grep SONAME
+      SONAME               libexpat.so.1
+
+We should name our library package after the SONAME of the shared library,
+without `.so`.  The binary package shall be named **`libexpat.1`**.
+
+The versionless `libexpat.so` link is only needed by **ld**(1) when linking a
+just-compiled object with the `-lexpat` linker flag.  So this can be provided by
+our library development package.  Also provided by that package will be the
+header files, the pkg-config file, and the static library.  The development
+package can be called **`libexpat.1-dev`**.
+
+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`**.
 
 
 TODO: Finish.
--
cgit v0.9.1