.TH "icmconf" "7" "1992\-2018" "icmake\&.9\&.02\&.07\&.tar\&.gz" "configuration file for \fBicmbuild\fP(1)"

.PP 
.SH "NAME"
icmconf \- Configuration file for the \fBicmbuild\fP(1) 
program maintenance script
.PP 
.SH "DESCRIPTION"

.PP 
The \fIicmconf\fP configuration file is used to specify and fine\-tune the
program maintenance performed by the \fBicmbuild\fP(1) script\&. It can be used to
activate and specify various directives that determine how the program or
library maintenance is performed\&.
.PP 
The directives are biased towards the construction of a \fBC++\fP program, but
program maintenance for other languages (e\&.g\&., \fBC\fP) can also easily be
configured\&.
.PP 
The \fBicmbuild\fP(1) script ignores empty lines and lines whose first non\-blank
characters are two consecutive forward slashes (//)\&. Long lines can be split
over multiple lines by using a final backslash character at lines continuing
at the next line (refer to the \fBicmake\fP(1) man\-page for further details)\&.
.PP 
.SH "CLASS DEPENDENCIES"

.PP 
Traditional make\-utilities recompile all dependent sources once header files
are modified\&. When developing \fBC++\fP programs this is hardly ever requird, as
adding a new member function to a class does not require you to recompile
already existing source files\&. Recompilation \fIis\fP required when modifying
the data member organization of classes\&. 
.PP 
To handle class dependencies in a more sensible way, \fBicmake\fP(1) checks
class dependencies using its support program \fI/usr/lib/icmake/icm\-dep\fP,
visiting the classes listed in the \fICLASSES\fP file if \fIicmconf\(cq\&s USE_ALL\fP
directive was specified\&. If a directory mentioned in the \fICLASSES\fP file
contains a file having a name that\(cq\&s equal to the name specified at the
\fIUSE_ALL\fP parameter, then all sources of classes that depend on that
particular class are also recompiled\&.
.PP 
Likewise, if the \fIPRECOMP\fP parameter was specified, then a similar action is
performed for the precompiled headers: if a local header file that\(cq\&s (directly
or indirectly) included by a class\(cq\&s internal header file has changed, then
that class\(cq\&s precompiled header as well as all precompiled headers of
dependent classes are recompiled\&.
.PP 
The \fBicmbuild\fP(1) script itself does not inspect these dependencies, but
calls \fI/usr/lib/icmake/icm\-dep\fP to perform the requird tests\&. The program
\fIicm\-dep\(cq\&s\fP short usage summary is written to the standard output stream
when calling \fIicmake \-d\fP (or directly: \fI/usr/lib/icmake/icm\-dep\fP)\&.
.PP 
.SH "ICMCONF PARAMETERS"

.PP 
.IP o 
\fB#define ADD_LIBRARIES       \(dq\&\(dq\&\fP
.br 
When a program must be linked against additional libraries (other than
the name of the program\(cq\&s library itself, if specified at \fILIBRARY\fP)
then those libraries should be specified, blank space separated,
here\&. E\&.g\&., when a program is linked against \fIlibbobcat\fP then the
specification is:
.nf 

    #define ADD_LIBRARIES   \(dq\&bobcat\(dq\&
    
.fi 
If your program is linked against multiple libraries, then use a
blank\-separated list of libraries (like \fI\(dq\&math bobcat\(dq\&\fP)
.IP 
.IP o 
\fB#define ADD_LIBRARY_PATHS  \(dq\&\(dq\&\fP
.br 
When the additional libraries (specified at \fIADD_LIBRARIES\fP) are
located in non\-standard library locations (e\&.g\&., not in \fI/lib\fP and
\fI/usr/lib\fP) then these additional paths are (blank space separated)
specified here\&. Specify only the paths, not the \fI\-L\fP flags\&.
.IP 
It is stronly advised to specify full pathnames here, or remember that
normally the location of the \fIicmconf\fP file is not the location
where the compilation actually takes place, which is the location
specified at the \fITMP_DIR\fP parameter (see below)\&.
.IP 
.IP o 
\fB#define CLS\fP
.br 
The \fIclear screen\fP directive\&. If defined \fItput clear\fP is called to
clear the terminal screen before starting the compilation\&. By default
it is not defined\&.
.IP 
.IP o 
\fB#define CXX                 \(dq\&g++\(dq\&\fP
.br 
The C++ compiler to use\&. For a \fBC\fP compiler use, e\&.g\&., \fI#define CC
\(dq\&gcc\(dq\&\fP\&. Its setting is overruled by an identically named environment
variable\&.
.IP 
.IP o 
\fB#define CXXFLAGS            \(dq\&\-\-std=c++14 \-Wall \-O2\(dq\&\fP
.br 
The compiler options to use\&. The default options are shown\&. When the
\fBC\fP compiler is used, use \fI#define CFLAGS\fP rather than
\fICXXFLAGS\fP\&. Its setting is overruled by an identically named
environment variable\&.
.IP 
.IP o 
\fB#define DEFCOM  \(dq\&\&.\&.\&.\(dq\&\fP
.br 
A \fIDEFCOM\fP directive may be added to the \fIicmconf\fP file (the
\fBicmstart\fP(1) script can do this for you)\&. It may be defined as:
.nf 

    #define DEFCOM  \(dq\&program\(dq\&
        
.fi 
in which case \fIicmbuild\fP will do program maintenance\&.  It may also be
defined as:
.nf 

    #define DEFCOM  \(dq\&program strip\(dq\&
        
.fi 
in which case \fIicmbuild\fP does program maintenance, creating a
stripped binary program\&. 
.IP 
Alternatively it may also be defined as:
.nf 

    #define DEFCOM  \(dq\&library\(dq\&
       
.fi 
in which case \fIicmbuild\fP does library maintenance\&. 
.IP 
.IP o 
\fB//#define ICM_DEP           \(dq\&\-V go\(dq\&\fP
.br 
The existence and implied existence of \fIUSE_ALL\fP files (see the
description of the \fIUSE_ALL\fP directive), as well as the correct ages
of precompiled headers can be checked by \fIicmake\(cq\&s\fP support program
\fIicm_dep\fP\&. By default \fIicm_dep\fP is called with the shown
default arguments\&. If \fIicm_dep\fP should not be called define
\fIICM_DEP\fP as an empty string (\fI\(dq\&\(dq\&\fP)\&. \fBIcmake\fP(1)\(cq\&s man\-page
contains a separate section about the \fIicm_dep\fP support program\&.
.IP 
.IP o 
\fB#define IH                  \(dq\&\&.ih\(dq\&\fP
.br 
The extension used for internal header files\&. See \fI#define PRECOMP\fP
below\&. 
.IP 
.IP o 
\fB#define LDFLAGS             \(dq\&\(dq\&\fP
.br 
The linker options to use\&. By default no options are passed to the
linker\&. Its setting is overruled by an identically named environment
variable\&.
.IP 
.IP o 
\fB#define LIBRARY           \(dq\&modules\(dq\&\fP
.br 
By default this directive is not defined\&. If defined a local library is
constructed\&. When a binary program is built it will be linked against
this library rather than to the individual object modules\&. 
.IP 
If a library must be constructed (see also the \fIDEFCOM\fP directive),
then the \fILIBRARY\fP directive must specify the library\(cq\&s base name
(without the \fIlib\fP prefix and without the \fI\&.a\fP extension)\&.
.IP 
After a library has been constructed \fIicmbuild install static dir\fP
installs the static library at \fIdir\fP, while \fIicmbuild install
shared dir\fP installs the shared library (see below at \fI#define
SHARED\fP) at \fIdir\fP\&.
.IP 
.IP o 
\fB#define MAIN                \(dq\&main\&.cc\(dq\&\fP
.br 
The source file in which the \fIint main\fP function is defined\&. This
specification may be left as\-is or may completely be removed if
\fBicmbuild\fP(1) is used for library maintenance rather than program
maintenance\&.
.IP 
.IP o 
\fB//#define NO_PRECOMP_WARNING\(dq\&\fP
.br 
When \fIPRECOMP\fP is defined (see below) a warning is issued when a
class\-directory does not contain a \fIIH\fP file\&. Such warnings are
suppressed when defining \fINO_PRECOMP_WARNING\fP\&. This option is
ignored unless \fIPRECOMP\fP has been defined\&.
.IP 
.IP o 
\fB#define OBJ_EXT             \(dq\&\&.o\(dq\&\fP
.br 
The extension of object modules created by the compiler\&.
.IP 
.IP o 
\fB//#define PRECOMP           \(dq\&\-x c++\-header\(dq\&\fP
.br 
When activated internal header files (see \fI#define IH\fP) are
precompiled when they are more recent than their precompiled
versions\&. Also, when a precompiled header file is (re)compiled the
precompiled header files of all dependent classes are also
recompiled\&. 
.IP 
Precompiled headers are removed by \fIicmbuild clean\fP\&. To specify
internal header files for other languages change the \fI\-x\fP
specification accordingly\&. By default this \fI#define\fP is not active\&.
.IP 
.IP o 
\fB#define REFRESH\fP
.br 
Define \fIREFRESH\fP to relink the binary program at every \fIicmbuild
program\fP call\&. By default \fIREFRESH\fP is \fInot\fP defined\&.
.IP 
.IP o 
\fB#define SHARED\fP
.br 
This directive is only interpreted if \fILIBRARY\fP was also specified\&.
If defined a static library (extension \fI\&.a\fP) as well as a shared
library (extension \fI\&.so*\fP) is built\&. If not specified, but
\fILIBRARY\fP was specified, only the static library is built\&. By
default \fISHARED\fP is not defined\&.
.IP 
The shared library receives as its major version number \fIVERSION\fP\(cq\&s
major version number, and receives \fIVERSION\fP as its full version
number\&. E\&.g\&., if \fIVERSION\fP is defined as \fI1\&.02\&.03\fP and \fILIBRARY\fP
is defined as \fIdemo\fP then the shared library \fIlibdemo\&.so\&.1\&.02\&.03\fP
is constructed, with \fIlibdemo\&.so\&.1\fP soft\-linking to it, with
\fIlibdemo\&.so\fP in turn soft\-linking to \fIlibdemo\&.so\&.1\fP\&.
.IP 
.IP o 
\fB#define SHAREDREQ           \(dq\&\(dq\&\fP
.br 
When creating a shared library \fISHAREDREQ\fP specifies the names of
libraries and library paths that are required by the shared library\&.
E\&.g\&., if a library is found in \fI/usr/lib/special\fP, assuming that the
name of the required library is \fIlibspecial\&.so\fP, then use the
specification \fI\(dq\&\-L/usr/lib/special \-lspecial\(dq\&\fP\&.  The \fI/lib\fP and
\fI/usr/lib\fP paths are usually predefined and need not be
specified\&. This directive is only interpreted if \fISHARED\fP and
\fILIBRARY\fP were also defined\&.
.IP 
.IP o 
\fB#define SOURCES             \(dq\&*\&.cc\(dq\&\fP
.br 
The pattern to locate sources in a directory\&. The default value is
shown\&. 
.IP 
.IP o 
\fB#define TMP_DIR             \(dq\&tmp\(dq\&\fP
.br 
The directory in which intermediate results are stored\&. Relative to the
current working directory unless an absolute path is specified\&.
.IP 
.IP o 
\fB#define USE_ALL     \(dq\&a\(dq\&\fP
.br 
After defining this directive (by default it is \fInot\fP defined) class
dependencies are interpreted\&. In this case, when a directory contains
a file having a name that\(cq\&s equal to the name specified at the
\fIUSE_ALL\fP directive, then all sources of that class as well as all
sources of classes that depend on it are (re)compiled\&. 
.IP 
Following the successful recompilations the \fBs\fP specified at
\fI#define USE_ALL\fP are removed\&.
.IP 
When the \fIUSE_ALL\fP directive was specified the command \fIicmbuild
clean\fP also removes any leftover \fIUSE_ALL\fP files from the program\(cq\&s
subdirectories\&.
.IP 
.IP o 
\fB#define USE_ECHO              ON\fP
.br 
When specified as \fION\fP (rather than \fIOFF\fP) commands executed by
\fIicmbuild\fP are echoed\&.
.IP 
.IP o 
\fB#define USE_VERSION\fP
.br 
If defined (which is the default) the file \fIVERSION\fP is read by
\fIicmconf\fP to determine the program/library\(cq\&s version, and the
project\(cq\&s release years\&.

.PP 
.SH "PARSER MAINTENANCE"

.PP 
The following directives are available in cases where  a program uses a parser
generator creating a parser class from a grammar specification:
.PP 
.IP o 
\fB#define PARSER_DIR          \(dq\&\(dq\&\fP
.br 
The subdirectory containing the parser\(cq\&s specification file\&. 
.IP 
If parser maintenance is not required, then this directive can be
omitted\&. If omitted, then all other directives, that begin with
\fIPARS\fP, can also be omitted\&.
.IP 
.IP o 
\fB#define PARSFILES           \(dq\&\(dq\&\fP
.br 
If the parser specification file named at \fIPARSSPEC\fP itself includes
additional specification files, then patterns matching these
additional grammar specification files should be specified here\&. The
pattern is interpreted in the directory specified at \fIPARSER_DIR\fP
and could contain a subdirectory name (e\&.g\&. \fIspecs/*\fP)\&. When files
matching the pattern are modified then a new parser will be
created\&. By default no additional specification files are used\&.
.IP 
.IP o 
\fB#define PARSFLAGS           \(dq\&\-V\(dq\&\fP
.br 
The flags to use when calling the program specified at \fIPARSGEN\fP\&.
.IP 
.IP o 
\fB#define PARSGEN             \(dq\&bisonc++\(dq\&\fP
.br 
The name of the program generating the parser\&.
.IP 
.IP o 
\fB#define PARSOUT             \(dq\&parse\&.cc\(dq\&\fP
.br 
The name of the file generated by the parser generator (which is used
by \fIicmbuild\fP to compare the timestamps of the parser specification
\fBs\fP against)\&.
.IP 
.IP o 
\fB#define PARSSPEC            \(dq\&grammar\(dq\&\fP
.br 
The name of the parser specification file\&. This file is
expected in the directory specified at \fIPARSER_DIR\fP\&.

.PP 
.SH "SCANNER MAINTENANCE"

.PP 
The following directives are available in cases where  a program uses a scanner
generator creating a lexical scanner class from a set of regular expressions:
.PP 
.IP o 
\fB#define SCANNER_DIR         \(dq\&\(dq\&\fP
.br 
The subdirectory containing the scanner\(cq\&s specification file\&. 
.IP 
If lexical scanner maintenance is not required, then this directive
can be omitted\&. If omitted, then all other directives, that begin with
\fISCAN\fP, can also be omitted\&.
.IP 
.IP o 
\fB#define SCANFILES            \(dq\&\(dq\&\fP
.br 
If the lexical scanner specification file named at \fISCANSPEC\fP itself
includes additional specification files, then patterns matching these
additional lexer specification files should be specified here\&. The
pattern is interpreted in the directory specified at \fISCANNER_DIR\fP
and could contain a subdirectory name (e\&.g\&. \fIspecs/*\fP)\&. When files
matching the pattern are modified then a new lexical scanner will be
created\&. By default no additional specification files are used\&.
.IP 
.IP o 
\fB#define SCANFLAGS           \(dq\&\(dq\&\fP
.br 
The flags to use when calling the program specified at \fISCANGEN\fP\&.
.IP 
.IP o 
\fB#define SCANGEN             \(dq\&flexc++\(dq\&\fP
.br 
The name of the program generating the lexical scanner\&.
.IP 
.IP o 
\fB#define SCANOUT             \(dq\&lex\&.cc\(dq\&\fP
.br 
The name of the file generated by the lexical scanner (which is used by
\fIicmbuild\fP to compare the timestamps of the scanner specification
\fBs\fP against)\&.
.IP 
.IP o 
\fB#define SCANSPEC            \(dq\&lexer\(dq\&\fP
.br 
The name of the lexical scanner specification file\&. This file is
expected in the directory specified at \fISCANNER_DIR\fP\&.

.PP 
.SH "FILES"
The mentioned paths are sugestive only and may be installation dependent:
.IP o 
\fB/usr/share/icmake/CLASSES\fP
.br 
Example of an \fBicmconf\fP \fICLASSES\fP file\&.
.IP o 
\fB/usr/share/icmake/icmconf\fP
.br 
Default skeleton \fBicmbuild\fP resource file\&.
.IP o 
\fB/etc/icmake\fP
.br 
Directory containing the default system\-wide \fBicmake\fP(1)
configuration files (like \fIVERSION\fP and \fIicmstart\&.rc\fP)
.IP o 
\fB$HOME/\&.icmake\fP
.br 
Optional directory containing user\-defined specifications overruling
the system\-wide definitions\&. This directory is the proper location for
a file \fIAUTHOR\fP defining the \fIAUTHOR\fP directive with the user\(cq\&s
name\&. E\&.g\&., my \fI\&.icmake/AUTHOR\fP file contains:
.IP 
.nf 
#define AUTHOR  \(dq\&Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl)\(dq\&;

.fi 

.IP 
.SH "SEE ALSO"
\fBicmake\fP(1), \fBicmbuild\fP(1), \fBicmstart\fP(1), \fBicmstart\&.rc\fP(7)\&.
.PP 
.SH "BUGS"
\fBicmbuild\fP(1) ends displaying a fatal error message if the current
working directory does not contain a file \fIicmconf\fP\&.
.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