Provided by: icmake_8.01.00-1_amd64 
NAME
icmconf - Configuration file for the icmbuild(1) program maintenance script
DESCRIPTION
The icmconf configuration file is used to specify and fine-tune the characteristics of
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 character is a
hash-mark (#) as well as 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).
CLASS DEPENDENCIES
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)’s CLASSES file may define
dependencies among classes.
By default, class-dependencies are not interpreted. To activate class-dependencoes
recognition then the line
//#define USE_ALL "a"
in the icmconf file must be uncommented:
#define USE_ALL "a"
If a class Y depends on class X as in:
class Y: public X
{
...
};
or as in:
class Y
{
X d_y;
...
};
then the sources of class Y should be recompiled if X’s data organization has changed. In
such cases Y depends on X.
Such class dependencies can be specified in the CLASSES file using the form:
y x
where x and y are the names of the directories in which the respective class sources are
found. If icmconf contains a line
#define USE_ALL "a"
then, after modifying X’s data organization, do ’touch x/a’, followed by ’icmbuild
program’. Icmbuild now compiles all of x’s sources as well as the sources in directories
(in)directly depending on x (in the example: the sources in the y directory).
Multiple dependencies can also be specified. If the class organization looks like this:
class Z: public Y
{
X d_x;
};
then Z depends on both Y and X. In the CLASSES file this is configured like this:
z x y
Indirect dependencies are automatically recognized. After changing X’s data organization
where CLASSES contains the lines
x
y x
z y
then icmbuild recompiles all source files in directories x, y and z.
ICMCONF PARAMETERS
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"
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.
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 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 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. They are removed again 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) a class dependency
setup defined in the CLASSES file is interpreted. In this case, when a directory
contains a file named at the USE_ALL directive, then all sources of that class as
well as all sources of all classes depending on it are (re)compiled. The program’s
root directory is assumed to depend on all other directories.
Class dependencies in CLASSES consist of the class name (as the first word on a
line) optionally followed by additional class names, which are the classes on which
the line’s first class name depends.
Assuming that a program uses five classes One, Two, Three, Four and Five, whose
sources are in, respectively, directories one, two, three, four, and five. If class
Three depends on class Two, which in turn depends on class One, while class Five
depends on Three and Four, then the file CLASSES may reflect these dependencies as
follows:
one
two one
three two
four
five three four
Afer touching (creating) the file two/a (using e.g., the command touch two/a) all
sources of the classes Two, Three and Five as well as all the sources in the
program’s root directory are recompiled: Two is recompiled because of the existence
of two/a, Three is recompiled because it depends on Two, Five is recompiled because
it depends on Three, the sources in the program’s root directory are recompiled
because at least one directory was recompiled.
Following the recompilations the s specified at #define USE_ALL are removed.
When the USE_ALL directive was defined the command icmbuild clean also removes any
leftover USE_ALL files from the program’s direct 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.
PARSER MAINTENANCE
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.
SCANNER MAINTENANCE
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.
FILES
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)";
SEE ALSO
icmake(1), icmbuild(1), icmstart(1), icmstart.rc(7).
BUGS
icmbuild(1) ends displaying a fatal error message if the current working directory does
not contain a file icmconf.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).