||configuration file for icmbuild(1)
icmconf - Configuration file for the icmbuild(1) program maintenance
The icmconf configuration file is used to specify and fine-tune the
program maintenance performed by the icmbuild(1) program and 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 characters are two consecutive forward slashes (//). Long
lines can be split over multiple lines by writing a final backslash
character at lines continuing at the next line (refer to the
icmake(1) man-page for further details).
Traditional make-utilities recompile all dependent sources once header files are
modified. When developing C++ programs this is hardly ever requird, as
adding new member functions to classes does not require you to recompile
already existing source files. Recompilation is required when the data
member organization of classes is altered.
To handle class dependencies in a more sensible way,
icmake(1) checks class dependencies using its support program
/usr/lib/icmake/icm-dep, visiting the classes listed in the
CLASSES file if icmconf’s USE_ALL directive was
specified. If a directory mentioned in the CLASSES file contains a
file having a name that’s equal to the name specified at the
USE_ALL parameter, then all sources of classes that depend on that
particular class are also recompiled. In practice this means that when you
change the data organization of a class you only need to touch it
that directory the file whose name was specified by the USE_ALL
directive. E.g., if your class is named Data, its sources are in the
sub-directory ./data, and #define USE_ALL "a" was
specified then after modifying the data organization of the class
Data you only need to issue the command touch data/a.
Subsequently, at the next icmbuild call all sources in ./data
as well as all sources in directories whose (header) files include
data.h are recompiled as well.
Likewise, if PRECOMP was defined, then a similar action is
performed for the precompiled headers: if a local header file that’s
(directly or indirectly) included by a class’s internal header file
has changed, then that class’s precompiled header as well as all
precompiled headers of dependent classes are recompiled.
The icmbuild(1) script itself does not inspect these
dependencies, but calls /usr/lib/icmake/icm-dep to perform the
requird tests. The program icm-dep’s short usage summary is
written to the standard output stream when calling icmake -d (or
All of the following #defines are required except those that are shown as
commented #defines (e.g., //#define REFRESH).
- //#define ADD_LIBRARIES ""
when a program must be linked against additional libraries (other than the
name of the program’s library itself (specified at LIBRARY)
then those libraries should be specified here. E.g., when a program is
linked against libbobcat then the specification is:
#define ADD_LIBRARIES "bobcat"
If your program is linked against multiple libraries, then use a
blank-separated list of libraries (like #define ADD_LIBRARIES
- //#define ADD_LIBRARY_PATHS ""
this directtive must be specified if ADD_LIBRARIES is also specified,
although it may be specified as an empty string. When 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.
- It is stronly advised to specify full pathnames here. Relative path
specifications can be used by specify paths relative to the directory that
is specified at the TMP_DIR directive (see below);
- //#define CLS
the clear screen directive. If defined clear is called to
clear the terminal screen before starting compilations. By default it is
not defined. Alternatively the -c option can be passed to
- #define CXX "g++"
the C++ compiler to use. For a C compiler specify, e.g.,
#define CC "gcc". Their settings are overruled by
identically named environment variables. If only C files are
compiled then #define CXX can be omitted;
- #define CXXFLAGS "--std=c++2a -Wall -O2"
C++ compiler options to use (here showing the default options). When
the C compiler is used, use #define CFLAGS rather than
CXXFLAGS. Their settings are overruled by identically named
environment variables. If only C files are compiled then #define
CXXFLAGS can be omitted;
- //#define DEFCOM "..."
a DEFCOM directive may be added to the icmconf file (the
icmstart(1) script can do this for you). It can be specified as:
#define DEFCOM "program"
in which case icmbuild does program maintenance, or as
#define DEFCOM "library"
in which case icmbuild does library maintenance.;
- //#define ICM_DEP "-V go"
the existence and implied existence of USE_ALL files (see the
description of the USE_ALL directive), as well as the correct ages
of precompiled headers can be checked by icmake’s support
program icm_dep. By default icm_dep is called with the shown
default arguments. If icm_dep should not be called define
ICM_DEP as an empty string ("").
Icmake(1)’s man-page contains a separate section about the
icm_dep support program;
- //#define IH ".ih"
the extension used for internal header files. See #define PRECOMP
below. If PRECOMP is specified ttIH) must also be specified;
- //#define LDFLAGS ""
linker options to use. By default no options are passed to the linker. Its
setting is overruled by an identically named environment variable;
- //#define LIBRARY "modules"
by defining this directive a local library is constructed. When a binary
program is built it is linked against this library rather than to the
individual object modules.
- If a library instead of a program must be constructed (see also the
DEFCOM directive), then the LIBRARY directive specifies the
library’s base name (without the lib prefix and without the
.a extension). In that case source files are expected in
sub-directories of the project’s main directory (i.e., the
directory containing icmconf). In that case avoid having source and
header files in the project’s main directory. Instead, move such
files to a separate sub-directory;
- //#define MAIN "main.cc"
the source file in which the int main function is defined. This
directive is required when doing program (rather than library)
- Note: if source files are located in the project’s main directory
but library maintenance is intended (e.g., by specifying #define
DEFCOM library) then define MAIN to specify a pseudo
main source, whose base name is the base name of the header file in the
project’s main directory. This, however, is considered a kludge,
and should be avoided by moving those source and header files to a
- //#define NO_PRECOMP_WARNING"
when PRECOMP is defined (see below) a warning is issued when a
class-directory does not contain a IH file. Such warnings are
suppressed by defining NO_PRECOMP_WARNING. This option is only
considered when PRECOMP has been defined;
- #define OBJ_EXT ".o"
this directive specifies the extension of object modules created by the
- //#define PRECOMP "-x c++-header"
define this directive to construct precompiled headers (in which case the
IH) directive must also have been specified. Dependencies between
(precompiled) headers are automatically considered.
Existing precompiled headers are removed by icmbuild
cleangch (or icmbuild clean. When source files of other languages
are compiled the PRECOMP’s -x argument must be adapted to
- //#define REFRESH
define REFRESH to relink the binary program when icmbuild
program is called, even though no file was (re)compiled. This is
useful when the program links to external libraries which were updated
separately from the currrent project;
- //#define SHARED
this directive is only interpreted when LIBRARY is also specified. If
defined a shared library (extension .so*) is built in addition to a
static library (extension .a);
The shared library receives VERSION as its version number
while soft links using VERSION’s (see below) major version
number an no version number are also made available. E.g., if VERSION
is defined as 1.02.03 and #define LIBRARY "demo"
then the shared library becomes libdemo.so.1.02.03, with
libdemo.so.1 soft-linking to it, and libdemo.so soft-linking
The following directives are available in cases where a program uses a parser
generator creating a parser class from a grammar specification. By default
they’re all commented out.
- //#define SHAREDREQ ""
when creating a shared library SHAREDREQ specifies the names of
libraries and library paths that are required by the constructed shared
library itself. 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 #define SHAREDREQ
"-L/usr/lib/special -lspecial". The /lib and
/usr/lib paths are usually automatically visited by the linker and
do not have the be specified. This directive is required (possibly as an
empty string) if SHARED is defined;
- #define SOURCES "*.cc"
the pattern to locate sources in directories;
- #define TMP_DIR "tmp"
the directory in which intermediate results are stored. To avoid
cross-device communications it’s probably best to define
TMP_DIR as a sub-directory of the project’s main
- //#define USE_ALL "a"
when defining this directive icmbuild looks for directories
containing files having the names defined by the USE_ALL
specification. All source files in those directories as well as all source
files in directories that (recursively) depend on the set of directories
under consideration are recompiled, after which the USE_ALL files
- //#define USE_ECHO ON
when defined as ON (rather than OFF) (system) commands
executed by icmbuild are echoed;
- //#define USE_VERSION
when defined (it is defined by default) a file VERSION is read by
icmconf to determine the program’s or library’s
version, and the project’s release years. The file VERSION
must be available in the project’s main directory and should
contain lines like these:
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.
By default they’re all commented out.
- //#define PARSER_DIR ""
the sub-directory containing the parser’s specification file. If the
PARSER_DIR directory is specified then all other directives in this
section must also be specified;
- //#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 is created;
- //#define PARSFLAGS "-V"
the flags that are used when calling the program specified at
- //#define PARSGEN "bisonc++"
the name of the program generating the parser;
- //#define PARSOUT "parse.cc"
the name of the file generated by the parser generator (used by
icmbuild when checking the timestamps of parser specification
- //#define PARSSPEC "grammar"
the name of the parser specification file. This file is expected in the
directory specified by the PARSER_DIR directive.
The mentioned paths are sugestive only and may be installation dependent:
- #define SCANNER_DIR ""
the subdirectory containing the scanner’s specification file. If the
SCANNER_DIR directory is specified then all other directives in
this section must also be specified;
- #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 is created. By default no
additional specification files are used;
- #define SCANFLAGS ""
the flags that are used when calling the program specified at
- #define SCANGEN "flexc++"
the name of the program generating the lexical scanner;
- #define SCANOUT "lex.cc"
the name of the file generated by the lexical scanner (which is used by
icmbuild when checking the timestamps of scanner specification
- #define SCANSPEC "lexer"
the name of the lexical scanner specification file. This file is expected in
the directory specified by the SCANNER_DIR directive.
icmake(1), icmbuild(1), icmstart(1), icmstart.rc(7).
icmbuild(1) ends, displaying a fatal error message, if the current
working directory does not contain a file icmconf.
This is free software, distributed under the terms of the GNU General Public
Frank B. Brokken (firstname.lastname@example.org).
: example of an icmconf CLASSES file;
: default (skeleton) icmbuild resource files, like main.cc,
: directory containing the default system-wide icmstart(1)
: optional user-defined 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
#define AUTHOR "Frank B. Brokken (email@example.com)";
Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.