icmbuild(1)

Icmake's generic program maintenance facility
(icmake.11.01.02)

1992-2024

NAME

icmbuild - A generic, C++/C program maintenance facility

SYNOPSIS

icmbuild [-h] [-c] args

DESCRIPTION

Icmbuild is a small C++ program calling icmake(1) to do program maintenance as defined by the icmbuild script that's (commonly) found in /usr/libexec/icmake.

Icmbuild's actions are tailored through a configuration file (icmconf) which must be present in the directory where program maintenance is requested. This file is automatically installed by icmstart(1). Refer to icmconf(7)'s man-page for details about this file.

Icmbuild assumes that your sources exist in and below the current working directory. The file icmconf in icmake(1)'s distribution provides an example of an icmconf file that can be used by icmbuild. In that example it is assumed that C++ sources are maintained, but program maintenance for, e.g., C sources can also easily be configured. If icmbuild is called, but icmconf is not available it displays a usage-summary after which icm() ends.

Icmbuild() handles the maintenance for all sources in each of the subdirectories named in the file CLASSES, and also of all sources in the current working directory. `Maintenance' involves compiling all as yet uncompiled source files, recompilation of modified source files, optionally library maintenance and optionally the pre-compilation of header files, which normally results in a marked reduction of source compilation times.

When source files are compiled object modules are produced which may be stored in a library, against which the object module of the program's main function is linked. It is also possible to specify additional libraries against which the program must be linked.

If a library is constructed it is kept up to date by icmbuild. When a source is successfully compiled its new object module replaces the old one in the library. At that point the separate object files are no longer required and are removed by icmbuild.

KICK-STARTING ICMBUILD

To use icmbuild do as follows:

Next:

The next section covers icmbuild's modes of operation.

OPTIONS

Icmbuild recognizes three options of which only one can be specified. See the following section for information about which option is recognized by by which icmbuild command.

ICMBUILD COMMANDS

Icmbuild recognizes the following commands (possible options are shown between square brackets). With the install commands a path argument must be specified, which must be an existing user-writable directory:

ICM-DEP

Class dependencies are handled by icmake's support program icm-dep. It can be called from icmake by passing it the option -d. All options and arguments following -d are forwared to icm-dep.

The program icm-dep is automatically called by icmbuild to handle class dependencies. Consider two classes Options and Process. If Process uses Options and if precompiled header files are used, then in addition to Option's header file, Process's header must also be precompiled if Option's header file changes. Likewise, if Option's data organization is altered and Option defines inline members used by Process or Process defines an Option data member then, in addition to Option's sources sources Process's sources must also be compiled. For the latter case icmconf provides the USE_ALL specification: if a `USE_ALL' file exists in a directory, then all sources of that directory are recompiled.

The program icm_dep determines the program's class dependencies, and recompiles class header files of all classes depending on classes whose header files must be recompiled. Furthermore, if a `USE_ALL' file exists in a directory then all sources of classes depending on that directory's class are also recompiled.

Icm-dep's options are described in icmake(1)'s man-page.

To start its work, icm_dep needs one command-line argument: go. Any other argument results in icm_dep performing a `dry run': it performs all its duties (and verbose messages are displayed as if go had been specified), but no files (precompiled headers or USE_ALL files) are touched or removed. If neither options nor arguments are specified icm_dep writes its usage summary to the standard output.

By default icmbuild calls icmake -d -V go: icm_dep is called to perform its duties and to show its actions on the standard output stream. By specifying a #define ICM_DEP parameter in the icmconf file this default can be overruled (cf. icmconf(7)).

FILES

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

EXAMPLES

Here is an example of the configuration file icmconf for a concrete program, using facilities of the bobcat library:


    #define CLS
    #define LIBRARY             "modules"
    #define MAIN                "main.cc"
    #define SOURCES             "*.cc"
    #define OBJ_EXT             ".o"
    #define SHAREDREQ           ""
    #define TMP_DIR             "tmp"
    #define USE_ALL             "a"
    #define USE_ECHO              ON
    #define CXX                 "g++"
    #define CXXFLAGS            " --std=c++20 -Wall -O2 -pthread" " -fdiagnostics-color=never "
    #define IH                  ".ih"
    #define PRECOMP             "-x c++-header"
    #define REFRESH
    #define LDFLAGS             ""
    #define ADD_LIBRARIES       "bobcat"
    #define ADD_LIBRARY_PATHS   ""
    
    #define DEFCOM              "program"
        

SEE ALSO

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

BUGS

None reported

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