icmconf(7)

configuration file for icmbuild(1)
(icmake.9.03.01.tar.gz)

1992-2020

NAME

icmconf - Configuration file for the icmbuild(1) program maintenance script

DESCRIPTION

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

CLASS DEPENDENCIES

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 directly: /usr/lib/icmake/icm-dep).

DEFINES IN ICMCONF

All of the following #defines are required except those that are shown as commented #defines (e.g., //#define REFRESH).

. 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 those languages;

  • //#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 to libdemo.so.1;

  • //#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 directory;

  • //#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 are removed;

  • //#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:
    
        VERSION=9.03.00
        YEARS=1992-2020
          
    
    )

    PARSER MAINTENANCE

    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.

    SCANNER MAINTENANCE

    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.

    FILES

    The mentioned paths are sugestive only and may be installation dependent:

    SEE ALSO

    icmake(1), icmbuild(1), icmstart(1), icmstart.rc(7).

    BUGS

    icmbuild(1) ends, displaying a fatal error message, if the current working directory does not contain a file icmconf.

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