.TH "icmbuild" "1" "1992\-2026" "icmake\&.13\&.07\&.00" "Icmake\(cq\&s generic program maintenance facility"

.PP 
.SH "NAME"
icmbuild \- A generic, C++/C program maintenance facility
.PP 
.SH "SYNOPSIS"
\fIicmbuild\fP [\-h] [\-c] \fIargs\fP
.PP 
.SH "DESCRIPTION"

.PP 
\fIIcmbuild\fP is a small \fBC++\fP program calling \fBicmake\fP(1) to do program
maintenance as defined by the \fIicmbuild\fP script (commonly found in
\fI/usr/libexec/icmake\fP)\&.
.PP 
\fIIcmbuild\(cq\&s\fP actions are tailored through a configuration file (\fIicmconf\fP)
which must be present in the directory where program maintenance is
requested\&. This file is automatically installed by \fBicmstart\fP(1)\&. Refer to
\fBicmconf\fP(7)\(cq\&s man\-page for details about this file\&.
.PP 
\fIIcmbuild\fP assumes that your sources exist in and below the current working
directory\&. The file \fIicmconf\fP in \fBicmake\fP(1)\(cq\&s distribution provides an
example of an \fIicmconf\fP file that can be used by \fIicmbuild\fP\&. In that example it
is assumed that a \fBC++\fP project is maintained, but program maintenance for,
e\&.g\&., a \fBC\fP project can also easily be configured\&. If \fIicmbuild\fP is called, but
\fIicmconf\fP is not available it displays a usage\-summary after which \fIicmbuild\fP
ends\&.
.PP 
\fIIcmbuild\fP() handles the maintenance for all sources in each of the subdirectories
named in the file \fICLASSES\fP, and also of all sources in the current working
directory\&. `Maintenance\(cq\& involves compiling all as yet uncompiled source
files, recompilation of modified source files, optionally library maintenance
and optionally constructing a Single Pre\-Compiled Header (SPCH) and
multi\-threaded source file compilation, resulting in a marked reduction
of source compilation times\&.
.PP 
When source files are compiled object files result which may be stored
in a library, against which the object file of the program\(cq\&s \fImain\fP
function is linked\&. It is also possible to specify additional libraries
against which the program must be linked\&.
.PP 
If a library is constructed it is kept up to date by \fIicmbuild\fP\&. 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 \fIicmbuild\fP\&.
.PP 
.SH "KICK\-STARTING ICMBUILD"

.PP 
To use \fIicmbuild\fP do as follows:
.IP o 
Install \fIicmbuild\fP in your path (\fIicmake\(cq\&s\fP installation procedure
should already have taken care of that);
.IP o 
Copy \fIicmconf\fP (and probably a file \fICLASSES\fP) to your
project\(cq\&s base directory (i\&.e\&., the directory where and below which 
the project\(cq\&s sources are found)\&. Usually this has already been taken
care of by the (icmstart) script;

.PP 
Next:
.IP o 
Modify the \fI#defines\fP in the file \fIicmconf\fP to taste;
.IP 
.IP o 
Enter the names of subdirectories containing sources on separate
lines in the file \fICLASSES\fP
.IP 
When the \fIOBJ_SEP\fP define is not specified (cf\&. \fBicmconf\fP(7)) then
the ordering of the classes in the \fICLASSES\fP file \fIis\fP
important\&. The ordering should not be modified but new class
(subdirectory) names can always be added to the end of the file
\fICLASSES\fP\&. Reordering the lines in the \fICLASSES\fP file should be
avoided as that most likely results in overwriting identically named
object files from already existing directories\&.
.IP 
If reordering is necessary, then first run the command \fIicmbuild
clean\fP to remove all files that were thus far created by
\fIicmbuild\fP\&. 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 \fIdata\&.cc\fP) and because of the number\-prefixes replacement of a
file \fIx\&.o\fP from class \fIA\fP by file \fIx\&.o\fP from class \fIB\fP is
prevented;
.IP 
When the \fIOBJ_SEP\fP define is specified the names of subdirectories in
the \fICLASSES\fP file can be reordered\&. In this case the names of
object files start with the source files\(cq\& subdirectory names, followed
by the character specified by the \fIOBJ_SEP\fP define, followed by the
files\(cq\& base names, followed by the extension specified by the
\fIOBJ_EXT\fP define\&. E\&.g\&., if a source file \fIappend\&.cc\fP is defined in
the subdirectory \fIprocess\fP then its object file, assuming \fI#define
OBJ_SEP \(dq\&,\(dq\&\fP was defined, is named \fIprocess,append\&.o\fP\&. For source
files defined in the program\(cq\&s top\-level directory there is no
subdirectory\&. E\&.g\&., for \fImain\&.cc\fP the \fI,main\&.o\fP object file is
generated\&.
.IP 
.IP o 
Start \fIicmbuild\fP\&.

.PP 
The next section covers \fIicmbuild\(cq\&s\fP  modes of operation\&.
.PP 
.SH "OPTIONS"

.PP 
\fIIcmbuild\fP recognizes three options of which only one can be specified\&. See the
following section for information about which option is recognized by which
\fIicmbuild\fP command\&.
.IP o 
\fI\-h\fP: display usage information (which is also automatically shown when
the current directory does not contain a file \fIicmconf\fP) and
terminate \fIicmbuild\fP;
.IP o 
\fI\-c\fP: clear the screen (by calling \fItput clear\fP) before starting 
the compilation process;
.IP o 
\fI\-s\fP: strip the compiled program or library at its installation
directory (see the various \fIinstall\fP modes below)\&.

.PP 
.SH "ICMBUILD COMMANDS"

.PP 
\fIIcmbuild\fP recognizes the following commands (possible options are shown
between square brackets)\&. With the \fIinstall\fP commands a \fIpath\fP
argument must be specified, which must be an existing user\-writable
directory:
.IP o 
\fIclean\fP
.br 
clean up remnants of previous actions (the directory specified by the
\fITMP_DIR\fP define in \fIicmconf\fP is removed)\&. If precompiled headers
were created (i\&.e\&., \fIPRECOMP\fP in \fIicmconf\fP was specified) then all
files having extension \fI\&.gch\fP in the main directory and in the
directories listed in the \fICLASSES\fP file are also removed\&. If
\fIUSE_ALL\fP was specified then those files are also removed;
.IP 
.IP o 
\fIcleangch\fP
.br 
all \fI\&.gch\fP files that were precompiled are removed (whether existing
in the \fIgch\fP subdirectory of the \fITMP_DIR\fP directory (specified in
\fIicmconf\fP), or in directories specified in the \fICLASSES\fP file, or
in the project\(cq\&s main directory)\&. If \fIicmconf\fP does not specify
\fIPRECOMP\fP then nothing happens;
.IP 
.IP o 
\fIcleantmp\fP
.br 
same as \fIicmbuild clean\fP, but the \fI\&.gch\fP files and files specified
by the \fIUSE_ALL\fP define in \fIicmconf\fP are not removed;
.IP 
.IP o 
\fI[\-s] install program path\fP
.br 
install the constructed program in the specified \fIpath\fP (to be used
after issuing \fIicmbuild\fP \fIprogram\fP, see below)\&. Path can be absolute or
relative and may optionally specify the name of the installed
program\&. Example: 
.nf 

    icmbuild install program ~/bin/prog
            
.fi 
This installs the constructed binary program in the user\(cq\&s \fIbin\fP
directory with the name \fIprog\fP;
.IP 
.IP o 
\fI[\-s] install static path\fP
.br 
install the constructed static library in the specified path (to be
used after issuing \fIicmbuild\fP \fIlibrary\fP, see below)\&.  Path can be
absolute or relative and may optionally specify the name of the
installed library\&. Example:
.nf 

    icmbuild install static /usr/lib/
       
.fi 
This installs the constructed static library (assume its name is
\fIlibspecial\&.a\fP) in \fI/usr/lib\fP as \fI/usr/lib/libspecial\&.a\fP\&.
.br 

.IP 
.IP o 
\fI[\-s] install shared path\fP 
when using this installation command, \fIicmconf\fP must contain
\fI#define SHARED\fP (cf\&. \fBicmconf\fP(7))\&. It installs the constructed
shared library in the specified path (to be used after issuing \fIicmbuild\fP
\fIlibrary\fP)\&. Path can be absolute or relative, and must specify an
existing directory\&. Example: 
.nf 

    icmbuild install shared /usr/lib/
       
.fi 
This installs the constructed binary shared library
(e\&.g\&. \fIlibspecial\&.so\fP) in \fI/usr/lib\fP as
\fI/usr/lib/libspecial\&.so\fP\&. In addition, the soft\-links
.nf 

    libspecial\&.so \-> libspecial\&.so\&.X
    libspecial\&.so\&.X \-> libspecial\&.so\&.X\&.Y\&.Y\&.Z 
            
.fi 
are defined in \fI/usr/lib\fP, where \fIX\&.Y\&.Z\fP are the major, minor and
subminor versions defined in the file \fIVERSION\fP\&.
.IP 
.IP o 
\fI[\-c] library\fP
.br 
do library maintenance (builds a static and optionally (if \fIicmconf\fP
defines \fISHARED\fP) a shared (dynamic) library); 
.IP 
.IP o 
\fI[\-c] program\fP
.br 
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 \fICLASSES\fP);
.IP 
.IP o 
If no commands are specified (but optionally only \fI\-c\fP)
then the \fIDEFCOM\fP specification in the \fIicmconf\fP is
inspected\&. Recognized specifications are: 
.nf 

    #define DEFCOM \(dq\&program\(dq\&
        
.fi 
which is quivalent to the command \fIicmbuild\fP \fI[\-c] program\fP;
.br 
if \fIDEFCOM\fP is specified as 
.nf 

    #define DEFCOM \(dq\&library\(dq\&
        
.fi 
then this is quivalent to the command \fIicmbuild\fP \fI[\-c] library\fP\&.
.br 

.IP 
If an explicit command is passed to \fIicmbuild\fP then \fIDEFCOM\fP
specifications are ignored\&.

.PP 
.SH "ICM\-DEP"

.PP 
Class dependencies are handled by \fIicmake\fP\(cq\&s support program
\fIicm\-dep\fP\&. It can be called from \fIicmake\fP when specifying option
\fI\-d\fP\&. All options and arguments following \fI\-d\fP are forwared to
\fIicm\-dep\fP\&.
.PP 
The program \fBicm\-dep\fP is automatically called by \fIicmbuild\fP to handle
class dependencies\&. Refer to the \fBicmake\fP(1) manpage, section \fBICM\-DEP\fP
for a description of the \fBicm\-dep\fP program\&.
.PP 
By default \fIicmbuild\fP calls \fIicmake \-d \-V go\fP: \fIicm_dep\fP is called to
perform its duties and to show its actions on the standard output stream\&. By
specifying a \fI#define ICM_DEP\fP parameter in the \fIicmconf\fP file this
default can be overruled (cf\&. \fBicmconf\fP(7))\&.
.PP 
.SH "FILES"

.PP 
The mentioned paths are sugestive only and may be installation dependent:
.IP o 
\fB/usr/share/icmake/icmconf\fP
Unabbreviated example of an \fIicmbuild\fP configuration file;
.IP o 
\fB/usr/share/icmake/CLASSES\fP
Example of an \fIicmbuild\fP \fICLASSES\fP file\&.

.PP 
.SH "EXAMPLES"

.PP 
Here is an example of the configuration file \fIicmconf\fP for a concrete
program, using facilities of the \fIbobcat\fP library:
.nf 

    #define CLS
    #define LIBRARY             \(dq\&ofiles\(dq\&
    #define MAIN                \(dq\&main\&.cc\(dq\&
    #define SOURCES             \(dq\&*\&.cc\(dq\&
    #define OBJ_EXT             \(dq\&\&.o\(dq\&
    #define SHAREDREQ           \(dq\&\(dq\&
    #define TMP_DIR             \(dq\&tmp\(dq\&
    #define USE_ALL             \(dq\&a\(dq\&
    #define USE_ECHO              ON
    #define CXX                 \(dq\&g++\(dq\&
    #define CXXFLAGS            \(dq\&\-Wall \-Werror \-O2\(dq\&
    #define IH                  \(dq\&\&.ih\(dq\&
    #define MULTICOMP           \(dq\&jobs \-q\(dq\&
    #define SPCH                \(dq\&\(dq\&
    #define REFRESH
    #define LDFLAGS             \(dq\&\(dq\&
    #define ADD_LIBRARIES       \(dq\&bobcat\(dq\&
    #define ADD_LIBRARY_PATHS   \(dq\&\(dq\&
    
    #define DEFCOM              \(dq\&program\(dq\&
        
.fi 

.PP 
.SH "SEE ALSO"
\fBicmake\fP(1), \fBicmconf\fP(7), \fBicmstart\fP(1), \fBicmstart\&.rc\fP(7)
.PP 
.SH "BUGS"
None reported
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP