--- name: "icmconf" section: "7" platform: "linux" package: "icmake" version: "13.07.00-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/icmconf" --- # icmconf(7) Configuration file for the icmbuild(1) program maintenance script ## NAME icmconf - Configuration file for the [**icmbuild**(1)](/icmbuild/1.md) program maintenance script ## DESCRIPTION The *icmconf* configuration file is used to configure program maintenance performed by [**icmbuild**(1)](/icmbuild/1.md). It uses various directives determining how the program or library maintenance is performed. *Icmconf’s* directives are biased towards the construction of **C++** programs, but program maintenance for other languages (e.g., **C**) can also easily be configured. The [**icmbuild**(1)](/icmbuild/1.md) script ignores empty lines and lines whose first non-blank characters are two consecutive forward slashes (//) or start with a hash-character (*#*). Long lines can be split over multiple lines by writing a final backslash character at lines continuing at the next line. ## CLASS DEPENDENCIES Traditional make-utilities recompile all dependent sources once header files are modified. When developing **C++** programs this is hardly ever requird, as adding new member functions to classes does not require you to recompile already existing source files. Recompilation *is* required when the data member organization of classes is altered. To handle class dependencies in a more sensible way, [**icmake**(1)](/icmake/1.md) checks class dependencies using its support programs *icm-dep*, visiting the classes listed in the *CLASSES* file if *icmconf’s USE\_ALL* directive was specified. If a directory mentioned in the *CLASSES* file contains a file having a name equal to the name specified at the *USE\_ALL* parameter, then all sources of classes that depend on that particular class are also recompiled. In practice this means that when you change the data organization of a class you only need to *touch* it that directory the file whose name was specified by the *USE\_ALL* directive. E.g., if your class is named *Data*, its sources are in the sub-directory *./data*, and *#define USE\_ALL "a"* was specified then after modifying the data organization of the class *Data* you only need to issue the command *touch data/a*. Subsequently, at the next *icmbuild* call all sources in *./data* as well as all sources in directories whose (header) files include *data.h* are recompiled as well. Likewise, if *#define SPCH* or (deprecated) *#define PRECOMP* was used, a similar action is performed for the precompiled headers: if a local file that’s (directly or indirectly) included by internal header files has changed, then the Single Pre-Compiled Header (SPCH) file is recompiled (or (deprecated), having specified *PRECOMP* the modified class headers are recompiled). The [**icmbuild**(1)](/icmbuild/1.md) script itself does not inspect these dependencies, but calls the support programs *icm-spch* and *icm-dep* to perform the requird tests. The usage summaries of these programs are written to the standard output stream when calling, respectively **icmake** *-S* and **icmake** *-d*. ## DEFAULT DEFINE SPECIFICATIONS The following *#defines*, except for those that are shown as commented (e.g., *//#define REFRESH*) are required. - o **//#define ADD\_LIBRARIES ""**\ when a program must be linked against additional libraries (other than the name of the program’s library itself (cf. *LIBRARY*, below) then those libraries should be specified here. E.g., when a program is linked against *libbobcat* then the specification is: ``` #define ADD_LIBRARIES "bobcat" ``` If your program is linked against multiple libraries, then use a blank-separated list of libraries (like *#define ADD\_LIBRARIES "bobcat math"*); - - o **//#define ADD\_LIBRARY\_PATHS ""**\ this directtive must be specified if *ADD\_LIBRARIES* is also specified, although it may be specified as an empty string. When 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. Specify only the paths, not the *-L* flags. - It is stronly advised to specify full pathnames here. Relative path specifications can be used by specifying paths relative to the directory that is specified at the *TMP\_DIR* directive (see below); - - o **//#define CLS**\ the *clear screen* directive. If defined *tput clear* is called to clear the terminal screen before starting compilations. By default it is not defined. Alternatively the *-c* option can be passed to *icmbuild*; - - o **#define CXX "g++"**\ the C++ compiler to use. For a **C** compiler specify, e.g., *#define* *CC "gcc"*. Their settings are overruled by identically named environment variables. If only **C** files are compiled then *#define CXX* can be omitted. - By specifying, e.g., **#define CXX "ccache g++"** compilations use caching facilities, which may impressively reduce recompilation times. Refer to the **cccache**(1) man-page for details. - - o **#define CXXFLAGS "-Werror -Wall -O2"**\ **C++** compiler options to use (here showing the default options). When the **C** compiler is used, use *#define CFLAGS* rather than *CXXFLAGS*. Their settings are overruled by identically named environment variables. If only **C** files are compiled then *#define CXXFLAGS* can be omitted. - Additional options can be defined by adding them to the CXXFLAGS definition. In addition, compilations use the environment variable *ICMAKE\_CPPSTD* to set the **C++** standard to use. E.g., after defining ``` ICMAKE_CPPSTD=--std=c++26 ``` the compiler uses the options ``` --std=c++26 -Werror -Wall -O2 ``` - - o **//#define DEFCOM "..."**\ a *DEFCOM* directive may be added to the *icmconf* file (the [**icmstart**(1)](/icmstart/1.md) script can do this for you). It can be specified as: ``` #define DEFCOM "program" ``` in which case *icmbuild* does program maintenance, or as ``` #define DEFCOM "library" ``` in which case *icmbuild* does library maintenance.; - - o **//#define ICM\_DEP "-V go"**\ the existence and implied existence of *USE\_ALL* files (see the description of the *USE\_ALL* directive). When the (deprecated) *PRECOMP* directive is specified the recency of precompiled headers is ensured (see also the *SPCH* description, below). By default *icm\_dep* is called with the shown default arguments. If *icm\_dep* should not be called define *ICM\_DEP* as an empty string (*""*). **Icmake**(1)’s man-page contains a separate section about the *icm\_dep* support program; - - o **#define IH ".ih"**\ the extension used for internal header files. See *#define SPCH* below. If *SPCH* is specified the ttI#define H) directive must also be specified; - - o **//#define LDFLAGS ""**\ linker options to use. By default no options are passed to the linker. Its setting is overruled by an identically named environment variable; - - o **//#define LIBRARY "ofiles"**\ by defining this directive a local library (*libofiles.a*) is constructed. When a binary program is built it is linked against this library rather than to the individual object files. - If a library instead of a program must be constructed (see also the *DEFCOM* directive), then the *LIBRARY* directive specifies the library’s base name (without the *lib* prefix and without the *.a* extension). In that case source files are expected in sub-directories of the project’s main directory (i.e., the directory containing *icmconf*). In that case avoid having source and header files in the project’s main directory. Instead, move such files to a separate sub-directory; - - o **//#define MAIN "main.cc"**\ the source file in which the *int main* function is defined. This directive is required when doing program (rather than library) maintenance. - Note: if source files are located in the project’s main directory but library maintenance is intended (e.g., by specifying *#define DEFCOM* *library*) then define *MAIN* to specify a pseudo main source, whose base name is the base name of the header file in the project’s main directory. This, however, is considered a kludge, and should be avoided by moving those source and header files to a separate sub-directory; - - o **//#define MULTICOMP "..."**\ \ Example: *#define MULTICOMP "jobs -q"* - This directive activates threaded compilation of source files. When used its first word specifies the name of a file to contain information about which files must be compiled. This must be a plain filename, not containing directory specifiers (like */*). Refer to the [**icmake**(1)](/icmake/1.md) man-page’s section *ICM-MULTICOMP* covering options, arguments, and usage of **icm-multicomp** which is called when *#define MULTICOMP* is specified; - - o **//#define NO\_PRECOMP\_WARNING"**\ when *#define PRECOMP* (now deprecated) is specified (see below) a warning is issued when a class-directory does not contain a *IH* file. Such warnings are suppressed by defining *NO\_PRECOMP\_WARNING*. This option is only considered when *#define* *PRECOMP* is specified; - - o **#define OBJ\_EXT ".o"**\ this directive specifies the extension of object modules created by the compiler; - - o **//#define OBJ\_SEP ","**\ When *OBJ\_SEP* is specified the names of subdirectories in the *CLASSES* file can be reordered. In this case the names of object files start with the source files’ subdirectory names, followed by the character specified by the *OBJ\_SEP* define, followed by the files’ base names, followed by the extension specified by the *OBJ\_EXT* define. E.g., if a source file *append.cc* is defined in the subdirectory *process* then its object file, assuming *#define* *OBJ\_SEP ","* was defined, is named *process,append.o*. For source files defined in the program’s top-level directory there is no subdirectory. E.g., for *main.cc* the *,main.o* object file is generated. - - o **//#define PRECOMP "-x c++-header"**\ (deprecated, consider declaring *#define SPCH* instead) \ define this directive to construct class-specific pre-compiled headers (in which case the *IH*) directive must also be specified. Dependencies between (precompiled) headers are automatically considered.\ Existing precompiled headers are removed by *icmbuild cleangch* (or *icmbuild clean*. When source files of other languages are compiled the *PRECOMP’s -x* argument must be adapted to those languages; - o **//#define REFRESH**\ define *REFRESH* to relink the binary program when *icmbuild* *program* is called, even when no file was (re)compiled. This is useful when the program links to external libraries which were updated separately from the currrent project; - o **//#define SHARED**\ this directive is only interpreted when *LIBRARY* is also specified. If defined a shared library (extension *.so\**) is built in addition to a static library (extension *.a*);\ The shared library receives *VERSION* as its version number while soft links using *VERSION*’s (see below) major version number an no version number are also made available. E.g., if *VERSION* is defined as *1.02.03* and *#define LIBRARY "demo"* then the shared library becomes *libdemo.so.1.02.03*, with *libdemo.so.1* soft-linking to it, and *libdemo.so* soft-linking to *libdemo.so.1*; - o **//#define SHAREDREQ ""**\ when creating a shared library *SHAREDREQ* specifies the names of libraries and library paths that are required by the constructed shared library itself. E.g., if a library is found in */usr/lib/special*, assuming that the name of the required library is *libspecial.so*, then use the specification *#define SHAREDREQ* *"-L/usr/lib/special -lspecial"*. The */lib* and */usr/lib* paths are usually automatically visited by the linker and do not have the be specified. This directive is required (possibly as an empty string) if *SHARED* is defined; - o **#define SOURCES "\*.cc"**\ the pattern to locate sources in directories; - o **//#define SPCH "..."**\ \ Example: *#define SPCH ""*\ If *#define SPCH* is specified then *#define IH* must also be specified.\ This directive activates the construction of a Single Pre-Compiled Header (SPCH). Refer to the [**icmake**(1)](/icmake/1.md) man-page, section **ICM-SPCH** for specific details and options when constructing a SPCH. The argument string can be empty, or it can contain specifications which are used when constructing a SPCH. The *--internal* (or *-i*) option should not be specified as it is used by default when calling **icmake -S**.\ By default the (*g++*) command constructing the SPCH is echoed to the standard output stream. This can be suppressed by specifying *--quiet* (or *-q*) in the *SPCH* string (e.g., *#define SPCH* *"-q"*). Additional options for the compiler can be specified using *--option* (or *-o*) specifications. - o **//#define SPCH\_ARGS "..."**\ \ Example: *#define SPCH\_ARGS "specs f:compiler"*\ In practice the *#define SPCH\_ARGS* specification is hardly ever required. It requires the specification of the *#define SPCH* directive. Refer to the [**icmake**(1)](/icmake/1.md) man-page, section **ICM-SPCH** for specific details about this specification.\ The first word (*specs*) defines the name of the file (used by **icmake -S**) to contain the names of the headers used when constructing the SPCH. If *SPCH\_ARGS* is not specified then **icmake -S** by default uses *specs*. When *SPCH\_ARGS* is used the specified name must be a plain filename, not containing directory specifiers (like */*) or an extension.\ The second word (here: *f:compiler*) is optional, but when provided defines the file containing the compiler-command to use when constructing the SPCH. By default the SPCH is constructed using the following command (all on one line): ``` g++ -c -o $2 ${ICMAKE_CPPSTD} -Wall -Werror -O2 -x c++-header $1 ``` To the compiler-command options specified by *-o* specifications provided in the *#define SPCH* string are added. It is also possible (but probably less convenient) to specify the command directly as *SPCH\_ARGS’s* second word. In that case surround the command by *\\\\’* (two backslashes and a quote) characters to ensure that the multi-word specification is interpreted by **icmake -S** as a single argument. - o **#define TMP\_DIR "tmp"**\ the directory in which intermediate results are stored. To avoid cross-device communications it’s probably best to define *TMP\_DIR* as a sub-directory of the project’s main directory; - o **//#define USE\_ALL "a"**\ when defining this directive **icmbuild** looks for directories containing files having the names defined by the *USE\_ALL* specification. All source files in those directories as well as all source files in directories that (recursively) depend on the set of directories under consideration are recompiled, after which the *USE\_ALL* files are removed; - o **//#define USE\_ECHO ON**\ when defined as *ON* (rather than *OFF*) (system) commands executed by *icmbuild* are echoed; - o **//#define USE\_VERSION**\ when defined (it is defined by default) a file *VERSION* is read by *icmconf* to determine the program’s or library’s version, and the project’s release years. The file *VERSION* must be available in the project’s main directory containing lines like: ``` VERSION=1.02.03 YEARS=2010-2025 ``` ) ## PARSER MAINTENANCE The following directives are available in cases where a program uses a parser generator creating a parser class from a grammar specification. By default they’re all commented out, and can be removed if a parser generator is not used. See also the [**icmstart.rc**(7)](/icmstart.rc/7.md) man-page (section(FINE-TUNING ICMCONF)) for an alternative way to specify the parser-related *#defines*. - o **//#define PARSER\_DIR ""**\ the sub-directory containing the parser’s specification file. If the *PARSER\_DIR* directory is specified then all other directives in this section must also be specified; - - 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 is created; - - o **//#define PARSFLAGS "-V"**\ the flags that are used when calling the program specified at *PARSGEN*; - - o **//#define PARSGEN "bisonc++"**\ the name of the program generating the parser; - - o **//#define PARSOUT "parse.cc"**\ the name of the file generated by the parser generator (used by *icmbuild* when checking the timestamps of parser specification **s**); - - o **//#define PARSSPEC "grammar"**\ the name of the parser specification file. This file is expected in the directory specified by the *PARSER\_DIR* directive. ## SCANNER MAINTENANCE 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. By default they’re all commented out, and can be removed if a scanner generator is not used. See also the [**icmstart.rc**(7)](/icmstart.rc/7.md) man-page (section(FINE-TUNING ICMCONF)) for an alternative way to specify the scanner-related *#defines*. - o **#define SCANNER\_DIR ""**\ the subdirectory containing the scanner’s specification file. If the *SCANNER\_DIR* directory is specified then all other directives in this section must also be specified; - - 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 is created. By default no additional specification files are used; - - o **#define SCANFLAGS ""**\ the flags that are used when calling the program specified at *SCANGEN*; - - o **#define SCANGEN "flexc++"**\ the name of the program generating the lexical scanner; - - o **#define SCANOUT "lex.cc"**\ the name of the file generated by the lexical scanner (which is used by *icmbuild* when checking the timestamps of scanner specification **s**). - - o **#define SCANSPEC "lexer"**\ the name of the lexical scanner specification file. This file is expected in the directory specified by the *SCANNER\_DIR* directive. ## FILES The 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 files, like *main.cc,* *usage.cc*, etc.; - o **/etc/icmake**\ : directory containing the default system-wide [**icmstart**(1)](/icmstart/1.md) configuration file; - o **$HOME/.icmake**\ : optional user-defined 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 (f.b.brokken@rug.nl)"; ``` ## SEE ALSO [**ccache**(1)](/ccache/1.md), [**icmake**(1)](/icmake/1.md), [**icmbuild**(1)](/icmbuild/1.md), [**icmstart**(1)](/icmstart/1.md), [**icmstart.rc**(7)](/icmstart.rc/7.md). ## 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**).