Provided by: icmake_7.21.01-1_amd64 
NAME
icmconf - Configuration file for the icmbuild(1) program maintenance script
DESCRIPTION
The icmconf configuration file is used to specify and tailor the characteristics of program maintenance
performed by the icmbuild(1) icmake script. It can be used to activate and specify various directives
that determine how the program or library maintenance will proceed.
The directives are biased towards the construction of a C++ program, but program maintenance for other
languages (e.g., C) can easily be realized as well.
CLASS DEPENDENCIES
Traditional make-utilities recompile sources once header files are modified. In the context of C++
program development this is often a bad idea, as adding a new member to a class does not normally require
you to recompile the class’s sources. To handle class dependencies in a more sensible way, icmake(1)’s
CLASSES file may define dependencies among classes.
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 cases like
these 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 directories holding the respective class sources. Then, when altering X’s data
organization, do ’touch x/a’, followed by ’icmbuild program’: x’s sources as well as the sources in
directories (in)directly depending on x (e.g., y) are then automatically recompiled by icmbuild.
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 may be indicated by the line
z x y
Indirect dependencies are automatically followed. After changing X’s data organization where CLASSES
contains the lines
x
y x
z y
then ’icmbuild program’ will result in the recompilation of all of the sources in classes x, y and z.
By default, class-dependencies are not interpreted. To activate them the line
//#define USE_ALL "a"
in the icmconf file must be uncommented:
#define USE_ALL "a"
PROGRAM AND SOURCE CONFIGURATION
o #define MAIN "main.cc"
The specification of the file defining the int main function. This specification may be left as-is
if icmbuild(1) is used for library maintenance rather than program maintenance.
o #define BINARY "binary"
The name of the binary program. Can be left as-is if the intent is to construct a library rather
than a program. Don’t specify a path here. The installation path can be specified at the
BIN_INSTALL directive (see below)
o #define REFRESH
By defining REFRESH the binary program is always relinked, even when no sources were modified.
This can be useful if, e.g., a separate library was rebuilt against which the program must be
linked. By default REFRESH is not defined.
o #define BIN_INSTALL "/usr/local/bin"
This directive specifies the location where icmbuild install will install the binary program.
LIBRARY CONSTRUCTION
o #define LIBRARY "modules"
By default this directive is not defined. If defined a local library is defined. When a binary
program is built it will be linked against the library rather than the individual object modules.
If library construction is required (see below at the DEFCOM directive), then the LIBRARY
directive defines the name of the library that is built. Change the library’s name at your own
digression. Don’t use lib or an extension like .a.
o #define SHARED
This directive is only interpreted if LIBRARY was also specified. If SHARED is defined a static
library (extension .a) as well as a shared library (extension .so) is built. If not specified only
the static library is built. By default SHARED is not defined.
o #define SHAREDREQ ""
When creating a shared library: Specify the names of any libraries and library paths that are
required by the shared library between the double quotes. E.g., if a library is found in
/usr/lib/special use "-L/usr/lib/special -lspecial" assuming that the name of the required library
is libspecial.so. 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 LIB_INSTALL "/usr/local/lib"
This directive specifies the location where icmbuild install will install the library (libraries).
By default it is not specified. It should only be specified if LIBRARY was also specified.
COMPILING AND LINKING
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 USE_ALL "a"
When this directive is specified (by default it is not specified) 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 and that 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
Now touching (creating) the file two/a (using e.g., the command touch two/a) causes all sources of
the classes Two, Three and Five as well as all the sources in the program’s root directory to be
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 is recompiled.
This facility was added to the icmbuild script because C++ header files are often modified without
the need to recompile all their depending sources. No recompilation is necessary when a new class
member function is declared. Recompilation, however, is necessary when the class’s internal
organization changes, e.g., when the organization of its data members is modified. Simply touching
a file "a" is sufficient to perform the necessary recompilations.
Following the recompilations the a s are removed.
Note also that when the USE_ALL directive is used the command icmbuild clean also removes any
leftover USE_ALL files from the program’s direct subdirectories.
o #define COMPILER "g++ --std=c++0x -Wall"
This directive defines the compiler to use. The default is shown. The default illustrates that the
compiler definition may also be provided with compiler options. when specified, these options are
always used and cannot be suppressed by COMPILER_OPTIONS (see below).
o #define COMPILER_OPTIONS "-g -O2"
This directive defines the compiler options to use. The default options are shown. To enable GNU
extensions in addition to the compiler’s C++0x extensions, add the option --std=gnu++0x.
o #define COPT "CXXFLAGS"
When defined (by default COPT is not defined but embedded in comment) COPT defines the name of an
environment variable that may be defined holding compiler options. When this environment variable
is defined the COMPILER_OPTIONS specification is ignored and the value of the specified
environment variable will be used instead.
o #define SOURCES "*.cc"
This directive defines the pattern to locate sources in a directory. Its default value is shown.
o #define LINKER_OPTIONS ""
This directive defines the options the compiler should pass to the linker. By default no special
options are used
o #define LOPT "LDFLAGS"
When defined (by default LOPT is not defined but embedded in comment) LOPT defines the name of an
environment variable that may be defined holding linker options. When this environment variable is
defined the LINKER_OPTIONS specification is ignored and the value of the specified environment
variable will be used instead.
o #define ADD_LIBRARIES ""
When a program (see BINARY above) 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. Only the paths should be specified, not the -L flags.
LEXICAL SCANNERS
When a program uses a lexical scanner, generated by a scanner generator like flex(1), the icmbuild script
can be used to update the scanner source whenever the scanner specification file is modified. Here are
the directives that are related to the use of a lexical scanner generator:
o #define SCANNER_DIR ""
If a lexical scanner must be constructed, then the subdirectory containing the scanner’s
specification file is specified with this directive. If empty (the default) no scanner
construction is monitored by icmbuild and all remaining scanner-related directives are ignored.
o #define SCANGEN "flexc++"
The name of the program generating the lexical scanner.
o #define SCANFLAGS ""
The flags to use when calling the program specified at SCANGEN.
o #define SCANSPEC "lexer"
The name of the lexical scanner specification file. This file is expected in the directory
specified at SCANNER_DIR.
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 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).
GRAMMAR PARSERS
When a program uses a grammar parser, generated by a parser generator like bisonc++(1), the icmbuild
script can be used to update the parser’s sources whenever a parser specification file is modified. Here
are the directives that are related to the use of a parser generator:
o #define PARSER_DIR ""
If a parser must be constructed, then the subdirectory containing the parser’s specification file
is specified with this directive. If empty (the default) no parser construction is monitored by
icmbuild and all remaining parser-related directives are ignored.
o #define PARSGEN "bisonc++"
The name of the program generating the parser.
o #define PARSFLAGS "-V"
The flags to use when calling the program specified at PARSGEN.
o #define PARSSPEC "grammar"
The name of the parser specification file. This file is expected in the directory specified at
PARSER_DIR.
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 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).
ADDITIONAL DIRECTIVES
o #define USE_VERSION
When this directive is specified (which is the default) the file VERSION will be read by icmconf
to determine the version of the program, the program release years and the program’s author name.
The default VERSION file generated by icmstart defines AUTHOR, VERSION and YEARS.
o #define DEFCOM "..."
A DEFCOM directive may be added to the icmconf file by icmstart. If added, it may contain:
#define DEFCOM "program"
in which case icmbuild will do program maintenance. Alternatively it may contain:
#define DEFCOM "program strip"
in which case icmbuild will do program maintenance, creating a stripped binary program. It may
also contain
#define DEFCOM "library"
in which case icmbuild will de library maintenance.
If this directive was not added by icmstart(1) it can always be added to icmconf by hand.
The following directives usually require no tweaking:
o #define USE_ECHO ON
When specified as ON (rather than OFF) commands executed by icmbuild are echoed.
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 OBJ_EXT ".o"
The extension of object modules created by the compiler.
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
The interpretation of the class dependencies (see section COMPILING AND LINKING has altered when icmake
was updated to version 7.16.00.
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).
icmake.7.18.00.tar.gz 1992-2012 icmconf(7)