Provided by: icmake_9.02.06-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 in
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 icmconf file it is assumed that C++ sources are
maintained, but program maintenance for, e.g., C sources can 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 in addition the maintenance of all sources in the current working
directory. `Maintenance’ involves compiling all as yet uncompiled source files,
recompilation of modified source files, and optionally library maintenance and the
pre-compilation of header files, which commonly 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 that is found in the
library. At that point the separate object files are no longer required and are removed by
icmbuild.
Up to icmake version 9.01.00 icmbuild was installed as an executable icmake script in
(commonly) /usr/bin. The dependency of this script on the file icmconf made it difficult
to provide usage information if icmconf was absent. Since version 9.02.00 the icmbuild
script has been moved to (commonly) /usr/lib/icmake, and icmbuild now is a little C
program providing the usage information when necessary or requested, but otherwise
executes icmake to process the icmbuild script.
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 in which and where below 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 at the end of the file CLASSES, but
reordering the lines in the CLASSES file should be avoided.
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 supports two options, at most one should be specified:
o -h: Display a usage summary (also automatically shown when the current directory
does not contain a file icmconf);
o -c: Clear the screen (using tput clear) before starting the maintenance process.
Next (after optionally specifying -c) icmbuild can be provided with the following
arguments:
o No arguments at all: if icmconf contains the line
#define DEFCOM "program"
then this is quivalent to the command icmbuild program;
if icmconf contains the line
#define DEFCOM "strip"
then this is quivalent to the command icmbuild strip;
if if icmconf contains the line
#define DEFCOM "library"
then this is quivalent to the command icmbuild library.
(these commands are further elaborated in this section.) DEFCOM specifications are
ignored when an explicit argument is passed to icmbuild.
o clean
clean up remnants of previous actions;
o install program <path>
install the constructed program in the specified <path> (to be used after issuing
icmbuild program, see below). Example:
icmbuild install ~/bin/program
This installs the constructed binary program in the user’s bin direcotry with the
name program;
o install static <path>
install the constructed static library in the specified path (to be used after
issuing icmbuild library, see below). Example:
icmbuild static /usr/lib/
This installs the constructed static library (e.g. libspecial.a) in /usr/lib as
/usr/lib/libspecial.a.
o install shared path install the constructed shared library in the specified path
(to be used after issuing icmbuild library), when icmconf defines SHARED (cf.
icmconf(7)). Example:
icmbuild 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 library
do library maintenance (builds a static and optionally (if icmconf defines SHARED)
a shared (dynamic) library);
o 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 program strip
same as program, but the final program is stripped (using the linker’s -s option);
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 changed 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 uses 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 all such class dependencies, and will recompile 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 will perform all its duties (and verbose messages
are displayed as if go had been specified), but no files (precompiled headers or USE_ALL
files) will be 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++14 -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).