# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1660315353 -7200
# Node ID dce34ff1ba5226731115f2f676275cc7e5c9c210
# Parent  300aef88597b056c269e7b59295e9904690f836c
Expanded the documentation, also changing various stylistic conventions.

diff -r 300aef88597b -r dce34ff1ba52 README.txt
--- a/README.txt	Fri Aug 12 16:41:47 2022 +0200
+++ b/README.txt	Fri Aug 12 16:42:33 2022 +0200
@@ -1,5 +1,5 @@
-Departure
-=========
+Introduction
+============
 
 This is a collection of L4Re packages for providing and using filesystems and
 related components.
@@ -7,12 +7,37 @@
 This directory (departure) should be installed within the pkg directory in the
 L4Re distribution.
 
-Building Fiasco and L4Re
-------------------------
+Prerequisites
+=============
+
+This software requires some other software to be useful:
+
+ * The Fiasco.OC microkernel and L4Re distribution
+ * The idl4re distribution
+
+Obtaining and Building idl4re
+=============================
+
+The idl4re distribution provides a tool called idl that generates source files
+from interface descriptions. It can be obtained as follows:
+
+hg clone https://hg.boddie.org.uk/L4Re/idl4re
 
-Although this is generally documented, the concise instructions for building
-the software have not been preserved in the L4Re distribution, requiring the
-perusal of online resources. For example:
+The software can be built as follows:
+
+cd idl4re
+make
+
+When building the Departure software within the L4Re build system, the idl4re
+directory will need to be present in the appropriate location, this being
+inside the l4 directory. See below for more details.
+
+Obtaining and Building Fiasco.OC and L4Re
+=========================================
+
+Although the build processes for Fiasco.OC and L4Re are generally documented,
+the concise instructions for building the software have not been preserved in
+the L4Re distribution, requiring the perusal of online resources. For example:
 
 https://github.com/kernkonzept/manifest/wiki/BUILDING
 
@@ -29,7 +54,7 @@
 cd ham
 make
 
-Returning to the parent directory, the Fiasco and L4Re distributions can be
+Returning to the parent directory, the Fiasco.OC and L4Re distributions can be
 obtained as follows:
 
 ham/ham init -u https://github.com/kernkonzept/manifest.git
@@ -40,8 +65,8 @@
 particular location and for the specific purpose of downloading the remaining
 software of interest.)
 
-Here is a quick summary of the build process for Fiasco starting at the parent
-directory of the Fiasco and L4Re distributions:
+Here is a quick summary of the build process for Fiasco.OC starting at the
+parent directory of the Fiasco.OC and L4Re distributions:
 
 cd fiasco
 make BUILDDIR=mybuild
@@ -53,10 +78,11 @@
 parameter to parallelise the build.
 
 At this point, this directory (departure) can be copied into the L4Re
-distribution within the pkg directory.
+distribution within the pkg directory. Also, the idl4re distribution should be
+made available within the l4 directory itself.
 
 Here is a quick summary of the build process for L4Re, also starting at the
-parent directory of the Fiasco and L4Re distributions:
+parent directory of the Fiasco.OC and L4Re distributions:
 
 cd l4
 make B=mybuild
@@ -71,11 +97,18 @@
 by this distribution if it has been copied into the pkg/departure location
 within the l4 directory.
 
-Running Programs from this Distribution
----------------------------------------
+Defining the L4Re Configuration
+===============================
 
-To make the test programs available to L4Re, add the following line to the
-L4Re conf/Makeconf.boot file:
+An example configuration file is provided as conf/Makeconf.boot within this
+distribution. Where no such existing file has been deployed, this example file
+can be copied into a suitable location from within the l4 directory as
+follows:
+
+cp pkg/departure/conf/Makeconf.boot conf/Makeconf.boot
+
+Otherwise, with an existing conf/Makeconf.boot file, to make the test programs
+available to L4Re, add the following line to such a file:
 
 MODULE_SEARCH_PATH += $(L4DIR_ABS)/pkg/departure/conf
 
@@ -86,7 +119,22 @@
 This removes any need to copy program configuration files and associated
 resources to the L4Re distribution itself.
 
+Defining the Module Lists
+=========================
+
 The program module lists in the conf subdirectory can either be appended to
 the L4Re conf/modules.list file, or a specific .list file can be copied to the
 conf/modules.list location (potentially after taking a backup copy of the
-original file).
+original file). For example, from within the l4 directory:
+
+cp conf/modules.list conf/modules.list.orig
+cp pkg/departure/conf/dstest_test.list conf/modules.list
+
+Running Programs from this Distribution
+=======================================
+
+With configuration measures in place, a program can be run in QEMU as follows:
+
+make O=mybuild qemu E=dstest_test
+
+The particular program used above is a short concurrency test.