icmbuild(1) Icmake’s generic program maintenance facility icmbuild(1)

# [NAME](#NAME)

icmbuild - A generic, C++/C program maintenance facility

# [SYNOPSIS](#SYNOPSIS)

*icmbuild* \[-h] \[-c] *args*

# [DESCRIPTION](#DESCRIPTION)

*Icmbuild* is a small **C++** program calling [**icmake**(1)](/man/os/icmake/icmake.1) 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)](/man/os/icmake/icmstart.1). Refer to [**icmconf**(7)](/man/os/icmake/icmconf.7)’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)](/man/os/icmake/icmake.1)’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](#KICK)

To use *icmbuild* do as follows:

[o](#o)

Install *icmbuild* in your path (*icmake’s* installation procedure should already have taken care of that);

[o](#o~2)

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](#o~3)

Modify the *#defines* in the file *icmconf* to taste;

[o](#o~4)

Enter the names of subdirectories containing sources on separate lines in the file *CLASSES*

Note that the order of the classes mentioned in *CLASSES* *is* relevant in that 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;

[o](#o~5)

Start *icmbuild*.

The next section covers *icmbuild’s* modes of operation.

# [OPTIONS](#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](#o~6)

*-h*: display usage information (which is also automatically shown when the current directory does not contain a file *icmconf*) and terminate *icmbuild*;

[o](#o~7)

*-c*: clear the screen (by calling *tput clear*) before starting the compilation process;

[o](#o~8)

*-s*: strip the compiled program or library at its installation directory (see the various *install* modes below).

# [ICMBUILD COMMANDS](#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](#o~9)

*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](#o~10)

*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](#o~11)

*cleantmp*  
same as *icmbuild clean*, but the *.gch* files and files specified by the *USE\_ALL* define in *icmconf* are not removed;

[o](#o~12)

*\[-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](#o~13)

*\[-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](#o~14)

*\[-s] install shared path* when using this installation command, *icmconf* must contain *#define SHARED* (cf. [**icmconf**(7)](/man/os/icmake/icmconf.7)). 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](#o~15)

*\[-c] library*  
do library maintenance (builds a static and optionally (if *icmconf* defines *SHARED*) a shared (dynamic) library);

[o](#o~16)

*\[-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](#o~17)

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](#ICM)

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)](/man/os/icmake/icmake.1) 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)](/man/os/icmake/icmconf.7)).

# [FILES](#FILES)

The mentioned paths are sugestive only and may be installation dependent:

[o](#o~18)

**/usr/share/icmake/icmconf** Unabbreviated example of an *icmbuild* configuration file;

[o](#o~19)

**/usr/share/icmake/CLASSES** Example of an *icmbuild* *CLASSES* file.

# [EXAMPLES](#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](#SEE_ALSO)

[**icmake**(1)](/man/os/icmake/icmake.1), [**icmconf**(7)](/man/os/icmake/icmconf.7), [**icmstart**(1)](/man/os/icmake/icmstart.1), [**icmstart.rc**(7)](/man/os/icmake/icmstart.rc.7)

# [BUGS](#BUGS)

None reported

# [COPYRIGHT](#COPYRIGHT)

This is free software, distributed under the terms of the GNU General Public License (GPL).

# [AUTHOR](#AUTHOR)

Frank B. Brokken (**f.b.brokken@rug.nl**).

1992-2026 icmake.13.06.01

---

Document: icmbuild(1) from icmake 13.06.01-r0 (Chainguard OS)
Source: https://gitlab.com/fbb-git/icmake.git