Improve README and INSTALL files

INSTALL.md

@@ -1,26 +1,11 @@
 Serval DNA Build and Test
 =========================
-
+[Serval Project], March 2013
-To build
---------
-
-In the `serval-dna` directory, run the following commands:
-
-    autoreconf -f -i
-    ./configure
-    make
-
-On Solaris, the system `make` command may not be GNU Make, and the system
-`cc` command may not be GNU Gcc.  The following may work:
-
-    autoreconf -f -i
-    CC=gcc ./configure
-    CC=gcc gmake
 
 Supported Targets
 -----------------
 
-The Serval DNA code successfully builds for the following platforms:
+The [Serval DNA][] code successfully builds for the following platforms:
 
  * Debian Linux, ix86 and x86\_64, kernels 2.6.x and 3.x, [gcc 4.4][] to [gcc 4.7][]
  * [Android 2.2 “Froyo”][], Arm, Linux kernels 2.6.x and 3.x, [gcc 4.4][] supplied as
@@ -28,12 +13,23 @@ The Serval DNA code successfully builds for the following platforms:
  * Mac OS X 10.7 “Lion”, x86\_64, [gcc 4.2][] available in [Xcode 4][] 3.2.6
  * Oracle SunOs 5.10 (Solaris), Sparc, [gcc 4.4][]
 
+Download
+--------
+
+Serval DNA source code is available from the [serval-dna][] repository on
+GitHub:  You can use [Git][] to download the latest version:
+
+    $ cd $HOME/src
+    $ git clone -q git://github.com/servalproject/serval-dna.git
+    $ cd serval-dna
+    $
+
 Dependencies
 ------------
 
 The dependencies for build are expressed in [configure.in](./configure.in).
-Most mandatory dependencies are present by default in a conventional Linux
+Most mandatory dependencies are present in the standard Linux development
-development environment.
+environment.
 
 Mandatory dependencies:
 
@@ -43,6 +39,7 @@ Mandatory dependencies:
  * socket library `libsocket` and headers
  * dynamic link library `libdl` and header `<dlfcn.h>`
  * Native Posix Threads Library `libpthread` and header `<pthread.h>`
+ * Autoconf 2.67 or later
  * on Solaris, the realtime library `librt` (for the `nanosleep()` function)
 
 Optional:
@@ -50,6 +47,57 @@ Optional:
  * Java compiler and SDK (mandatory for Android's **libservald.so**)
  * ALSA sound library and headers (only present on Linux not Android)
 
+Build
+-----
+
+In the `serval-dna` directory, run the following commands:
+
+    $ cd $HOME/src/serval-dna
+    $ autoreconf -f -i
+    $ ./configure
+    $ make
+    $
+
+A successful session should appear something like:
+
+    $ cd $HOME/src/serval-dna
+    $ autoreconf -f -i
+    $ ./configure
+    checking build system type... i686-pc-linux-gnu
+    checking host system type... i686-pc-linux-gnu
+    checking target system type... i686-pc-linux-gnu
+    checking for pkg-config... /usr/bin/pkg-config
+    checking pkg-config is at least version 0.9.0... yes
+    checking for gcc... gcc
+    ...
+    checking for library containing strlcpy... no
+    configure: creating ./config.status
+    config.status: creating Makefile
+    config.status: creating testconfig.sh
+    $ make
+    CC nacl/src/crypto_auth_hmacsha256_ref/hmac.c
+    CC nacl/src/crypto_auth_hmacsha256_ref/verify.c
+    CC nacl/src/crypto_auth_hmacsha512256_ref/hmac.c
+    ...
+    CC xprintf.c
+    LINK servald
+    LINK libmonitorclient.so
+    AR libmonitorclient.a
+    CC tfw_createfile.c
+    LINK tfw_createfile
+    $
+
+On Solaris, the system `make` command may not be GNU Make, and the system
+`cc` command may not be GNU Gcc.  The following may work:
+
+    $ cd $HOME/src/serval-dna
+    $ autoreconf -f -i
+    $ CC=gcc
+    $ export CC
+    $ ./configure
+    $ gmake
+    $
+
 Built artifacts
 ---------------
 
@@ -69,6 +117,44 @@ The build process produces the following artifacts:
   entry points to functions for managing the client end of a monitor connection
   with the servald daemon.
 
+Test scripts
+------------
+
+The scripts in the [tests](./tests/) directory require [Bash][] version 3.2.48
+or later.  To run tests, simply build a native `servald` executable then invoke
+the test script.  Each test case is executed in its own self-contained
+temporary directory with its own set-up and configuration, so there is no need
+to configure anything or clean up afterwards.
+
+For example, the following command runs all the tests except long-running,
+resource-hungry “stress” tests:
+
+    $ ./tests/all
+    1 [PASS.] (logging) By default, only errors and warnings are logged to stderr
+    2 [PASS.] (logging) Configure all messages logged to stderr
+    3 [PASS.] (logging) Configure no messages logged to stderr
+    4 [PASS.] (logging) By Default, all messages are appended to a configured file
+    ...
+    158 [PASS.] (rhizomeprotocol) One way direct pull bundle from configured peer
+    159 [PASS.] (rhizomeprotocol) Two-way direct sync bundles with configured peer
+    160 [PASS.] (directory_service) Publish and retrieve a directory entry
+    161 [PASS.] (directory_service) Ping via relay node
+    161 tests, 161 pass, 0 fail, 0 error
+    $
+
+There are options to run tests concurrently for faster results, and to select
+subsets of test cases.  To see the options, give the `--help` option:
+
+    $ ./tests/all --help
+
+Every test run writes its log files into the [testlog/all](./testlog/all/)
+directory, deleting all logs from the previous run.
+
+Configure
+---------
+
+See [doc/Servald-Configuration](./doc/Servald-Configuration.md).
+
 Voice call test
 ---------------
 
@@ -84,35 +170,39 @@ for performing voice call testing:
 
 The Codec2 source code can be fetched using [Subversion][]:
 
-    svn checkout https://freetel.svn.sourceforge.net/svnroot/freetel/codec2 codec2
+    $ cd $HOME/src
+    $ svn checkout https://freetel.svn.sourceforge.net/svnroot/freetel/codec2 codec2
+    $
 
-The following options can be used to control the `HAVE_VOIPTEST` macro:
+There are command-line options to control the `HAVE_VOIPTEST` macro:
 
- * `./configure --enable-voiptest` will set `HAVE_VOIPTEST` and fail if the
+ * To force `HAVE_VOIPTEST` to be set, and fail if the necessary packages are
-   necessary packages are not present
+   not present, use:
 
- * `./configure --disable-voiptest` will unset `HAVE_VOIPTEST` and will not
+        $ ./configure --enable-voiptest
-   check for presence of the above packages
 
-Test scripts
+ * To force `HAVE_VOIPTEST` to be un-set (and not check for the presence of the
-------------
+   above packages), use:
 
-The scripts in the [tests](./tests/) directory require [Bash][] version 3.2.48
+        $ ./configure --disable-voiptest
-or later.  To run all the tests (except long-running, resource-hungry stress
-tests), build the `servald` executable natively using [GNU make][], then invoke
-them manually:
 
-    ./tests/all
+About the examples
+------------------
 
-There are options to run tests concurrently for faster results, and to select
+The examples in this document are [Bourne shell][] commands, using standard
-subsets of test cases.  To see the options, give the `--help` option:
+quoting and variable expansion.  Commands issued by the user are prefixed with
+the shell prompt `$` to distinguish them from the output of the command.
+Single and double quotes around arguments are part of the shell syntax, so are
+not seen by the command.  Lines ending in backslash `\` continue the command on
+the next line.
 
-    ./tests/all --help
+The directory paths used in the examples are for illustrative purposes only,
-
+and may need to be changed for your particular circumstances.
-The logs of the most recent test run are in the [testlog/all](./testlog/all/)
-directory.
 
 
+[Serval Project]: http://www.servalproject.org/
+[Serval DNA]: ./README.md
+[serval-dna]: https://github.com/servalproject/serval-dna
 [batphone]: https://github.com/servalproject/batphone
 [Android 2.2 “Froyo”]: http://developer.android.com/about/versions/android-2.2-highlights.html
 [Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
@@ -123,4 +213,6 @@ directory.
 [JNI]: http://en.wikipedia.org/wiki/Java_Native_Interface
 [Bash]: http://en.wikipedia.org/wiki/Bash_(Unix_shell)
 [GNU make]: http://www.gnu.org/software/make/
+[Git]: http://git-scm.com/
 [Subversion]: http://subversion.apache.org/
+[Bourne shell]: http://en.wikipedia.org/wiki/Bourne_shell

README.md

@@ -1,5 +1,6 @@
 Serval DNA
 ==========
+[Serval Project][], May 2013
 
 This repository contains the source code for the “core” Serval components
 implemented in [GNU C][]:
@@ -83,8 +84,20 @@ have agreed to the [Serval Project Developer Agreement - Individual][individ],
 and from organisations that have agreed to the [Serval Project Developer
 Agreement - Entity][entity].
 
-servald
+Download, build and test
--------
+------------------------
+
+Instructions for downloading, building and testing Serval DNA are in
+[INSTALL.md](./INSTALL.md).  (If that link is does not work, try
+[INSTALL.md](/servalproject/serval-dna/blob/master/INSTALL.md).)
+
+Configure
+---------
+
+See [doc/Servald-Configuration](./doc/Servald-Configuration.md).
+
+More information
+----------------
 
 The **servald** executable is a multi-purpose program designed to be invoked
 directly from the command line and also via [JNI][] from within a Java program.
@@ -97,16 +110,9 @@ Some operations are self-contained, some start and stop the servald daemon
 process, some communicate with the servald daemon as an MDP client, and others
 via a two-way [pipe][] called the monitor interface.
 
-For more detail on the purpose and usage of the servald command-line, see the
+For more documentation, see the
 [doc](/servalproject/serval-dna/tree/master/doc/) directory.
 
-Build and test
---------------
-
-Instructions for building and testing Serval DNA are in
-[INSTALL.md](./INSTALL.md).  (If that link is does not work, try
-[INSTALL.md](/servalproject/serval-dna/blob/master/INSTALL.md).)
-
 
 [Serval Project]: http://www.servalproject.org/
 [SPI]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:spi