icmbuild(1)

📦
version 13.07.00 · 8 versions
, in arch rolling

🎀 NAME 🎀

icmbuild(1) — A generic, C++/C program maintenance facility — okay bestie, this is the page for icmbuild, and it's literally the program that does your program maintenance for you 💅 (and yes, the page is long, part 1 starts now, don't go anywhere).

✨ SYNOPSIS ✨

icmbuild [-h] [-c] args

🌸 DESCRIPTION 🌸

So. icmbuild is a small C++ program that calls icmake(1) to do program maintenance, exactly as defined by the icmbuild script (which you'll commonly find hanging out in /usr/libexec/icmake). No cap.

icmbuild's actions get tailored through a configuration file called icmconf, and here's the thing: that file must be present in the directory where you're requesting program maintenance. It gets installed automatically by icmstart(1), so you usually don't have to lift a finger. If you want the tea on this file, go read icmconf(7)'s man-page. 🫶

icmbuild assumes your sources exist in and below the current working directory. The icmconf file in icmake(1)'s distribution gives you an example icmconf that icmbuild can use — in that example it's assumed you're maintaining a C++ project, but lowkey program maintenance for, like, a C project can also easily be configured. And if icmbuild gets called but icmconf isn't available? It displays a usage-summary and then dips. 😭

icmbuild handles the maintenance for all sources in each of the subdirectories named in the file CLASSES, and also for all sources in the current working directory. And what does 'maintenance' mean, you ask? It 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) plus multi-threaded source file compilation — which is giving marked reduction of source compilation times. 🔥

When source files are compiled, object files result, and those may be stored in a library — and the object file of the program's main function gets linked against that library. It's also possible to specify additional libraries that your program must be linked against.

If a library is constructed, icmbuild keeps it up to date. 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 icmbuild removes them. Clean. ✨

🦋 KICK-STARTING ICMBUILD 🦋

To use icmbuild, do it like this:

  • Install icmbuild in your path (icmake's installation procedure should already have taken care of that, bestie);
  • Copy icmconf (and probably a file CLASSES) to your project's base directory — that's 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:

  • Modify the #defines in the file icmconf to taste;
  • 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)) 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 — 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 because 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.

  • 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 info about which option is recognized by which icmbuild command.

  • -h — display usage information (which is also automatically shown when the current directory does not contain a file icmconf) and terminate icmbuild;
  • -c — clear the screen (by calling tput clear) before starting the compilation process;
  • -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:

  • 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;
  • 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;
  • cleantmp same as icmbuild clean, but the .gch files and files specified by the USE_ALL define in icmconf are not removed;
  • [-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;

  • [-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.

  • [-s] install shared path when using this installation command, icmconf must contain #define SHARED (cf. 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.

  • [-c] library do library maintenance (builds a static and optionally (if icmconf defines SHARED) a shared (dynamic) library);
  • [-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);
  • 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 equivalent to the command icmbuild [-c] program; if DEFCOM is specified as

#define DEFCOM "library"

then this is equivalent 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 forwarded to icm-dep.

The program icm-dep is automatically called by icmbuild to handle class dependencies. Refer to the 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)).

🍓 FILES 🍓

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

  • /usr/share/icmake/icmconf — Unabbreviated example of an icmbuild configuration file;
  • /usr/share/icmake/CLASSES — Example of an icmbuild CLASSES file.

⭐ EXAMPLES ⭐

Here's 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), icmconf(7), icmstart(1), icmstart.rc(7)

🙈 BUGS 🙈

None reported

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

✨ AUTHOR ✨

Okay so this whole thing was written by one very real human, and you should absolutely know their name:

  • Frank B. Brokken — reachable at f.b.brokken@rug.nl 🫶

That's it, that's the author section. Lowkey iconic that one person is behind all of this, ngl.

And that's a wrap, bestie! 🎀 Go forth and build stuff, and if a target ever misbehaves just remember: you and icmbuild are a team now. 💅

This page comes from icmake.13.07.00, dated 1992-2026, and you found it under icmbuild(1). Thirty-four years of manpage and it still slays. Periodt. 💖✨

📦 where this page comes from