Improved the documentation of directory variables.

3 files changed, 168 insertions, 97 deletions

diff --git a/comfignat.gpr.gp b/comfignat.gpr.gp
index 132947c..545352b 100644
--- a/comfignat.gpr.gp
+++ b/comfignat.gpr.gp
@@ -1,5 +1,5 @@
 -- Comfignat configuration variables for GNAT project files
--- Copyright 2013 - 2014 B. Persson, Bjorn@Rombobeorn.se
+-- Copyright 2013 - 2015 B. Persson, Bjorn@Rombobeorn.se
 --
 -- This material is provided as is, with absolutely no warranty expressed
 -- or implied. Any use is at your own risk.
@@ -84,7 +84,7 @@ abstract project Comfignat is
 
    -- Programs that can be run from a command prompt are in Bindir. This is
    -- usually the same directory that the program itself is in, so this
-   -- variable is probably useful only to programs in Libexecdir.
+   -- variable is probably useful only to programs under Libexecdir.
    #if Bindir'Defined then
       Bindir := $Bindir;
    #else
@@ -272,8 +272,9 @@ abstract project Comfignat is
       Stage_Bindir := Stagedir & Bindir;
    #end if;
 
-   -- Programs that are only to be run by other programs, not by users, shall
-   -- be installed under Stage_Libexecdir.
+   -- Programs that are only intended to be run by other programs, not by
+   -- users, shall be installed under an application-specific subdirectory of
+   -- Stage_Libexecdir.
    #if Stage_Libexecdir'Defined then
       Stage_Libexecdir := $Stage_Libexecdir;
    #else
diff --git a/comfignat.mk b/comfignat.mk
index 9d6badc..6c3176e 100644
--- a/comfignat.mk
+++ b/comfignat.mk
@@ -1,5 +1,5 @@
 # Comfignat makefile foundation for configuring and building GNAT projects
-# Copyright 2013 - 2014 B. Persson, Bjorn@Rombobeorn.se
+# Copyright 2013 - 2015 B. Persson, Bjorn@Rombobeorn.se
 #
 # This material is provided as is, with absolutely no warranty expressed
 # or implied. Any use is at your own risk.
@@ -263,7 +263,8 @@ preprocess_file = "${GNATPREP}" ${firstword ${filter %.gp,$^}} $@ \
 # preprocess_file is a command for use in recipes. It runs the first .gp file
 # among the rule's prerequisites through Gnatprep to produce the target. If the
 # target is a usage project, then the usage-relevant directory variables are
-# conveyed to it as Gnatprep symbols. Otherwise srcdir is conveyed.
+# conveyed to it as Gnatprep symbols. Otherwise srcdir is conveyed, as it's
+# needed by preprocessed build projects.
 
 build_GPR = "${GNAT_BUILDER}" -P ${firstword ${filter %.gpr,$^}} \
             ${addprefix -aP,${VPATH}} -p \
@@ -424,7 +425,8 @@ usage_directory_variables = includedir archincludedir libdir alidir
 
 builder_directory_variables = bindir libexecdir ${usage_directory_variables}
 # These are the builder-relevant directory variables. They control where the
-# GNAT tools write files to be installed.
+# GNAT tools write files to be installed. These are the variables that
+# Comfignat-compatible directories projects must provide.
 
 usage_relevant = ${filter ${usage_directory_variables},${1}}
 # usage_relevant returns a list of the words in the input list that are usage-
diff --git a/manual.en.html b/manual.en.html
index 86eb33d..a03beba 100755
--- a/manual.en.html
+++ b/manual.en.html
@@ -112,7 +112,7 @@ and is also browsable
 
 <p>The following applies to all of Comfignat including this document:</p>
 
-<p>Copyright 2013 - 2014 Björn Persson, Bjorn@Rombobjörn.se</p>
+<p>Copyright 2013 - 2015 Björn Persson, Bjorn@Rombobjörn.se</p>
 
 <p>This material is provided as is, with absolutely no warranty expressed
 or implied. Any use is at your own risk.</p>
@@ -140,10 +140,9 @@ that the project <var>Comfignat</var> defines.</p>
   <li><p>Use <var>Comfignat.Objdir</var> for <var>Object_Dir</var>.</p></li>
 
   <li><p>If your project file builds a program, then use
-  <var>Comfignat.Stage_Bindir</var> for <var>Exec_Dir</var>, unless the program
-  is only intended to be executed by other programs and not run manually from a
-  command prompt, in which case it should be placed under
-  <var>Comfignat.Stage_Libexecdir</var>.</p></li>
+  <var>Comfignat.Stage_Bindir</var> for <var>Exec_Dir</var> (or,
+  <a href="#where_programs">in some cases</a>, a subdirectory of
+  <var>Comfignat.Stage_Libexecdir</var>).</p></li>
 
   <li><p>If your project file builds a library, then use a subdirectory of
   <var>Comfignat.Stage_Includedir</var> for <var>Library_Src_Dir</var>,
@@ -213,86 +212,71 @@ usage_GPRs = example.gpr</pre></div>
 
 <h2 id="howto">How to Use Comfignat</h2>
 
-<h3 id="where">Where to Place Files</h3>
+<h3 id="directory_variables">Directory Variables</h3>
 
 <p>During the build, the files that will be installed are collected in a
 directory structure under a staging directory whose name is held in the
 variable <var>stagedir</var>. In the installation step that whole directory
 structure is copied to the directory specified in <var>DESTDIR</var>, or to the
-root directory if <var>DESTDIR</var> is empty. Compiled programs, libraries,
-ALI files and needed library sources are written to the staging directory by
-the GNAT tools if the build-controlling project files are written correctly.
-Comfignat automatically stages usage project files. To get other files
-installed, the makefile needs to either copy them to the appropriate directory
-under the staging directory, or instruct the tools that generate those files to
-write them there.</p>
-
-<p>Comfignat defines several directory variables to allow distributions and
-installing users to control where in the filesystem different kinds of files
-get installed and where applications write their files at run time. Variables
-whose names begin with “<var>stage_</var>” point to the directories under the
-staging directory where the files shall be written during the build. Variables
-without the “<var>stage_</var>” prefix tell where the files will be in the
-target system after installation, and are suitable for embedding in programs
-where the directory names are needed at run time, and in usage project
-files.</p>
-
-<p>Directory variables are available as Make variables to makefiles that
-include <var>comfignat.mk</var>, as GNAT project variables to build project
-files that import <var>comfignat.gpr</var>, and as preprocessor symbols to
-usage project files that are preprocessed with Gnatprep. If the Make variable
-<var>relocatable_package</var> is set to “<samp>true</samp>” on the command
-line, then the variables for embedding will be relative to <var>bindir</var> in
-build project files, and relative to <var>gprdir</var> in usage project
-files, except that <var>bindir</var> will instead be relative to
-<var>libexecdir</var>, and <var>runstatedir</var> and <var>lockdir</var> are
-always absolute.</p>
+root directory if <var>DESTDIR</var> is empty.</p>
+
+<p>Comfignat defines several directory variables that control where in the
+target filesystem different kinds of files will get installed and where
+applications write their files at run time. Distributions and installing users
+are expected to override these variables according to their filesystem layout.
+They are available as Make variables to makefiles that include
+<var>comfignat.mk</var>, as GNAT project variables to build project files that
+import <var>comfignat.gpr</var>, and as preprocessor symbols to usage project
+files that are preprocessed with Gnatprep. The build project variables are
+suitable for embedding in programs where the directory names are needed at run
+time. In project files most of these variables are relative pathnames when a
+<a href="#relocatable">relocatable package</a> is built. Otherwise they are
+absolute. In makefiles they are always absolute.</p>
+
+<p>Another set of directory variables, which are derived from the first set but
+have the prefix “<var>stage_</var>” in their names, specify the directories
+under the staging directory where the files shall be written during the build.
+These variables are available to makefiles and build project files. Build
+projects shall use them in the attributes that control where generated files
+are placed. They are always absolute pathnames.</p>
+
+<p>A third set, with the prefix “<var>Make_</var>”, are relative versions of
+the staging directory variables. These are meant for use in Make targets,
+prerequisites and other places where Make expects space-separated lists. This
+mitigates the problem that Make has with spaces in filenames. Using a relative
+pathname hides the pathname of the parent directory from Make so that spaces
+in that part of the pathname don't cause Make to read it as a list of multiple
+filenames. (In recipes it's usually possible to use quotes around a pathname to
+ensure that it won't be read as a space-separated list, so there the
+“<var>stage_</var>” variables should work.) These variables are only available
+to makefiles.</p>
+
+<p>The directory <var>objdir</var> is meant for intermediate files, and
+<var>srcdir</var> and <var>builddir</var> are used to support
+<a href="#build_directories">separate build directories</a>. For Make targets
+and prerequisites there are <var>Make_stagedir</var>, <var>Make_objdir</var>,
+<var>Make_srcdir</var> and <var>Make_builddir</var></p>
+
+<h4 id="where">Where to Place Files</h4>
+
+<h5 id="where_programs">Programs</h5>
 
 <ul>
 <li><p>Programs that can be run from a command prompt shall be placed in
-<var>stage_bindir</var>. Build project files shall use
-<var>Comfignat.Stage_Bindir</var>.</p></li>
+<var>Comfignat.Stage_Bindir</var> by build project files. Any executable files
+that aren't built with GNAT tools shall be placed in <var>stage_bindir</var> by
+makefiles.</p></li>
 
 <li><p>Programs that are only to be run by other programs, not by users, shall
-be placed under <var>stage_libexecdir</var>,
-<var>Comfignat.Stage_Libexecdir</var> in build project files. If there are
-several such programs they should probably be under a separate subdirectory.
-Programs that need to invoke such programs shall have
-<var>Comfignat.Libexecdir</var> compiled in.</p></li>
-
-<li><p>Idiosyncratic read-only architecture-independent data files shall be
-placed under a separate subdirectory of <var>stage_datadir</var>. Programs
-shall look for them under <var>Comfignat.Datadir</var>.</p></li>
-
-<li><p>Configuration files – host-specific data files that aren't modified in
-the normal course of their use but may be modified by system administrators –
-shall be placed under <var>stage_sysconfdir</var>. If there are several they
-should probably be under a separate subdirectory. Programs shall look for them
-under <var>Comfignat.Sysconfdir</var>.</p></li>
-
-<li><p>Idiosyncratic variable data files shall be placed under a separate
-subdirectory of <var>stage_statedir</var>. Programs shall read and write them
-under <var>Comfignat.Statedir</var>.</p></li>
-
-<li><p>If your program keeps cached data files that it can regenerate if they
-are deleted, then those files shall be kept under a separate subdirectory of
-<var>Comfignat.Cachedir</var>. You won't install cached files but you may want
-to create the subdirectory under <var>stage_cachedir</var>.</p></li>
+be placed under a separate subdirectory of
+<var>Comfignat.Stage_Libexecdir</var> by build project files – or under
+<var>stage_libexecdir</var> by makefiles. Programs that need to invoke such
+programs shall have <var>Comfignat.Libexecdir</var> compiled in.</p></li>
+</ul>
 
-<li><p>Log files shall be written under <var>Comfignat.Logdir</var>. You won't
-install log files but you may want to create a separate subdirectory under
-<var>stage_logdir</var> if your program writes its own log files.</p></li>
-
-<li><p>Small files that take part in describing the state of the system and
-that exist only while the program is running, such as process identifier files
-and transient Unix-domain sockets, shall be sought and created under
-<var>Comfignat.Runstatedir</var>. (This is <strong>not</strong> the place for
-temporary files in general.)</p></li>
-
-<li><p>Lock files that are used to prevent multiple programs from trying to
-access a device or other resource at the same time shall be sought and created
-under <var>Comfignat.Lockdir</var>.</p></li>
+<h5 id="where_libraries">Libraries</h5>
 
+<ul>
 <li><p>Ada specifications, C headers and other source files that are needed for
 compilation of other software that uses your libraries shall be placed under
 <var>Comfignat.Stage_Includedir</var> by build project files, usually under a
@@ -323,12 +307,44 @@ subdirectory that ALI files are placed in when
 <var>alidir</var> = <var>libdir</var>.) Programs shall look for them under
 <var>Comfignat.Libdir</var>.</p></li>
 
-<li><p>Comfignat puts usage project files in <var>stage_gprdir</var>.</p></li>
+<li><p>Comfignat automatically puts usage project files in
+<var>stage_gprdir</var>.</p></li>
+</ul>
+
+<h5 id="where_data">Data</h5>
+
+<ul>
+<li><p>Idiosyncratic read-only architecture-independent data files shall be
+placed under a separate subdirectory of <var>stage_datadir</var>. Programs
+shall look for them under <var>Comfignat.Datadir</var>.</p></li>
 
 <li><p>Locale-specific message catalogs shall be placed in the appropriate
 subdirectories under <var>stage_localedir</var>. Programs shall look for them
 under <var>Comfignat.Localedir</var>.</p></li>
 
+<li><p>Configuration files – host-specific data files that aren't modified in
+the normal course of their use but may be modified by system administrators –
+shall be placed under <var>stage_sysconfdir</var>. If there are several they
+should probably be under a separate subdirectory. Programs shall look for them
+under <var>Comfignat.Sysconfdir</var>.</p></li>
+
+<li><p>Idiosyncratic variable data files shall be placed under a separate
+subdirectory of <var>stage_statedir</var>. Programs shall read and write them
+under <var>Comfignat.Statedir</var>.</p></li>
+
+<li><p>If your program keeps cached data files that it can regenerate if they
+are deleted, then those files shall be kept under a separate subdirectory of
+<var>Comfignat.Cachedir</var>. You won't install cached files but you may want
+to create the subdirectory under <var>stage_cachedir</var>.</p></li>
+
+<li><p>Log files shall be written under <var>Comfignat.Logdir</var>. You won't
+install log files but you may want to create a separate subdirectory under
+<var>stage_logdir</var> if your program writes its own log files.</p></li>
+</ul>
+
+<h5 id="where_documentation">Documentation</h5>
+
+<ul>
 <li><p>Documentation in the Man format shall be placed in the appropriate
 subdirectories under <var>stage_mandir</var>.</p></li>
 
@@ -339,6 +355,30 @@ subdirectories under <var>stage_mandir</var>.</p></li>
 <var>stage_miscdocdir</var>.</p></li>
 </ul>
 
+<h5 id="where_system">System State</h5>
+
+<ul>
+<li><p>Small files that take part in describing the state of the system and
+that exist only while the program is running, such as process identifier files
+and transient Unix-domain sockets, shall be sought and created under
+<var>Comfignat.Runstatedir</var>. (This is <strong>not</strong> the place for
+temporary files in general.)</p></li>
+
+<li><p>Lock files that are used to prevent multiple programs from trying to
+access a device or other resource at the same time shall be sought and created
+under <var>Comfignat.Lockdir</var>.</p></li>
+</ul>
+
+<h5 id="where_intermediate">Intermediate Files</h5>
+
+<ul>
+<li><p>It is recommended to keep intermediate files in <var>objdir</var>. Then
+Comfignat automatically knows how to delete them in
+<a href="#target_clean">“<samp>make clean</samp>”</a>. Build project files
+shall use <var>Comfignat.Objdir</var> for <var>Object_Dir</var>. Makefiles may
+use <var>Make_objdir</var>.</p></li>
+</ul>
+
 <h3 id="directories_projects">Directories Projects</h3>
 
 <p>A directories project is a GNAT project file that defines directory
@@ -360,8 +400,9 @@ target architecture.</dd>
 <dd>The directory for programs that can be run from a command prompt.</dd>
 
 <dt><var>Libexecdir</var></dt>
-<dd>The top-level directory for programs that are intended to be run by other
-programs rather than by users.</dd>
+<dd>The parent of applications' separate application-specific directories for
+programs that are intended to be run by other programs rather than by
+users.</dd>
 
 <dt><var>Includedir</var></dt>
 <dd>The top-level directory for (normally architecture-independent) source
@@ -437,6 +478,33 @@ atomic_doodads = true</pre>
 symbols to preprocessed files and as external variables to build project
 files.</p>
 
+<h3 id="relocatable">Relocatable Packages</h3>
+
+<p>A relocatable software package is a directory tree with programs and/or
+libraries that can be installed anywhere in a filesystem and function from
+there without recompilation. Such software can't use embedded absolute
+pathnames to refer to files in the package. Pathnames embedded in the files
+must be relative to some directory in the relocatable package.</p>
+
+<p>If the Make variable <var>relocatable_package</var> is set to
+“<samp>true</samp>” on the command line, then Comfignat will use relative
+pathnames in preprocessor symbols and GNAT project variables for embedding. In
+usage project files the pathnames will be relative to <var>gprdir</var> so that
+the project file will reference the right directories regardless of how the
+package is relocated (as long as the package is moved as a whole and not
+rearranged internally). In build project files most directory variables will be
+relative to <var>bindir</var>. Provided that a program can find out the
+pathname of its own executable file, it can get <var>bindir</var> as the
+directory part of that, and then find the other directories relative to that
+directory. <var>bindir</var> will instead be relative to <var>libexecdir</var>
+so that a helper program in <var>libexecdir</var> can find <var>bindir</var>
+and then find the other directories from there.</p>
+
+<p>Only <var>runstatedir</var> and <var>lockdir</var> are always absolute
+pathnames. Those directories belong to the operating system and are used for
+communication between subsystems. It wouldn't make sense for an application to
+have its own <var>runstatedir</var>.</p>
+
 <h3 id="build_tools">Build Tools and their Arguments</h3>
 
 <p>There are several options variables that let installing users and
@@ -548,7 +616,7 @@ directory and its ancestors. Just specify the directory as an order-only
 prerequisite and be sure to append a slash. This rule ensures that the
 directory <var>data</var> exists before the file <var>db</var> is written:</p>
 
-<pre class="example make">${stage_statedir}/example/data/db: | ${stage_statedir}/example/data/
+<pre class="example make">${Make_statedir}/example/data/db: | ${Make_statedir}/example/data/
 	echo stuff > $@</pre>
 
 <h3 id="targets">Make Targets</h3>
@@ -556,7 +624,7 @@ directory <var>data</var> exists before the file <var>db</var> is written:</p>
 <p>These phony targets are defined in <var>comfignat.mk</var>:</p>
 
 <dl>
-<dt><var>build</var></dt>
+<dt id="target_build"><var>build</var></dt>
 <dd><p>This is what a plain “<samp>make</samp>” will do (unless your makefile
 defines some other target before it includes <var>comfignat.mk</var>). By
 default it builds and stages the build projects that are listed in
@@ -567,7 +635,7 @@ example documentation:</p>
 
 <pre class="example make">build: man html pdf</pre></dd>
 
-<dt><var>install</var></dt>
+<dt id="target_install"><var>install</var></dt>
 <dd><p>If a user unpacks a source package and immediately runs
 “<samp>make install</samp>”, then the <var>build</var> target is built and then
 installed. If some files have already been staged in the staging directory,
@@ -575,7 +643,7 @@ then “<samp>make install</samp>” doesn't rebuild anything but just copies th
 staged directory structure to the directory specified in <var>DESTDIR</var>, or
 to the root directory if <var>DESTDIR</var> is empty.</p></dd>
 
-<dt><var>all</var></dt>
+<dt id="target_all"><var>all</var></dt>
 <dd><p>By default <var>all</var> is the same as <var>build</var>, but you may
 add additional prerequisites to it if you have optional components that
 shouldn't be built by default. Such targets will be built by
@@ -583,18 +651,18 @@ shouldn't be built by default. Such targets will be built by
 
 <pre class="example make">all: demo_programs auxiliary_tools</pre></dd>
 
-<dt><var>base</var></dt>
+<dt id="target_base"><var>base</var></dt>
 <dd><p>This builds and stages the build projects that are listed in
 <var>build_GPRs</var>, but does not do everything that <var>build</var> does.
 It can be used to bypass targets that you don't want to rebuild all the time
 when you're programming. Any targets that you do want to rebuild every time may
 be added as prerequisites.</p></dd>
 
-<dt><var>preprocess</var></dt>
+<dt id="target_preprocess"><var>preprocess</var></dt>
 <dd><p>This preprocesses files that need to be preprocessed before projects are
 built.</p></dd>
 
-<dt><var>postinstall</var></dt>
+<dt id="target_postinstall"><var>postinstall</var></dt>
 <dd><p>You may add a recipe to <var>postinstall</var> if there are commands
 that need to be run on the target system after the files have been installed.
 This will typically be commands that modify existing files on the target
@@ -605,19 +673,19 @@ run on the target system, not on a build server. Installing users can override
 this default behaviour by setting <var>do_postinstall</var> to
 “<samp>true</samp>” or “<samp>false</samp>”.</p></dd>
 
-<dt><var>preinstall</var></dt>
+<dt id="target_preinstall"><var>preinstall</var></dt>
 <dd><p>This is like <var>postinstall</var> except that it's run before the
 files are installed, not after. Installing users can control it with
 <var>do_preinstall</var>.</p></dd>
 
-<dt><var>install_files</var></dt>
+<dt id="target_install_files"><var>install_files</var></dt>
 <dd><p>You may add a recipe to <var>install_files</var> if any files have to be
 written, deleted or moved after the staged directory tree has been copied.
 Avoid using this if possible. It's better to stage all the files correctly
 under the staging directory in the build phase, but this hook exists if you
 really need it for some workaround.</p></dd>
 
-<dt><var>configure</var></dt>
+<dt id="target_configure"><var>configure</var></dt>
 <dd><p>“<samp>make configure</samp>” is used to set values in the
 <a href="#configuration">persistent configuration</a> and to set up a
 <a href="#build_directories">separate build directory</a>. This is a
@@ -625,25 +693,25 @@ double-colon rule so you can add your own <var>configure</var> recipe in case
 you need to configure things that can't easily be expressed as Make
 variables.</p></dd>
 
-<dt><var>show_configuration</var></dt>
+<dt id="target_show_configuration"><var>show_configuration</var></dt>
 <dd><p>“<samp>make show_configuration</samp>” outputs the configured variables
 in the <a href="#configuration">persistent configuration</a>. This is a
 double-colon rule so you can add your own <var>show_configuration</var> recipe
 to accompany your own <var>configure</var> recipe.</p></dd>
 
-<dt><var>unconfigure</var></dt>
+<dt id="target_unconfigure"><var>unconfigure</var></dt>
 <dd><p>This deletes the configuration file that “<samp>make configure</samp>”
 writes. This is a double-colon rule. If you add your own <var>configure</var>
 recipe that writes additional configuration files, then you should also add an
 <var>unconfigure</var> recipe to delete those files.</p></dd>
 
-<dt><var>clean</var></dt>
+<dt id="target_clean"><var>clean</var></dt>
 <dd><p>This deletes all files that are normally created by building the
 software, but preserves the configuration. It's a double-colon rule so you can
 add your own <var>clean</var> recipe to delete files that your recipes
 generate.</p></dd>
 
-<dt><var>distclean</var></dt>
+<dt id="target_distclean"><var>distclean</var></dt>
 <dd><p>This deletes all files that are normally created by configuring or
 building the software. In an unpacked source tree where builds have been done
 but no other files have been created, “<samp>make distclean</samp>” leaves only