icmconf(7) configuration file for icmbuild(1)icmconf(7)NAMEicmconf - Configuration file for the icmbuild(1) program maintenance
script
DESCRIPTION
The icmconf configuration file is used to specify and tailor the char‐
acteristics 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 mod‐
ified. 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 organiza‐
tion 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 indi‐
cated 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’ results in recompiling 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"
Empty lines and lines whose first non-blank character is a hash-mark
(#) or whose first non-blank characters are two consecutive forward
slashes (//) are ignored. Long lines can be split over multiple lines
by using a final backslash character at lines which continue at the
next line. E.g.,
name1 depends on multiple other classes
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 speci‐
fied 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 sepa‐
rated) 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 environ‐
ment variable.
o #define CXXFLAGS "--std=c++0x -Wall -g -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 by icmstart.
It may be defined as:
#define DEFCOM "program"
in which case icmbuild will do program maintenance. Alterna‐
tively it may be defined as:
#define DEFCOM "program strip"
in which case icmbuild will do program maintenance, creating a
stripped binary program. It may also be defined as
#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.
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 construction is intended (see also the DEFCOM
directive), then the LIBRARY directive defines the base name
(without the lib prefix and without the .a extension) of the
library to be constructed.
After a library construction install static dir installs the
static library at dir, which install shared dir installs the
shared library (see below at #define SHARED) at dir.
o #define MAIN "main.cc"
The source file defining the int main function. This specifica‐
tion may be left as-is or may completely be removed if icm‐
build(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 PARSER_DIR ""
The subdirectory containing the parser’s specification file.
Leave empty if no parser class is used and if no parser is gen‐
erated. The following directives, beginning with PARS, are only
interpreted when PARSER_DIR is defined as a non-empty string.
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 speci‐
fication s against).
o #define PARSSPEC "grammar"
The name of the parser specification file. This file is expected
in the directory specified at PARSER_DIR.
o #define REFRESH
Define REFRESH to relink the binary program at every icmbuild
program call. By default REFRESH is not defined.
o #define SCANNER_DIR ""
The subdirectory containing the scanner’s specification file.
Leave empty if no scanner class is used and if no lexical scan‐
ner is generated. The following directives, beginning with SCAN,
are only interpreted when SCANNER_DIR is defined as a non-empty
string.
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 addi‐
tional 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 speci‐
fication 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.
o #define SHARED
This directive is only interpreted if LIBRARY was also speci‐
fied. 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 VER‐
SION’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 lib‐
demo.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 inter‐
preted. 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 pro‐
gram’s root directory are recompiled because at least one direc‐
tory 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 neces‐
sary recompilations.
Following the recompilations the USE_ALL s 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 icm‐
build 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.
OBSOLETE DIRECTIVES
o BINARY ""
This #define may safely be removed from older icmconf files as
it is no longer used by icmbuild. When a binary program is con‐
structed it is created as TMP_DIR "/bin/binary", while install
program path installs the binary program at path.
o BIN_INSTALL
This #define may safely be removed from older icmconf files as
it is no longer used by icmbuild. See #define BINARY for details
about how to install a binary program
o #define COMPILER ""
This #define should be replaced by CXX or CC.
o #define COMPILER_OPTIONS ""
This #define should be replaced by CXXFLAGS or CFLAGS.
o LIB_INSTALL
This #define may safely be removed from older icmconf files as
it is no longer used by icmbuild. See #define LIBRARY for
details about how to install libraries.
o #define LINKER_OPTIONS ""
This #define should be replaced by LDFLAGS.
FILES
The mentioned paths are sugestive only and may be installation depen‐
dent:
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) configu‐
ration files (like VERSION and icmstart.rc)
o $HOME/.icmake
Optional directory containing user-defined specifications over‐
ruling 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 ALSOicmake(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.22.01.tar.gz 1992-2015 icmconf(7)
