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