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