icmconf(7)

configuration file for icmbuild(1)
(icmake.10.04.00)

1992-2023

NAME

DESCRIPTION

The icmconf configuration file is used to specify and fine-tune the program maintenance performed by the icmbuild(1) program and script. It can be used to activate and specify various directives that determine how the program or library maintenance is performed.

The directives are biased towards the construction of a C++ program, but program maintenance for other languages (e.g., C) can also easily be configured.

The icmbuild(1) script ignores empty lines and lines whose first non-blank characters are two consecutive forward slashes (//). Long lines can be split over multiple lines by writing a final backslash character at lines continuing at the next line (refer to the icmake(1) man-page for further details).

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) checks class dependencies using its support program /usr/lib/icmake/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 that's 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 PRECOMP was defined, then a similar action is performed for the precompiled headers: if a local header file that's (directly or indirectly) included by a class's internal header file has changed, then that class's precompiled header as well as all precompiled headers of dependent classes are recompiled.

The icmbuild(1) script itself does not inspect these dependencies, but calls /usr/lib/icmake/icm-dep to perform the requird tests. The program icm-dep's short usage summary is written to the standard output stream when calling icmake -d (or directly: /usr/lib/icmake/icm-dep).

DEFINES IN ICMCONF

All of the following #defines are required except those that are shown as commented #defines (e.g., //#define REFRESH).

• //#define ADD_LIBRARIES ""
  when a program must be linked against additional libraries (other than the name of the program's library itself (specified at LIBRARY) 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 "math bobcat");

• //#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 specify paths relative to the directory that is specified at the TMP_DIR directive (see below);

• //#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;

• #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;

• #define CXXFLAGS "--std=c++20 -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;

• //#define DEFCOM "..."
  a DEFCOM directive may be added to the icmconf file (the icmstart(1) 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.;

• //#define ICM_DEP "-V go"
  the existence and implied existence of USE_ALL files (see the description of the USE_ALL directive), as well as the correct ages of precompiled headers can be checked by icmake's support program icm_dep. 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;

• //#define IH ".ih"
  the extension used for internal header files. See #define PRECOMP below. If PRECOMP is specified ttIH) must also be specified;

• //#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;

• //#define LIBRARY "modules"
  by defining this directive a local library is constructed. When a binary program is built it is linked against this library rather than to the individual object modules.

  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;

• //#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;

• //#define NO_PRECOMP_WARNING"
  when PRECOMP is defined (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 PRECOMP has been defined;

• #define OBJ_EXT ".o"
  this directive specifies the extension of object modules created by the compiler;

• //#define PRECOMP "-x c++-header"
  define this directive to construct precompiled headers (in which case the IH) directive must also have been specified

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;

    VERSION=9.03.00
    YEARS=1992-2020