icmconf(7)

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