icmconf - Configuration file for the icmbuild(1) program
maintenance script
The icmconf configuration file is used to specify and
fine-tune the program maintenance performed by the icmbuild(1)
script. It can be used to activate and specify various directives that
determine how the program or library maintenance is performed.
The directives are biased towards the construction of a C++
program, but program maintenance for other languages (e.g., C) can
also easily be configured.
The icmbuild(1) script ignores empty lines and lines whose
first non-blank characters are two consecutive forward slashes (//). Long
lines can be split over multiple lines by using a final backslash character
at lines continuing at the next line (refer to the icmake(1) man-page
for further details).
Traditional make-utilities recompile all dependent sources once
header files are modified. When developing C++ programs this is
hardly ever requird, as adding a new member function to a class does not
require you to recompile already existing source files. Recompilation
is required when modifying the data member organization of
classes.
To handle class dependencies in a more sensible way,
icmake(1) checks class dependencies using its support program
/usr/lib/icmake/icm-dep, visiting the classes listed in the
CLASSES file if icmconf’s USE_ALL directive was
specified. If a directory mentioned in the CLASSES file contains a
file having a name that’s equal to the name specified at the
USE_ALL parameter, then all sources of classes that depend on that
particular class are also recompiled.
Likewise, if the PRECOMP parameter was specified, then a
similar action is performed for the precompiled headers: if a local header
file that’s (directly or indirectly) included by a class’s
internal header file has changed, then that class’s precompiled
header as well as all precompiled headers of dependent classes are
recompiled.
The icmbuild(1) script itself does not inspect these
dependencies, but calls /usr/lib/icmake/icm-dep to perform the
requird tests. The program icm-dep’s short usage summary is
written to the standard output stream when calling icmake -d (or
directly: /usr/lib/icmake/icm-dep).
- o
- #define ADD_LIBRARIES ""
When a program must be linked against additional libraries (other than the
name of the program’s library itself, if specified at
LIBRARY) then those libraries should be specified, blank space
separated, here. E.g., when a program is linked against libbobcat
then the specification is:
#define ADD_LIBRARIES "bobcat"
If your program is linked against multiple libraries, then use a
blank-separated list of libraries (like "math
bobcat")
- o
- #define ADD_LIBRARY_PATHS ""
When the additional libraries (specified at ADD_LIBRARIES) are
located in non-standard library locations (e.g., not in /lib and
/usr/lib) then these additional paths are (blank space separated)
specified here. Specify only the paths, not the -L flags.
- It is stronly advised to specify full pathnames here, or remember that
normally the location of the icmconf file is not the location where
the compilation actually takes place, which is the location specified at
the TMP_DIR parameter (see below).
- o
- #define CLS
The clear screen directive. If defined tput clear is called to
clear the terminal screen before starting the compilation. By default it
is not defined.
- o
- #define CXX "g++"
The C++ compiler to use. For a C compiler use, e.g., #define
CC "gcc". Its setting is overruled by an identically
named environment variable.
- o
- #define CXXFLAGS "--std=c++14 -Wall -O2"
The compiler options to use. The default options are shown. When the
C compiler is used, use #define CFLAGS rather than
CXXFLAGS. Its setting is overruled by an identically named
environment variable.
- o
- #define DEFCOM "..."
A DEFCOM directive may be added to the icmconf file (the
icmstart(1) script can do this for you). It may be defined as:
#define DEFCOM "program"
in which case icmbuild will do program maintenance. It may also be
defined as:
#define DEFCOM "program strip"
in which case icmbuild does program maintenance, creating a stripped
binary program.
- Alternatively it may also be defined as:
#define DEFCOM "library"
in which case icmbuild does library maintenance.
- o
- //#define ICM_DEP "-V go"
The existence and implied existence of USE_ALL files (see the
description of the USE_ALL directive), as well as the correct ages
of precompiled headers can be checked by icmake’s support
program icm_dep. By default icm_dep is called with the shown
default arguments. If icm_dep should not be called define
ICM_DEP as an empty string ("").
Icmake(1)’s man-page contains a separate section about the
icm_dep support program.
- o
- #define IH ".ih"
The extension used for internal header files. See #define PRECOMP
below.
- o
- #define LDFLAGS ""
The linker options to use. By default no options are passed to the linker.
Its setting is overruled by an identically named environment
variable.
- o
- #define LIBRARY "modules"
By default this directive is not defined. If defined a local library is
constructed. When a binary program is built it will be linked against this
library rather than to the individual object modules.
- If a library must be constructed (see also the DEFCOM directive),
then the LIBRARY directive must specify the library’s base
name (without the lib prefix and without the .a
extension).
- After a library has been constructed icmbuild install static dir
installs the static library at dir, while icmbuild install
shared dir installs the shared library (see below at #define
SHARED) at dir.
- o
- #define MAIN "main.cc"
The source file in which the int main function is defined. This
specification may be left as-is or may completely be removed if
icmbuild(1) is used for library maintenance rather than program
maintenance.
- o
- //#define NO_PRECOMP_WARNING"
When PRECOMP is defined (see below) a warning is issued when a
class-directory does not contain a IH file. Such warnings are
suppressed when defining NO_PRECOMP_WARNING. This option is ignored
unless PRECOMP has been defined.
- o
- #define OBJ_EXT ".o"
The extension of object modules created by the compiler.
- o
- //#define PRECOMP "-x c++-header"
When activated internal header files (see #define IH) are precompiled
when they are more recent than their precompiled versions. Also, when a
precompiled header file is (re)compiled the precompiled header files of
all dependent classes are also recompiled.
- Precompiled headers are removed by icmbuild clean. To specify
internal header files for other languages change the -x
specification accordingly. By default this #define is not
active.
- o
- #define REFRESH
Define REFRESH to relink the binary program at every icmbuild
program call. By default REFRESH is not defined.
- o
- #define SHARED
This directive is only interpreted if LIBRARY was also specified. If
defined a static library (extension .a) as well as a shared library
(extension .so*) is built. If not specified, but LIBRARY was
specified, only the static library is built. By default SHARED is
not defined.
- The shared library receives as its major version number
VERSION’s major version number, and receives VERSION
as its full version number. E.g., if VERSION is defined as
1.02.03 and LIBRARY is defined as demo then the
shared library libdemo.so.1.02.03 is constructed, with
libdemo.so.1 soft-linking to it, with libdemo.so in turn
soft-linking to libdemo.so.1.
- o
- #define SHAREDREQ ""
When creating a shared library SHAREDREQ specifies the names of
libraries and library paths that are required by the shared library. E.g.,
if a library is found in /usr/lib/special, assuming that the name
of the required library is libspecial.so, then use the
specification "-L/usr/lib/special -lspecial". The
/lib and /usr/lib paths are usually predefined and need not
be specified. This directive is only interpreted if SHARED and
LIBRARY were also defined.
- o
- #define SOURCES "*.cc"
The pattern to locate sources in a directory. The default value is
shown.
- o
- #define TMP_DIR "tmp"
The directory in which intermediate results are stored. Relative to the
current working directory unless an absolute path is specified.
- o
- #define USE_ALL "a"
After defining this directive (by default it is not defined) class
dependencies are interpreted. In this case, when a directory contains a
file having a name that’s equal to the name specified at the
USE_ALL directive, then all sources of that class as well as all
sources of classes that depend on it are (re)compiled.
- Following the successful recompilations the s specified at
#define USE_ALL are removed.
- When the USE_ALL directive was specified the command
icmbuild clean also removes any leftover USE_ALL
files from the program’s subdirectories.
- o
- #define USE_ECHO ON
When specified as ON (rather than OFF) commands executed by
icmbuild are echoed.
- o
- #define USE_VERSION
If defined (which is the default) the file VERSION is read by
icmconf to determine the program/library’s version, and the
project’s release years.
The following directives are available in cases where a program
uses a parser generator creating a parser class from a grammar
specification:
- o
- #define PARSER_DIR ""
The subdirectory containing the parser’s specification file.
- If parser maintenance is not required, then this directive can be omitted.
If omitted, then all other directives, that begin with PARS, can
also be omitted.
- o
- #define PARSFILES ""
If the parser specification file named at PARSSPEC itself includes
additional specification files, then patterns matching these additional
grammar specification files should be specified here. The pattern is
interpreted in the directory specified at PARSER_DIR and could
contain a subdirectory name (e.g. specs/*). When files matching the
pattern are modified then a new parser will be created. By default no
additional specification files are used.
- o
- #define PARSFLAGS "-V"
The flags to use when calling the program specified at PARSGEN.
- o
- #define PARSGEN "bisonc++"
The name of the program generating the parser.
- o
- #define PARSOUT "parse.cc"
The name of the file generated by the parser generator (which is used by
icmbuild to compare the timestamps of the parser specification
s against).
- o
- #define PARSSPEC "grammar"
The name of the parser specification file. This file is expected in the
directory specified at PARSER_DIR.
The following directives are available in cases where a program
uses a scanner generator creating a lexical scanner class from a set of
regular expressions:
- o
- #define SCANNER_DIR ""
The subdirectory containing the scanner’s specification file.
- If lexical scanner maintenance is not required, then this directive can be
omitted. If omitted, then all other directives, that begin with
SCAN, can also be omitted.
- o
- #define SCANFILES ""
If the lexical scanner specification file named at SCANSPEC itself
includes additional specification files, then patterns matching these
additional lexer specification files should be specified here. The pattern
is interpreted in the directory specified at SCANNER_DIR and could
contain a subdirectory name (e.g. specs/*). When files matching the
pattern are modified then a new lexical scanner will be created. By
default no additional specification files are used.
- o
- #define SCANFLAGS ""
The flags to use when calling the program specified at SCANGEN.
- o
- #define SCANGEN "flexc++"
The name of the program generating the lexical scanner.
- o
- #define SCANOUT "lex.cc"
The name of the file generated by the lexical scanner (which is used by
icmbuild to compare the timestamps of the scanner specification
s against).
- o
- #define SCANSPEC "lexer"
The name of the lexical scanner specification file. This file is expected in
the directory specified at SCANNER_DIR.
The mentioned paths are sugestive only and may be installation
dependent:
- o
- /usr/share/icmake/CLASSES
Example of an icmconf CLASSES file.
- o
- /usr/share/icmake/icmconf
Default skeleton icmbuild resource file.
- o
- /etc/icmake
Directory containing the default system-wide icmake(1) configuration
files (like VERSION and icmstart.rc)
- o
- $HOME/.icmake
Optional directory containing user-defined specifications overruling the
system-wide definitions. This directory is the proper location for a file
AUTHOR defining the AUTHOR directive with the user’s
name. E.g., my .icmake/AUTHOR file contains:
-
#define AUTHOR "Frank B. Brokken (f.b.brokken@rug.nl)";
icmbuild(1) ends displaying a fatal error message if the
current working directory does not contain a file icmconf.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).