From b3263dc7119ce5e7da4422bc48877b8b93fc187a Mon Sep 17 00:00:00 2001 From: Björn Persson Date: Thu, 4 Sep 2025 11:43:38 +0200 Subject: Added switch variables. --- manual.en.html | 129 +++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 108 insertions(+), 21 deletions(-) (limited to 'manual.en.html') 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 comfignat.mk, as GNAT project variables to build project files that import comfignat.gpr, 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 relocatable package is built. Otherwise they are absolute. In makefiles they are always absolute.

+

A set of switch variables are derived from the directory variables +but have the suffix “_Switch” 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 Compiler'Switches or Compiler'Default_Switches +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 Comfignat.All_Dir_Switches +which is a list of compiler parameters.

+

Another set of directory variables, which are derived from the first set but have the prefix “stage_” 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.

-

A third set, with the prefix “Make_”, are relative versions of +

Yet another set, with the prefix “Make_”, 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.

and prerequisites there are Make_stagedir, Make_objdir, Make_srcdir and Make_builddir

+

Example

+ +

Here's an example where a program needs to +read its configuration from a file in Sysconfdir, +cache some data in its own subdirectory of Cachedir, +and coordinate with other programs through lock files in Lockdir. +A source file defines constants for the pathnames, +based on preprocessor symbols:

+ +
configuration.adb
+
package body Configuration is
+
+   Configuration_File : constant String := $Sysconfdir & "/example.conf";
+   Cachesubdir        : constant String := $Cachedir   & "/example";
+   Lockdir            : constant String := $Lockdir;
+
+   [...]
+
+end Configuration;
+ +

The build project uses switch variables to define those symbols. +It also uses Objdir and Stage_Bindir +to control where files are written during the build:

+ +
build_example.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") &
+         (Comfignat.Sysconfdir_Switch,
+          Comfignat.Cachedir_Switch,
+          Comfignat.Lockdir_Switch);
+   end Compiler;
+
+end Build_Example;
+ +

The makefile stages a default configuration file +and the program's own cache directory +as part of the build, +using the Make_ variables:

+ +
Makefile
+
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 $< $@
+

Where to Place Files

Programs
@@ -265,13 +336,16 @@ and prerequisites there are Make_stagedir, Make_objdir,

  • Programs that can be run from a command prompt shall be placed in Comfignat.Stage_Bindir by build project files. Any executable files that aren't built with GNAT tools shall be placed in stage_bindir by -makefiles.

    • +makefiles. +If a relocatable program needs bindir compiled in, then +use Comfignat.Bindir_Switch in Compiler'Switches.

  • Programs that are only to be run by other programs, not by users, shall be placed under a separate subdirectory of Comfignat.Stage_Libexecdir by build project files – or under -stage_libexecdir by makefiles. Programs that need to invoke such -programs shall have Comfignat.Libexecdir compiled in.

    • +stage_libexecdir by makefiles. +Use Comfignat.Libexecdir_Switch in Compiler'Switches +for programs that need to invoke such programs.

    Libraries
    @@ -304,8 +378,9 @@ project files shall get the directory from the preprocessor symbol

  • Other architecture-specific files shall usually be placed under a separate subdirectory of stage_libdir. (It will be the same subdirectory that ALI files are placed in when -alidir = libdir.) Programs shall look for them under -Comfignat.Libdir.

    • +alidir = libdir.) +Use Comfignat.Libdir_Switch in Compiler'Switches +for programs that read them.

  • Comfignat automatically puts usage project files in stage_gprdir.

    • @@ -315,29 +390,37 @@ subdirectory that ALI files are placed in when @@ -367,12 +450,16 @@ be placed in stage_userunitdir.

  • 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 -Comfignat.Runstatedir. (This is not the place for +runstatedir. +Use Comfignat.Runstatedir_Switch in Compiler'Switches. +(This is not the place for temporary files in general.)

  • 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 Comfignat.Lockdir.

    • +under lockdir. +Use Comfignat.Lockdir_Switch in +Compiler'Switches.

    Intermediate Files
    -- cgit v1.2.3