includefile(release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(sop)(3)(\
    it() bf(-ARG1) ARG2 nl()ARG3\
)

DEFINEMACRO(itt)(1)(\
    it()tt(ARG1)\
)

DEFINEMACRO(itb)(1)(\
    it()bf(ARG1)nl()\
)

DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))

COMMENT( man-request, section, date, distribution file, general name)
manpage(icmconf)(7)(_CurYrs_)(icmake._CurVers_.tar.gz)
        (configuration file for bf(icmbuild)(1))

COMMENT( man-request, larger title )
manpagename(icmconf)(Configuration file for the bf(icmbuild)(1) 
                    program maintenance script)

manpagedescription()

The tt(icmconf) configuration file is used to specify and fine-tune the
program maintenance performed by the bf(icmbuild)(1) 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 bf(C++) program, but
program maintenance for other languages (e.g., bf(C)) can also easily be
configured.

The bf(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 using a final backslash character at lines continuing
at the next line (refer to the bf(icmake)(1) man-page for further details).

manpagesection(CLASS DEPENDENCIES)

Traditional make-utilities recompile all dependent sources once header files
are modified. When developing bf(C++) programs this is hardly ever requird, as
adding a new member function to a class does not require you to recompile
already existing source files. Recompilation em(is) required when modifying
the data member organization of classes. 

To handle class dependencies in a more sensible way, bf(icmake)(1) checks
class dependencies using its support program tt(/usr/lib/icmake/icm-dep),
visiting the classes listed in the tt(CLASSES) file if tt(icmconf's USE_ALL)
directive was specified. If a directory mentioned in the tt(CLASSES) file
contains a file having a name that's equal to the name specified at the
tt(USE_ALL) parameter, then all sources of classes that depend on that
particular class are also recompiled.

Likewise, if the tt(PRECOMP) parameter was specified, 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 bf(icmbuild)(1) script itself does not inspect these dependencies, but
calls tt(/usr/lib/icmake/icm-dep) to perform the requird tests. The program
tt(icm-dep's) short usage summary is written to the standard output stream
when calling tt(icmake -d) (or directly: tt(/usr/lib/icmake/icm-dep)).

manpagesection(ICMCONF PARAMETERS)

    itemization(
    itb(#define ADD_LIBRARIES       "")
       When a program must be linked against additional libraries (other than
        the name of the program's library itself, if specified at tt(LIBRARY))
        then those libraries should be specified, blank space separated,
        here. E.g., when a program is linked against tt(libbobcat) then the
        specification is:
    verb(
    #define ADD_LIBRARIES   "bobcat"
    )
        If your program is linked against multiple libraries, then use a
    blank-separated list of libraries (like tt("math bobcat"))

    itb(#define ADD_LIBRARY_PATHS  "")
       When the additional libraries (specified at tt(ADD_LIBRARIES)) are
        located in non-standard library locations (e.g., not in tt(/lib) and
        tt(/usr/lib)) then these additional paths are (blank space separated)
        specified here. Specify only the paths, not the tt(-L) flags.

        It is stronly advised to specify full pathnames here, or remember that
        normally the location of the tt(icmconf) file is not the location
        where the compilation actually takes place, which is the location
        specified at the tt(TMP_DIR) parameter (see below).

    itb(#define CLS)
       The em(clear screen) directive. If defined tt(tput clear) is called to
        clear the terminal screen before starting the compilation. By default
        it is not defined.

    itb(#define CXX                 "g++")
       The C++ compiler to use. For a bf(C) compiler use, e.g., tt(#define CC
        "gcc"). Its setting is overruled by an identically named environment
        variable.

    itb(#define CXXFLAGS            "--std=c++14 -Wall -O2")
       The compiler options to use. The default options are shown. When the
        bf(C) compiler is used, use tt(#define CFLAGS) rather than
        tt(CXXFLAGS). Its setting is overruled by an identically named
        environment variable.

    itb(#define DEFCOM  "...")
       A tt(DEFCOM) directive may be added to the tt(icmconf) file (the
        bf(icmstart)(1) script can do this for you). It may be defined as:
       verb(
    #define DEFCOM  "program"
        )
       in which case tt(icmbuild) will do program maintenance.  It may also be
        defined as:
       verb(
    #define DEFCOM  "program strip"
        )
       in which case tt(icmbuild) does program maintenance, creating a
        stripped binary program. 

       Alternatively it may also be defined as:
       verb(
    #define DEFCOM  "library"
       )
        in which case tt(icmbuild) does library maintenance. 

    itb(//#define ICM_DEP           "-V go")
       The existence and implied existence of tt(USE_ALL) files (see the
        description of the tt(USE_ALL) directive), as well as the correct ages
        of precompiled headers can be checked by tt(icmake's) support program
        tt(icm_dep). By default tt(icm_dep) is called with the shown
        default arguments. If tt(icm_dep) should not be called define
        tt(ICM_DEP) as an empty string (tt("")). bf(Icmake)(1)'s man-page
        contains a separate section about the tt(icm_dep) support program.

    itb(#define IH                  ".ih")
       The extension used for internal header files. See tt(#define PRECOMP)
        below. 

    itb(#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.

    itb(#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 must be constructed (see also the tt(DEFCOM) directive),
        then the tt(LIBRARY) directive must specify the library's base name
        (without the tt(lib) prefix and without the tt(.a) extension).

       After a library has been constructed tt(icmbuild install static dir)
        installs the static library at tt(dir), while tt(icmbuild install
        shared dir) installs the shared library (see below at tt(#define
        SHARED)) at tt(dir).

    itb(#define MAIN                "main.cc")
       The source file in which the tt(int main) function is defined. This
        specification may be left as-is or may completely be removed if
        bf(icmbuild)(1) is used for library maintenance rather than program
        maintenance.

    itb(//#define NO_PRECOMP_WARNING")
       When tt(PRECOMP) is defined (see below) a warning is issued when a
        class-directory does not contain a tt(IH) file. Such warnings are
        suppressed when defining tt(NO_PRECOMP_WARNING). This option is
        ignored unless tt(PRECOMP) has been defined.

    itb(#define OBJ_EXT             ".o")
        The extension of object modules created by the compiler.

    itb(//#define PRECOMP           "-x c++-header")
       When activated internal header files (see tt(#define IH)) are
        precompiled when they are more recent than their precompiled
        versions. Also, when a precompiled header file is (re)compiled the
        precompiled header files of all dependent classes are also
        recompiled. 

        Precompiled headers are removed by tt(icmbuild clean). To specify
        internal header files for other languages change the tt(-x)
        specification accordingly. By default this tt(#define) is not active.

    itb(#define REFRESH)
       Define tt(REFRESH) to relink the binary program at every tt(icmbuild
        program) call. By default tt(REFRESH) is em(not) defined.

    itb(#define SHARED)
       This directive is only interpreted if tt(LIBRARY) was also specified.
        If defined a static library (extension tt(.a)) as well as a shared
        library (extension tt(.so*)) is built. If not specified, but
        tt(LIBRARY) was specified, only the static library is built. By
        default tt(SHARED) is not defined.

       The shared library receives as its major version number tt(VERSION)'s
        major version number, and receives tt(VERSION) as its full version
        number. E.g., if tt(VERSION) is defined as tt(1.02.03) and tt(LIBRARY)
        is defined as tt(demo) then the shared library tt(libdemo.so.1.02.03)
        is constructed, with tt(libdemo.so.1) soft-linking to it, with
        tt(libdemo.so) in turn soft-linking to tt(libdemo.so.1).

    itb(#define SHAREDREQ           "")
       When creating a shared library tt(SHAREDREQ) specifies the names of
        libraries and library paths that are required by the shared library.
        E.g., if a library is found in tt(/usr/lib/special), assuming that the
        name of the required library is tt(libspecial.so), then use the
        specification tt("-L/usr/lib/special -lspecial").  The tt(/lib) and
        tt(/usr/lib) paths are usually predefined and need not be
        specified. This directive is only interpreted if tt(SHARED) and
        tt(LIBRARY) were also defined.

    itb(#define SOURCES             "*.cc")
       The pattern to locate sources in a directory. The default value is
        shown. 

    itb(#define TMP_DIR             "tmp")
       The directory in which intermediate results are stored. Relative to the
        current working directory unless an absolute path is specified.

    itb(#define USE_ALL     "a")
       After defining this directive (by default it is em(not) defined) class
        dependencies are interpreted. In this case, when a directory contains
        a file having a name that's equal to the name specified at the
        tt(USE_ALL) directive, then all sources of that class as well as all
        sources of classes that depend on it are (re)compiled. 

        Following the successful recompilations the file(s) specified at
        tt(#define USE_ALL) are removed.

        When the tt(USE_ALL) directive was specified the command tt(icmbuild
        clean) also removes any leftover tt(USE_ALL) files from the program's
        subdirectories.

    itb(#define USE_ECHO              ON)
        When specified as tt(ON) (rather than tt(OFF)) commands executed by
        tt(icmbuild) are echoed.

    itb(#define USE_VERSION)
       If defined (which is the default) the file tt(VERSION) is read by
        tt(icmconf) to determine the program/library's version, and the
        project's release years.
    )

manpagesection(PARSER MAINTENANCE)

The following directives are available in cases where  a program uses a parser
generator creating a parser class from a grammar specification:

    itemization(
    itb(#define PARSER_DIR          "")
       The subdirectory containing the parser's specification file. 

        If parser maintenance is not required, then this directive can be
        omitted. If omitted, then all other directives, that begin with
        tt(PARS), can also be omitted.

    itb(#define PARSFILES           "")
       If the parser specification file named at tt(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 tt(PARSER_DIR)
        and could contain a subdirectory name (e.g. tt(specs/*)). When files
        matching the pattern are modified then a new parser will be
        created. By default no additional specification files are used.

    itb(#define PARSFLAGS           "-V")
       The flags to use when calling the program specified at tt(PARSGEN).

    itb(#define PARSGEN             "bisonc++")
       The name of the program generating the parser.

    itb(#define PARSOUT             "parse.cc") 
       The name of the file generated by the parser generator (which is used
        by tt(icmbuild) to compare the timestamps of the parser specification
        file(s) against).

    itb(#define PARSSPEC            "grammar")
       The name of the parser specification file. This file is
        expected in the directory specified at tt(PARSER_DIR).
    )

manpagesection(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:

    itemization(
    itb(#define SCANNER_DIR         "")
       The subdirectory containing the scanner's specification file. 

        If lexical scanner maintenance is not required, then this directive
        can be omitted. If omitted, then all other directives, that begin with
        tt(SCAN), can also be omitted.

    itb(#define SCANFILES            "")
       If the lexical scanner specification file named at tt(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 tt(SCANNER_DIR)
        and could contain a subdirectory name (e.g. tt(specs/*)). When files
        matching the pattern are modified then a new lexical scanner will be
        created. By default no additional specification files are used.

    itb(#define SCANFLAGS           "")
       The flags to use when calling the program specified at tt(SCANGEN).

    itb(#define SCANGEN             "flexc++")
       The name of the program generating the lexical scanner.

    itb(#define SCANOUT             "lex.cc")
       The name of the file generated by the lexical scanner (which is used by
        tt(icmbuild) to compare the timestamps of the scanner specification
        file(s) against).

    itb(#define SCANSPEC            "lexer")
       The name of the lexical scanner specification file. This file is
        expected in the directory specified at tt(SCANNER_DIR).
    )

manpagefiles()
    The mentioned paths are sugestive only and may be installation dependent:
    itemization(
    itb(/usr/share/icmake/CLASSES)
        Example of an bf(icmconf) tt(CLASSES) file.
    itb(/usr/share/icmake/icmconf)
        Default skeleton bf(icmbuild) resource file.
    itb(/etc/icmake)
        Directory containing the default system-wide bf(icmake)(1)
        configuration files (like tt(VERSION) and tt(icmstart.rc))
    itb($HOME/.icmake) 
       Optional directory containing user-defined specifications overruling
        the system-wide definitions. This directory is the proper location for
        a file tt(AUTHOR) defining the tt(AUTHOR) directive with the user's
        name. E.g., my tt(.icmake/AUTHOR) file contains:

        verbinclude(/home/frank/.icmake/AUTHOR)

    )

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

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

includefile(trailer.inc)
