NAMEicmconf - Configuration file for the icmbuild(1) program maintenance script
DESCRIPTIONThe icmconf configuration file is used to specify and tailor the characteristics of program maintenance performed by the icmbuild(1) icmake script. It can be used to activate and specify various directives that determine how the program or library maintenance will proceed. The directives are biased towards the construction of a C++ program, but program maintenance for other languages (e.g., C) can easily be realized as well.
PROGRAM AND SOURCE CONFIGURATIONo #define MAIN "main.cc" The specification of the file defining the int main function. This specification may be left as-is if icmbuild(1) is used for library maintenance rather than program maintenance. o #define BINARY "binary" The name of the binary program. Can be left as-is if the intent is to construct a library rather than a program. Don't specify a path here. The installation path can be specified at the BIN_INSTALL directive (see below) o #define REFRESH By defining REFRESH the binary program is always relinked, even when no sources were modified. This can be useful if, e.g., a separate library was rebuilt against which the program must be linked. By default REFRESH is not defined. o #define BIN_INSTALL "/usr/local/bin" This directive specifies the location where icmbuild install will install the binary program.
LIBRARY CONSTRUCTIONo #define LIBRARY "modules" By default this directive is not defined. If defined a local library is defined. When a binary program is built it will be linked against the library rather than the individual object modules. If library construction is required (see below at the DEFCOM directive), then the LIBRARY directive defines the name of the library that is built. Change the library's name at your own digression. Don't use lib or an extension like .a. o #define SHARED This directive is only interpreted if LIBRARY was also specified. If SHARED is defined a static library (extension .a) as well as a shared library (extension .so) is built. If not specified only the static library is built. By default SHARED is not defined. o #define SHAREDREQ "" When creating a shared library: Specify the names of any libraries and library paths that are required by the shared library between the double quotes. E.g., if a library is found in /usr/lib/special use "-L/usr/lib/special -lspecial" assuming that the name of the required library is libspecial.so. The /lib and /usr/lib paths are usually predefined and need not be specified. This directive is only interpreted if SHARED and LIBRARY were also defined. o #define LIB_INSTALL "/usr/local/lib" This directive specifies the location where icmbuild install will install the library (libraries). By default it is not specified. It should only be specified if LIBRARY was also specified.
COMPILING AND LINKINGo #define CLS The clear screen directive. If defined tput clear is called to clear the terminal screen before starting the compilation. By default it is not defined. o #define USE_ALL "ALL" When this directive is specified (by default it is not specified) a class dependency setup defined in the CLASSES file will be used. In this case, when a directory contains a file named at the USE_ALL directive (the default icmconf file pre-specifies the filename ALL) then all sources of that class as well as all sources of all classes depending on it are (re)compiled. Class dependencies in CLASSES consist of the class name (as the first word on a line) optionally followed by additional class names, which are the classes directly depending on the line's first class name. Assuming that a program uses five classes One, Two, Three, Four and five and that class Three depends on class Two, which in turn depends on class One, while class Five depends on Four and Two, then the file CLASSES may reflect these dependencies: one two one three two four five two four Creating the file three/ALL (using e.g., touch three/ALL) will cause all sources of the classes Three, Two and One to be recompiled. Creating five/ALL will cause all sources of classes Five, Four, Two and One to be recompiled. This facility was added to the icmbuild script because C++ header files are often modified without the need to recompile all their depending sources. No recompilation is necessary when a new class member is declared. Recompilation is necessary when the class's internal organization changes, e.g., when the organization of its data members is modified. By simply creating a file ALL the required recompilations will be performed. Following the recompilation the ALL s are removed. Note also that when the USE_ALL directive is used the command icmbuild clean also removes any leftover USE_ALL files from the program's direct subdirectories. o #define COMPILER "g++" This directive defines the compiler to use. The default is shown. o #define COMPILER_OPTIONS "--std=c++0x -g -Wall -O2" This directive defines the compiler options to use. The default flags are shown. To enable GNU extensions in addition to the compiler's C++0x extensions, add the --std=gnu++0x flag. o #define SOURCES "*.cc" This directive defines the pattern to locate sources in a directory. Its default value is shown. o #define LINKER_OPTIONS "-s" This directive defines the options the compiler should pass to the linker. Its default value is shown. o #define ADD_LIBRARIES "" When a program (see BINARY above) must be linked against additional libraries (other than the name of the program's library itself, if specified at LIBRARY) then those libraries should be specified, blank space separated, here. E.g., when a program is linked against libbobcat then the specification is: #define ADD_LIBRARIES "bobcat" o #define ADD_LIBRARY_PATHS "" When the additional libraries (specified at ADD_LIBRARIES) are located in non-standard library locations (e.g., not in /lib and /usr/lib) then these additional paths are (blank space separated) specified here. Only the paths should be specified, not the -L flags.
LEXICAL SCANNERSWhen a program uses a lexical scanner, generated by a scanner generator like flex(1), the icmbuild script can be used to update the scanner source whenever the scanner specification file is modified. Here are the directives that are related to the use of a lexical scanner generator: o #define SCANNER_DIR "" If a lexical scanner must be constructed, then the subdirectory containing the scanner's specification file is specified with this directive. If empty (the default) no scanner construction is monitored by icmbuild and all remaining scanner-related directives are ignored. o #define SCANGEN "flex" The name of the program generating the lexical scanner. o #define SCANFLAGS "-I" The flags to use when calling the program specified at SCANGEN. o #define SCANSPEC "lexer" The name of the lexical scanner specification file. This file is expected in the directory specified at SCANNER_DIR. o #define SCANFILES "" If the lexical scanner specification file named at SCANSPEC 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 SCANNER_DIR and could contain a subdirectory name (e.g. specs/*). When files matching the pattern are modified then a new lexical scanner will be created. By default no additional specification files are used. o #define SCANOUT "yylex.cc" The name of the file generated by the lexical scanner (which is used by icmbuild to compare the timestamps of the scanner specification s against).
GRAMMAR PARSERSWhen a program uses a grammar parser, generated by a parser generator like bisonc++(1), the icmbuild script can be used to update the parser's sources whenever a parser specification file is modified. Here are the directives that are related to the use of a parser generator: o #define PARSER_DIR "" If a parser must be constructed, then the subdirectory containing the parser's specification file is specified with this directive. If empty (the default) no parser construction is monitored by icmbuild and all remaining parser-related directives are ignored. o #define PARSGEN "bisonc++" The name of the program generating the parser. o #define PARSFLAGS "-V -l" The flags to use when calling the program specified at PARSGEN. o #define PARSSPEC "grammar" The name of the parser specification file. This file is expected in the directory specified at PARSER_DIR. o #define PARSFILES "" If the parser specification file named at PARSSPEC 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 PARSER_DIR and could contain a subdirectory name (e.g. specs/*). When files matching the pattern are modified then a new parser will be created. By default no additional specification files are used. o #define PARSOUT "parse.cc" The name of the file generated by the parser generator (which is used by icmbuild to compare the timestamps of the parser specification s against). o #define GRAMBUILD Since bisonc++ version 2.0.0 this directive is obsolete, but is kept for backward compatibility. It is removed from the icmconf skeleton file. The PARSEFILES directive overrules the use of GRAMBUILD.
ADDITIONAL DIRECTIVESo #define USE_VERSION When this directive is specified (which is the default) the file VERSION will be read by icmconf to determine the version of the program, the program release years and the program's author name. The default VERSION file generated by icmstart defines AUTHOR, VERSION and YEARS. o #define DEFCOM "..." A DEFCOM directive may be added to the icmconf file by icmstart. If added, it may be defined as #define DEFCOM "program" in which case icmbuild will do program maintenance. It may also be defined as as #define DEFCOM "library" in which case icmbuild will de library maintenance. If this directive was not added by icmstart it can always be added to icmconf by hand. The following directives usually require no tweaking: o #define USE_ECHO ON When specified as ON (rather than OFF) commands executed by icmbuild are echoed. o #define TMP_DIR "tmp" The directory in which intermediate results are stored. Relative to the current working directory unless an absolute path is specified. o #define OBJ_EXT ".o" The extension of object modules created by the compiler.
FILESThe mentioned paths are sugestive only and may be installation dependent: o /usr/share/icmake/CLASSES Example of an icmconf CLASSES file. o /usr/share/icmake/icmconf Default skeleton icmbuild resource file. o /etc/icmake Directory containing the default system-wide icmake(1) configuration files (like VERSION and icmstart.rc) o $HOME/.icmake Optional directory containing user-defined specifications overruling the system-wide definitions. This directory is the proper location for a file AUTHOR defining the AUTHOR directive with the user's name. E.g., my .icmake/AUTHOR file contains: #define AUTHOR "Frank B. Brokken (firstname.lastname@example.org)";
SEE ALSOicmake(1), icmbuild(1), icmstart(1), icmstart.rc(7).
COPYRIGHTThis is free software, distributed under the terms of the GNU General Public License (GPL).
AUTHORFrank B. Brokken (email@example.com). ICMCONF(7)