--- name: "icmbuild" section: "1" platform: "linux" package: "icmake" version: "13.07.00-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/icmbuild" --- # icmbuild(1) A generic, C++/C program maintenance facility ## NAME icmbuild - A generic, C++/C program maintenance facility ## SYNOPSIS *icmbuild* \[-h\] \[-c\] *args* ## DESCRIPTION *Icmbuild* is a small **C++** program calling [**icmake**(1)](/icmake/1.md) to do program maintenance as defined by the *icmbuild* script (commonly found in */usr/libexec/icmake*). *Icmbuild’s* actions are tailored through a configuration file (*icmconf*) which must be present in the directory where program maintenance is requested. This file is automatically installed by [**icmstart**(1)](/icmstart/1.md). Refer to [**icmconf**(7)](/icmconf/7.md)’s man-page for details about this file. *Icmbuild* assumes that your sources exist in and below the current working directory. The file *icmconf* in [**icmake**(1)](/icmake/1.md)’s distribution provides an example of an *icmconf* file that can be used by *icmbuild*. In that example it is assumed that a **C++** project is maintained, but program maintenance for, e.g., a **C** project can also easily be configured. If *icmbuild* is called, but *icmconf* is not available it displays a usage-summary after which *icmbuild* ends. *Icmbuild*() handles the maintenance for all sources in each of the subdirectories named in the file *CLASSES*, and also of all sources in the current working directory. \`Maintenance’ 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. When source files are compiled object files result which may be stored in a library, against which the object file of the program’s *main* function is linked. It is also possible to specify additional libraries against which the program must be linked. If a library is constructed it is kept up to date by *icmbuild*. 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 *icmbuild*. ## KICK-STARTING ICMBUILD To use *icmbuild* do as follows: - o Install *icmbuild* in your path (*icmake’s* installation procedure should already have taken care of that); - o Copy *icmconf* (and probably a file *CLASSES*) to your project’s base directory (i.e., the directory where and below which the project’s sources are found). Usually this has already been taken care of by the (icmstart) script; Next: - o Modify the *#defines* in the file *icmconf* to taste; - - o Enter the names of subdirectories containing sources on separate lines in the file *CLASSES* - When the *OBJ\_SEP* define is not specified (cf. [**icmconf**(7)](/icmconf/7.md)) then the ordering of the classes in the *CLASSES* file *is* important. The ordering should not be modified but new class (subdirectory) names can always be added to the end of the file *CLASSES*. Reordering the lines in the *CLASSES* file should be avoided as that most likely results in overwriting identically named object files from already existing directories. - If reordering is necessary, then first run the command *icmbuild* *clean* to remove all files that were thus far created by *icmbuild*. 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 *data.cc*) and because of the number-prefixes replacement of a file *x.o* from class *A* by file *x.o* from class *B* is prevented; - When the *OBJ\_SEP* define 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 Start *icmbuild*. The next section covers *icmbuild’s* modes of operation. ## OPTIONS *Icmbuild* recognizes three options of which only one can be specified. See the following section for information about which option is recognized by which *icmbuild* command. - o *-h*: display usage information (which is also automatically shown when the current directory does not contain a file *icmconf*) and terminate *icmbuild*; - o *-c*: clear the screen (by calling *tput clear*) before starting the compilation process; - o *-s*: strip the compiled program or library at its installation directory (see the various *install* modes below). ## ICMBUILD COMMANDS *Icmbuild* recognizes the following commands (possible options are shown between square brackets). With the *install* commands a *path* argument must be specified, which must be an existing user-writable directory: - o *clean*\ clean up remnants of previous actions (the directory specified by the *TMP\_DIR* define in *icmconf* is removed). If precompiled headers were created (i.e., *PRECOMP* in *icmconf* was specified) then all files having extension *.gch* in the main directory and in the directories listed in the *CLASSES* file are also removed. If *USE\_ALL* was specified then those files are also removed; - - o *cleangch*\ all *.gch* files that were precompiled are removed (whether existing in the *gch* subdirectory of the *TMP\_DIR* directory (specified in *icmconf*), or in directories specified in the *CLASSES* file, or in the project’s main directory). If *icmconf* does not specify *PRECOMP* then nothing happens; - - o *cleantmp*\ same as *icmbuild clean*, but the *.gch* files and files specified by the *USE\_ALL* define in *icmconf* are not removed; - - o *\[-s\] install program path*\ install the constructed program in the specified *path* (to be used after issuing *icmbuild* *program*, see below). Path can be absolute or relative and may optionally specify the name of the installed program. Example: ``` icmbuild install program ~/bin/prog ``` This installs the constructed binary program in the user’s *bin* directory with the name *prog*; - - o *\[-s\] install static path*\ install the constructed static library in the specified path (to be used after issuing *icmbuild* *library*, see below). Path can be absolute or relative and may optionally specify the name of the installed library. Example: ``` icmbuild install static /usr/lib/ ``` This installs the constructed static library (assume its name is *libspecial.a*) in */usr/lib* as */usr/lib/libspecial.a*.\ - - o *\[-s\] install shared path* when using this installation command, *icmconf* must contain *#define SHARED* (cf. [**icmconf**(7)](/icmconf/7.md)). It installs the constructed shared library in the specified path (to be used after issuing *icmbuild* *library*). Path can be absolute or relative, and must specify an existing directory. Example: ``` icmbuild install shared /usr/lib/ ``` This installs the constructed binary shared library (e.g. *libspecial.so*) in */usr/lib* as */usr/lib/libspecial.so*. In addition, the soft-links ``` libspecial.so -> libspecial.so.X libspecial.so.X -> libspecial.so.X.Y.Y.Z ``` are defined in */usr/lib*, where *X.Y.Z* are the major, minor and subminor versions defined in the file *VERSION*. - - o *\[-c\] library*\ do library maintenance (builds a static and optionally (if *icmconf* defines *SHARED*) a shared (dynamic) library); - - o *\[-c\] program*\ 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 *CLASSES*); - - o If no commands are specified (but optionally only *-c*) then the *DEFCOM* specification in the *icmconf* is inspected. Recognized specifications are: ``` #define DEFCOM "program" ``` which is quivalent to the command *icmbuild* *\[-c\] program*;\ if *DEFCOM* is specified as ``` #define DEFCOM "library" ``` then this is quivalent to the command *icmbuild* *\[-c\] library*.\ - If an explicit command is passed to *icmbuild* then *DEFCOM* specifications are ignored. ## ICM-DEP Class dependencies are handled by *icmake*’s support program *icm-dep*. It can be called from *icmake* when specifying option *-d*. All options and arguments following *-d* are forwared to *icm-dep*. The program **icm-dep** is automatically called by *icmbuild* to handle class dependencies. Refer to the [**icmake**(1)](/icmake/1.md) manpage, section **ICM-DEP** for a description of the **icm-dep** program. By default *icmbuild* calls *icmake -d -V go*: *icm\_dep* is called to perform its duties and to show its actions on the standard output stream. By specifying a *#define ICM\_DEP* parameter in the *icmconf* file this default can be overruled (cf. [**icmconf**(7)](/icmconf/7.md)). ## FILES The mentioned paths are sugestive only and may be installation dependent: - o **/usr/share/icmake/icmconf** Unabbreviated example of an *icmbuild* configuration file; - o **/usr/share/icmake/CLASSES** Example of an *icmbuild* *CLASSES* file. ## EXAMPLES Here is an example of the configuration file *icmconf* for a concrete program, using facilities of the *bobcat* library: ``` #define CLS #define LIBRARY "ofiles" #define MAIN "main.cc" #define SOURCES "*.cc" #define OBJ_EXT ".o" #define SHAREDREQ "" #define TMP_DIR "tmp" #define USE_ALL "a" #define USE_ECHO ON #define CXX "g++" #define CXXFLAGS "-Wall -Werror -O2" #define IH ".ih" #define MULTICOMP "jobs -q" #define SPCH "" #define REFRESH #define LDFLAGS "" #define ADD_LIBRARIES "bobcat" #define ADD_LIBRARY_PATHS "" #define DEFCOM "program" ``` ## SEE ALSO [**icmake**(1)](/icmake/1.md), [**icmconf**(7)](/icmconf/7.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**).