Added switch variables.

2 files changed, 141 insertions, 21 deletions

diff --git a/comfignat.gpr.gp b/comfignat.gpr.gp
index ebfd724..3061c2b 100644
--- a/comfignat.gpr.gp
+++ b/comfignat.gpr.gp
@@ -229,6 +229,39 @@ abstract project Comfignat is
 
 
    --
+   -- The following variables are convenient to use in Compiler'Switches or
+   -- Compiler'Default_Switches in project files.
+   --
+   -- There are no switch variables for:
+   -- · Unitdir, Userunitdir and GPRdir: A program working on such files would
+   --   need to use a search path, not just one directory.
+   -- · Includedir, Archincludedir and Alidir: Libraries have those pathnames
+   --   in usage project files. There doesn't seem to be a usecase for
+   --   compiling them into binaries.
+
+   Bindir_Switch         := "-gnateDBindir="""         & Bindir         & """";
+   Libexecdir_Switch     := "-gnateDLibexecdir="""     & Libexecdir     & """";
+   Datadir_Switch        := "-gnateDDatadir="""        & Datadir        & """";
+   Sysconfdir_Switch     := "-gnateDSysconfdir="""     & Sysconfdir     & """";
+   Statedir_Switch       := "-gnateDStatedir="""       & Statedir       & """";
+   Cachedir_Switch       := "-gnateDCachedir="""       & Cachedir       & """";
+   Logdir_Switch         := "-gnateDLogdir="""         & Logdir         & """";
+   Runstatedir_Switch    := "-gnateDRunstatedir="""    & Runstatedir    & """";
+   Lockdir_Switch        := "-gnateDLockdir="""        & Lockdir        & """";
+   Libdir_Switch         := "-gnateDLibdir="""         & Libdir         & """";
+   Localedir_Switch      := "-gnateDLocaledir="""      & Localedir      & """";
+   Mandir_Switch         := "-gnateDMandir="""         & Mandir         & """";
+   Infodir_Switch        := "-gnateDInfodir="""        & Infodir        & """";
+   Miscdocdir_Switch     := "-gnateDMiscdocdir="""     & Miscdocdir     & """";
+
+   All_Dir_Switches :=
+      (Bindir_Switch, Libexecdir_Switch, Datadir_Switch, Sysconfdir_Switch,
+       Statedir_Switch, Cachedir_Switch, Logdir_Switch, Runstatedir_Switch,
+       Lockdir_Switch, Libdir_Switch, Localedir_Switch, Mandir_Switch,
+       Infodir_Switch, Miscdocdir_Switch);
+
+
+   --
    -- The following variables are for use in attributes to control where
    -- generated files are placed.
    --
diff --git a/manual.en.html b/manual.en.html
index b69237d..070157e 100755
--- a/manual.en.html
+++ b/manual.en.html
@@ -227,12 +227,24 @@ 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
+files that are preprocessed with Gnatprep.
+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>A set of switch variables are derived from the directory variables
+but have the suffix “<var>_Switch</var>” in their names.
+These contain compiler parameters that define the directory variables as
+preprocessor symbols for GNAT's integrated preprocessing.
+They are available to build project files.
+They are more convenient than the plain directory variables
+to use in <var>Compiler'Switches</var> or <var>Compiler'Default_Switches</var>
+to convey directory variables to your program,
+when your program needs the directory names at run time.
+Either use those switch variables that your program needs,
+or use <var>Comfignat.All_Dir_Switches</var>
+which is a list of compiler parameters.</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.
@@ -240,7 +252,7 @@ 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
+<p>Yet another 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
@@ -257,6 +269,65 @@ to makefiles.</p>
 and prerequisites there are <var>Make_stagedir</var>, <var>Make_objdir</var>,
 <var>Make_srcdir</var> and <var>Make_builddir</var></p>
 
+<h4 id="directory_variables_example">Example</h4>
+
+<p>Here's an example where a program needs to
+read its configuration from a file in <var>Sysconfdir</var>,
+cache some data in its own subdirectory of <var>Cachedir</var>,
+and coordinate with other programs through lock files in <var>Lockdir</var>.
+A source file defines constants for the pathnames,
+based on preprocessor symbols:</p>
+
+<div class="example file"><h5><code>configuration.adb</code></h5>
+<pre class="ada">package body Configuration is
+
+   Configuration_File : constant String := $Sysconfdir &amp; "/example.conf";
+   Cachesubdir        : constant String := $Cachedir   &amp; "/example";
+   Lockdir            : constant String := $Lockdir;
+
+   [...]
+
+end Configuration;</pre></div>
+
+<p>The build project uses switch variables to define those symbols.
+It also uses <var>Objdir</var> and <var>Stage_Bindir</var>
+to control where files are written during the build:</p>
+
+<div class="example file"><h5><code>build_example.gpr</code></h5>
+<pre class="gpr">with "comfignat.gpr";
+
+standard project Build_Example is
+
+   for Main       use ("example");
+   for Object_Dir use Comfignat.Objdir;
+   for Exec_Dir   use Comfignat.Stage_Bindir;
+
+   package Compiler is
+      for Default_Switches ("Ada") use ("-gnatwa", "-gnatVa");
+      for Switches ("configuration.adb") use
+         Compiler'Default_Switches ("Ada") &amp;
+         (Comfignat.Sysconfdir_Switch,
+          Comfignat.Cachedir_Switch,
+          Comfignat.Lockdir_Switch);
+   end Compiler;
+
+end Build_Example;</pre></div>
+
+<p>The makefile stages a default configuration file
+and the program's own cache directory
+as part of the build,
+using the <var>Make_</var> variables:</p>
+
+<div class="example file"><h5><code>Makefile</code></h5>
+<pre class="make">include comfignat.mk
+
+build_GPRs = build_example.gpr
+
+build: ${Make_sysconfdir}/example.conf ${Make_cachedir}/example/
+
+${Make_sysconfdir}/example.conf: defaults.conf | ${Make_sysconfdir}/
+	cp -p $&lt; $@</pre></div>
+
 <h4 id="where">Where to Place Files</h4>
 
 <h5 id="where_programs">Programs</h5>
@@ -265,13 +336,16 @@ and prerequisites there are <var>Make_stagedir</var>, <var>Make_objdir</var>,
 <li><p>Programs that can be run from a command prompt shall be placed in
 <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>
+makefiles.
+If a relocatable program needs <var>bindir</var> compiled in, then
+use <var>Comfignat.Bindir_Switch</var> in <var>Compiler'Switches</var>.</p></li>
 
 <li><p>Programs that are only to be run by other programs, not by users, shall
 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>
+<var>stage_libexecdir</var> by makefiles.
+Use <var>Comfignat.Libexecdir_Switch</var> in <var>Compiler'Switches</var>
+for programs that need to invoke such programs.</p></li>
 </ul>
 
 <h5 id="where_libraries">Libraries</h5>
@@ -304,8 +378,9 @@ project files shall get the directory from the preprocessor symbol
 <li><p>Other architecture-specific files shall usually be placed under a
 separate subdirectory of <var>stage_libdir</var>. (It will be the same
 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>
+<var>alidir</var> = <var>libdir</var>.)
+Use <var>Comfignat.Libdir_Switch</var> in <var>Compiler'Switches</var>
+for programs that read them.</p></li>
 
 <li><p>Comfignat automatically puts usage project files in
 <var>stage_gprdir</var>.</p></li>
@@ -315,29 +390,37 @@ subdirectory that ALI files are placed in when
 
 <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>
+placed under a separate subdirectory of <var>stage_datadir</var>.
+Use <var>Comfignat.Datadir_Switch</var> in <var>Compiler'Switches</var>
+for programs that read them.</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>
+subdirectories under <var>stage_localedir</var>.
+Use <var>Comfignat.Localedir_Switch</var> in <var>Compiler'Switches</var>
+for programs that read them.</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>
+should probably be under a separate subdirectory.
+Use <var>Comfignat.Sysconfdir_Switch</var> in <var>Compiler'Switches</var>
+for programs that read them.</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>
+subdirectory of <var>stage_statedir</var>.
+Use <var>Comfignat.Statedir_Switch</var> in <var>Compiler'Switches</var>
+for programs that read and write them.</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
+<var>cachedir</var>.
+Use <var>Comfignat.Cachedir_Switch</var> in <var>Compiler'Switches</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
+<li><p>Log files shall be written under <var>logdir</var>.
+Use <var>Comfignat.Logdir_Switch</var> in <var>Compiler'Switches</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>
@@ -367,12 +450,16 @@ be placed in <var>stage_userunitdir</var>.</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
+<var>runstatedir</var>.
+Use <var>Comfignat.Runstatedir_Switch</var> in <var>Compiler'Switches</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>
+under <var>lockdir</var>.
+Use <var>Comfignat.Lockdir_Switch</var> in
+<var>Compiler'Switches</var>.</p></li>
 </ul>
 
 <h5 id="where_intermediate">Intermediate Files</h5>