From 929b6ada115224ee4e9f1a147e7dd95819b78024 Mon Sep 17 00:00:00 2001 From: Björn Persson Date: Wed, 1 Jul 2015 23:39:13 +0200 Subject: Improved the documentation of directory variables. --- manual.en.html | 248 ++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 158 insertions(+), 90 deletions(-) (limited to 'manual.en.html') 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

The following applies to all of Comfignat including this document:

-

Copyright 2013 - 2014 Björn Persson, Bjorn@Rombobjörn.se

+

Copyright 2013 - 2015 Björn Persson, Bjorn@Rombobjörn.se

This material is provided as is, with absolutely no warranty expressed or implied. Any use is at your own risk.

@@ -140,10 +140,9 @@ that the project Comfignat defines.

  • Use Comfignat.Objdir for Object_Dir.

  • If your project file builds a program, then use - Comfignat.Stage_Bindir for Exec_Dir, 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 - Comfignat.Stage_Libexecdir.

    • + Comfignat.Stage_Bindir for Exec_Dir (or, + in some cases, a subdirectory of + Comfignat.Stage_Libexecdir).

  • If your project file builds a library, then use a subdirectory of Comfignat.Stage_Includedir for Library_Src_Dir, @@ -213,86 +212,71 @@ usage_GPRs = example.gpr

    How to Use Comfignat

    -

    Where to Place Files

    +

    Directory Variables

    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 stagedir. In the installation step that whole directory structure is copied to the directory specified in DESTDIR, or to the -root directory if DESTDIR 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.

    - -

    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 “stage_” point to the directories under the -staging directory where the files shall be written during the build. Variables -without the “stage_” 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.

    - -

    Directory variables 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. If the Make variable -relocatable_package is set to “true” on the command -line, then the variables for embedding will be relative to bindir in -build project files, and relative to gprdir in usage project -files, except that bindir will instead be relative to -libexecdir, and runstatedir and lockdir are -always absolute.

    +root directory if DESTDIR is empty.

    + +

    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 +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 +relocatable package is built. Otherwise they are +absolute. In makefiles they are always absolute.

    + +

    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. +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 +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 +“stage_” variables should work.) These variables are only available +to makefiles.

    + +

    The directory objdir is meant for intermediate files, and +srcdir and builddir are used to support +separate build directories. For Make targets +and prerequisites there are Make_stagedir, Make_objdir, +Make_srcdir and Make_builddir

    + +

    Where to Place Files

    + +
    Programs
    -

  • Log files shall be written under Comfignat.Logdir. You won't -install log files but you may want to create a separate subdirectory under -stage_logdir if your program writes its own log files.

    • - -

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

    • +
    Libraries
    + + +
    Data
    + + + +
    Documentation
    + + +
    System State
    + + + +
    Intermediate Files
    + + +

    Directories Projects

    A directories project is a GNAT project file that defines directory @@ -360,8 +400,9 @@ target architecture.

    The directory for programs that can be run from a command prompt.
    Libexecdir
    -
    The top-level directory for programs that are intended to be run by other -programs rather than by users.
    +
    The parent of applications' separate application-specific directories for +programs that are intended to be run by other programs rather than by +users.
    Includedir
    The top-level directory for (normally architecture-independent) source @@ -437,6 +478,33 @@ atomic_doodads = true symbols to preprocessed files and as external variables to build project files.

    +

    Relocatable Packages

    + +

    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.

    + +

    If the Make variable relocatable_package is set to +“true” 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 gprdir 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 bindir. Provided that a program can find out the +pathname of its own executable file, it can get bindir as the +directory part of that, and then find the other directories relative to that +directory. bindir will instead be relative to libexecdir +so that a helper program in libexecdir can find bindir +and then find the other directories from there.

    + +

    Only runstatedir and lockdir 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 runstatedir.

    +

    Build Tools and their Arguments

    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 data exists before the file db is written:

    -
    ${stage_statedir}/example/data/db: | ${stage_statedir}/example/data/
+
    ${Make_statedir}/example/data/db: | ${Make_statedir}/example/data/
 	echo stuff > $@
    
 
 
    Make Targets
    
@@ -556,7 +624,7 @@ directory data exists before the file db is written:
    
 
    These phony targets are defined in comfignat.mk:
    
 
 
    
-
    build
    
+
    build
    
 
    This is what a plain “make” will do (unless your makefile
 defines some other target before it includes comfignat.mk). By
 default it builds and stages the build projects that are listed in
@@ -567,7 +635,7 @@ example documentation:
    
 
 
    build: man html pdf
    
 
-
    install
    
+
    install
    
 
    If a user unpacks a source package and immediately runs
 “make install”, then the build target is built and then
 installed. If some files have already been staged in the staging directory,
@@ -575,7 +643,7 @@ then “make install” doesn't rebuild anything but just copies th
 staged directory structure to the directory specified in DESTDIR, or
 to the root directory if DESTDIR is empty.
    
 
-
    all
    
+
    all
    
 
    By default all is the same as build, 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
 
 
    all: demo_programs auxiliary_tools
    
 
-
    base
    
+
    base
    
 
    This builds and stages the build projects that are listed in
 build_GPRs, but does not do everything that build 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.
    
 
-
    preprocess
    
+
    preprocess
    
 
    This preprocesses files that need to be preprocessed before projects are
 built.
    
 
-
    postinstall
    
+
    postinstall
    
 
    You may add a recipe to postinstall 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 do_postinstall to
 “true” or “false”.
    
 
-
    preinstall
    
+
    preinstall
    
 
    This is like postinstall except that it's run before the
 files are installed, not after. Installing users can control it with
 do_preinstall.
    
 
-
    install_files
    
+
    install_files
    
 
    You may add a recipe to install_files 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.
    
 
-
    configure
    
+
    configure
    
 
    “make configure” is used to set values in the
 persistent configuration and to set up a
 separate build directory. This is a
@@ -625,25 +693,25 @@ double-colon rule so you can add your own configure recipe in case
 you need to configure things that can't easily be expressed as Make
 variables.
    
 
-
    show_configuration
    
+
    show_configuration
    
 
    “make show_configuration” outputs the configured variables
 in the persistent configuration. This is a
 double-colon rule so you can add your own show_configuration recipe
 to accompany your own configure recipe.
    
 
-
    unconfigure
    
+
    unconfigure
    
 
    This deletes the configuration file that “make configure”
 writes. This is a double-colon rule. If you add your own configure
 recipe that writes additional configuration files, then you should also add an
 unconfigure recipe to delete those files.
    
 
-
    clean
    
+
    clean
    
 
    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 clean recipe to delete files that your recipes
 generate.
    
 
-
    distclean
    
+
    distclean
    
 
    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, “make distclean” leaves only
-- 
cgit v1.2.3