.TH "icmbuild" "1" "1992\-2023" "icmake\&.10\&.04\&.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 that\(cq\&s (commonly) found in
\fI/usr/lib/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 \fBC++\fP sources are maintained, but program maintenance for,
e\&.g\&., \fBC\fP sources can also easily be configured\&. If \fIicmbuild\fP is called, but
\fIicmconf\fP is not available it displays a usage\-summary after which icm()
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 the pre\-compilation of header files, which normally results in
a marked reduction of source compilation times\&.
.PP 
When source files are compiled object modules are produced which may be stored
in a library, against which the object module 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 
Note that the order of the classes mentioned in \fICLASSES\fP \fIis\fP
relevant in that new class (subdirectory) names can always be added to
the end of the file \fICLASSES\fP, but reordering the lines in the
\fICLASSES\fP file should be avoided as that may easily result 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 
.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 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 by passing it the option
\fI\-d\fP\&. All options and arguments following \fI\-d\fP are forwared to
\fIicm\-dep\fP\&.
.PP 
The program \fIicm\-dep\fP is automatically called by \fIicmbuild\fP to handle
class dependencies\&. Consider two classes \fIOptions\fP and \fIProcess\fP\&. If
\fIProcess\fP uses \fIOptions\fP and if precompiled header files are used, then in
addition to \fIOption\(cq\&s\fP header file, \fIProcess\(cq\&s\fP header must also be
precompiled if \fIOption\(cq\&s\fP header file changes\&. Likewise, if \fIOption\(cq\&s\fP
data organization is altered and \fIOption\fP defines inline members used by
\fIProcess\fP or \fIProcess\fP defines an \fIOption\fP data member then, in addition
to \fIOption\(cq\&s\fP sources sources \fIProcess\(cq\&s\fP sources must also be
compiled\&. For the latter case \fIicmconf\fP provides the \fIUSE_ALL\fP
specification: if a \fI`USE_ALL\(cq\&\fP file exists in a directory, then all sources
of that directory are recompiled\&.
.PP 
The program \fIicm_dep\fP determines the program\(cq\&s class dependencies, and
recompiles class header files of all classes depending on classes whose header
files must be recompiled\&. Furthermore, if a \fI`USE_ALL\(cq\&\fP file exists in a
directory then all sources of classes depending on that directory\(cq\&s class are
also recompiled\&.
.PP 
\fIIcm\-dep\(cq\&s\fP options are described in \fBicmake\fP(1)\(cq\&s man\-page\&.
.PP 
To start its work, \fIicm_dep\fP needs one command\-line argument:
\fIgo\fP\&. Any other argument results in \fIicm_dep\fP performing a `dry run\(cq\&: it
performs all its duties (and verbose messages are displayed as if \fIgo\fP
had been specified), but no files (precompiled headers or \fIUSE_ALL\fP files)
are touched or removed\&. If neither options nor arguments are specified
\fIicm_dep\fP writes its usage summary to the standard output\&.
.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\&modules\(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\& \-\-std=c++20 \-Wall \-O2 \-pthread\(dq\& \(dq\& \-fdiagnostics\-color=never \(dq\&
    #define IH                  \(dq\&\&.ih\(dq\&
    #define PRECOMP             \(dq\&\-x c++\-header\(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