Provided by: icmake_9.03.01-1_amd64 
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/lib/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:
o Install icmbuild in your path (icmake’s installation procedure should already have taken care of
that);
o Copy icmconf (and probably a file CLASSES) to your project’s base directory (i.e., the directory
where and below which the project’s sources are found). Usually this has already been taken care
of by the (icmstart) script;
Next:
o Modify the #defines in the file icmconf to taste;
o Enter the names of subdirectories containing sources on separate lines in the file CLASSES
Note that the order of the classes mentioned in CLASSES is relevant in that new class
(subdirectory) names can always be added to the end of the file CLASSES, but reordering the lines
in the CLASSES file should be avoided as that may easily result in overwriting identically named
object files from already existing directories.
If reordering is necessary, then first run the command icmbuild clean to remove all files that
were thus far created by icmbuild. Recompilation is necessary as the names of the object files
contain class order-numbers for identification. These class-order numbers prevent file-name
collisions (e.g., two classes might use a file data.cc) and because of the number-prefixes
replacement of a file x.o from class A by file x.o from class B is prevented;
o Start icmbuild.
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.
o -h: display usage information (which is also automatically shown when the current directory does
not contain a file icmconf) and terminate icmbuild;
o -c: clear the screen (by calling tput clear) before starting the compilation process;
o -s: strip the compiled program or library at its installation directory (see the various install
modes below).
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:
o clean
clean up remnants of previous actions (the directory specified by the TMP_DIR define in icmconf is
removed). If precompiled headers were created (i.e., PRECOMP in icmconf was specified) then all
files having extension .gch in the main directory and in the directories listed in the CLASSES
file are also removed. If USE_ALL was specified then those files are also removed;
o cleangch
all .gch files that were precompiled are removed (whether existing in the gch subdirectory of the
TMP_DIR directory (specified in icmconf), or in directories specified in the CLASSES file, or in
the project’s main directory). If icmconf does not specify PRECOMP then nothing happens;
o cleantmp
same as icmbuild clean, but the .gch files and files specified by the USE_ALL define in icmconf
are not removed;
o [-s] install program path
install the constructed program in the specified path (to be used after issuing icmbuild program,
see below). Path can be absolute or relative and may optionally specify the name of the installed
program. Example:
icmbuild install program ~/bin/prog
This installs the constructed binary program in the user’s bin directory with the name prog;
o [-s] install static path
install the constructed static library in the specified path (to be used after issuing icmbuild
library, see below). Path can be absolute or relative and may optionally specify the name of the
installed library. Example:
icmbuild install static /usr/lib/
This installs the constructed static library (assume its name is libspecial.a) in /usr/lib as
/usr/lib/libspecial.a.
o [-s] install shared path when using this installation command, icmconf must contain #define SHARED
(cf. icmconf(7)). It installs the constructed shared library in the specified path (to be used
after issuing icmbuild library). Path can be absolute or relative, and must specify an existing
directory. Example:
icmbuild install shared /usr/lib/
This installs the constructed binary shared library (e.g. libspecial.so) in /usr/lib as
/usr/lib/libspecial.so. In addition, the soft-links
libspecial.so -> libspecial.so.X
libspecial.so.X -> libspecial.so.X.Y.Y.Z
are defined in /usr/lib, where X.Y.Z are the major, minor and subminor versions defined in the
file VERSION.
o [-c] library
do library maintenance (builds a static and optionally (if icmconf defines SHARED) a shared
(dynamic) library);
o [-c] program
do program maintenance (builds a program from the sources in the current working directory and
from the sources in the directories specified in the file CLASSES);
o If no commands are specified (but optionally only -c) then the DEFCOM specification in the icmconf
is inspected. Recognized specifications are:
#define DEFCOM "program"
which is quivalent to the command icmbuild [-c] program;
if DEFCOM is specified as
#define DEFCOM "library"
then this is quivalent to the command icmbuild [-c] library.
If an explicit command is passed to icmbuild then DEFCOM specifications are ignored.
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:
o /usr/share/icmake/icmconf Unabbreviated example of an icmbuild configuration file;
o /usr/share/icmake/CLASSES Example of an icmbuild CLASSES file.
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++2a -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).