diff options
Diffstat (limited to 'manual.en.html')
| -rwxr-xr-x | manual.en.html | 164 |
1 files changed, 137 insertions, 27 deletions
diff --git a/manual.en.html b/manual.en.html index 9910afb..4d6d73a 100755 --- a/manual.en.html +++ b/manual.en.html @@ -17,12 +17,12 @@ <p>Comfignat is common, convenient, command-line-controlled compile-time configuration of software built with the -<a href="http://gcc.gnu.org/onlinedocs/gnat_ugn_unw/">GNAT tools</a> on +<a href="https://gcc.gnu.org/onlinedocs/gnat_ugn/">GNAT tools</a> on Unix-like operating systems. It consists of a makefile foundation to be included by your makefile, and an abstract GNAT project file to be imported by your project files. Leveraging <a href="https://www.gnu.org/software/make/">GNU Make</a> and -<a href="http://gcc.gnu.org/onlinedocs/gnat_ugn_unw/Preprocessing-with-gnatprep.html">Gnatprep</a>, +<a href="https://gcc.gnu.org/onlinedocs/gnat_ugn/Preprocessing-with-gnatprep.html">Gnatprep</a>, Comfignat adds the flexibility that GNAT project files lack, so that programs and libraries whose build systems are built around Comfignat can easily be configured for all sorts of use cases. Comfignat also helps with configuration @@ -81,8 +81,8 @@ project files with those, so that the installed directory tree as a whole can be moved to another location in the filesystem without breaking the project files.</p></li> -<li><p><a href="http://gcc.gnu.org/onlinedocs/gnat_ugn_unw/The-GNAT-Make-Program-gnatmake.html">Gnatmake</a> -and <a href="http://docs.adacore.com/gprbuild-docs/html/gprbuild_ug.html">GPRbuild</a> +<li><p><a href="https://gcc.gnu.org/onlinedocs/gnat_ugn/Building-with-gnatmake.html">Gnatmake</a> +and <a href="https://docs.adacore.com/gprbuild-docs/html/gprbuild_ug.html">GPRbuild</a> are both supported, which makes Comfignat suitable for both mixed-language projects and pure Ada projects.</p></li> @@ -112,7 +112,7 @@ and is also <p>The following applies to all of Comfignat including this document:</p> -<p>Copyright 2013 - 2016 Björn Persson, Bjorn@Rombobjörn.se</p> +<p>Copyright 2013 - 2025 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> @@ -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 & "/example.conf"; + Cachesubdir : constant String := $Cachedir & "/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") & + (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 $< $@</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> @@ -355,18 +438,28 @@ subdirectories under <var>stage_mandir</var>.</p></li> <var>stage_miscdocdir</var>.</p></li> </ul> -<h5 id="where_system">System State</h5> +<h5 id="where_system">System Integration</h5> <ul> +<li><p>SystemD unit files that are independent of user sessions shall be placed +in <var>stage_unitdir</var>.</p></li> + +<li><p>SystemD unit files for services that run as part of a user session shall +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> @@ -768,6 +861,23 @@ and testing, and delete parts that don't apply to your project.</p> <h2 id="news">News</h2> +<h3 id="news_1.6">Noteworthy Changes in Version 1.6</h3> + +<ul> +<li><p>Switch variables were added to make it more convenient to convey +directory variables to the program being compiled.</p></li> + +<li><p>Directory variables for SystemD unit files were added.</p></li> +</ul> + +<h3 id="news_1.5">Noteworthy Changes in Version 1.5</h3> + +<ul> +<li><p>The variable Library_Type was added to help with writing build project +files that allow installing users to choose whether to build a shared or static +library.</p></li> +</ul> + <h3 id="news_1.4">Noteworthy Changes in Version 1.4</h3> <ul> |