icmake(1)

A program maintenance utility
(icmake.11.01.02)

1992-2024

NAME

icmake - A program maintenance (make) utility using a C-like grammar

SYNOPSIS

icmake option(s) [source [dest]] [args]

DESCRIPTION

Icmake(1) is a generic tool handling program maintenance that can be used as an alternative for make(1). It's a generic tool in that icmake-scripts, written in a language closely resembling the C programming language, can perform tasks that are traditionally the domain of scripting languages. See also section ICMAKE V. 11.01.00 below an overview of the changes from version 10 to version 11.

To summarize the changes: since icmake version 11.00.00 icmake offers Single Pre-Compiled Headers (SPCH) and multi-threaded source-file compilation, commonly reducing the construction times of projects to around 30-40% of the original construction times.

Icmake allows programmers to use a programming language (closely resembling the well-known C-programming language) to define the actions that are required for (complex) program maintenance. For this, icmake offers various special operators as well as a set of support functions that have shown their usefulness in program maintenance.

Although icmake scripts can be written from scratch, often the required activities are highly comparable. This observation resulted in the construction of two icmake scripts, which are part of the standard icmake distribution: icmstart(1), initializing a directory for program development and icmbuild(1), handling the actual program maintenance. By default both scripts are tailored to initializing and maintaining C++ programs (or, after minimal adaptation, C programs), but can easily be adapted to other programming languages.

This man-page covers icmake (the program), and its main support programs. Refer to the icmstart(1) man-page for information about how a directory can be initialized (created) in which (by default) a C++ or C program can be developed, and refer to the icmbuild(1) man-page for information about how icmbuild can be used to handle program maintenance.

The icmscript(7) man-page covers the syntax and facilities offered by icmake's scripting language, allowing you to write your own icmake scripts.

Icmake should not be confused with an Integrated Development Environment (IDE). Icmake merely performs tasks for which scripts can be written, and a minimal set of pre-defined scripts (icmstart and icmbuild) that have proven their usefulness when developing and maintaining programs are included in icmake's distribution.

In its standard activation modes, icmake uses the following support programs:

In addition, since version 11.00.00, icmake uses two new support programs:

Refer to the sections (below) ICMAKE V. 11.00.00, OPTIONS (for descriptions of the options --multicomp and spch); MULTICOMP and SPCH for, respectively, the descriptions of the icm-multicomp and icm-spch programs; and refer to the icmconf(7) man-page for details about the new #define directives MULTICOMP, SPCH, and SPCH_FILE.

Furthermore, primarily used for illustration, education, and debugging, the program icmun is available to disassemble compiled icmake byte-code (.bim) files (`bim-files'). Icmun is not installed in a standard PATH directory but in icmake's lib directory, which commonly is /usr/libexec/icmake (see also section ICMUN below).

Traditional make-utilities recompile sources once header files are modified. When developing C++ programs this is often not required, as adding new member functions to classes does not require you to recompile all source files of those classes. To handle class dependencies icmbuld(1) optionally inspects class dependencies, (re)compiling sources of dependent classes when necessary. By default, class-dependencies are not considered, but they are when the USE_ALL, SPCH, and/or (deprecated since version 11.00.00) PRECOMP #define directives, found in the icmconf file, are activated. Refer to the icmconf(7) man-page for details about these directives.

This manpage describes icmake's options in section OPTIONS, followed by sections covering the support programs

Refer to the icmscript(7) man-page for a description of icmake's C-like scripting language.

ICMAKE V. 11.01.00

Since icmake version 11.00.00 icmake may construct and use Single Pre-Compiled Headers (SPCH) and also offers multi-threaded source-file compilations.

The icmake support program icm-spch (callable via icmake --spch ..., see section ICM-SPCH for details) handles the construction of SPCHs; the icmake support program icm-multicomp (callable via icmake --multicomp ..., see section ICM-MULTICOMP for details) handles multi-threaded source-file compilations. See also the icmconf(7) manpage.

When developing C++ programs the environment variable ICMAKE_CXXFLAGS is no longer used. Instead the environment variable ICMAKE_CPPSTD is used. Use this latter environment variable to have one point of maintenance specifying the version of the C++ standard to use when compiling your sources.

OPTIONS

Where available, single letter options are listed between parentheses beyond their associated long-option variants. Icmake defines action options and non-action options. The first action option that is encountered is used.

When using icmbuild(1) for program maintenance icmake is called automatically, and the user doesn't have to specify any icmake options.

The following action options write some text to the standard output stream, whereafter icmake ends:

The remaining action options require additional options and/or arguments, and most of them process icmake source- or bim-files. Several of these action options write output files. By default these files are located in the same directories as the source files' directories.

The remaining action options are:

Finally, there are some (non-action) options that can be specified before specifying action options:

ICM-DEP

Icm-dep is a support program called by icmake to determine source- and precompiled-header file dependencies. Icm-dep can be used for software projects that are developed as described in the C++ Annotations, section Header file organization in chapter Classes. For those projects classes are developed in their own directories, which are direct sub-directories of the project's main program directory. Their class interfaces are provided in class-header files bearing the names of the class-directories, and all headers that are required by the class's sources are declared in a separate internal header files, commonly having extensions .ih.

Icmake automatically calls icm-dep when USE_ALL, SPCH, or PRECOMP is specified in icmconf files. By default it is called with arguments -V go. The #define ICM_DEP define-specification in the icmconf file can be used to specify a different set of options.

By default, when called by icmake directory dependencies are determined, touching all files in directories that depend on directories containing files whose names are specified by the icmconf's #define USE_ALL direcctive.

When icmconf files contain the #define SPCH directive icm-dep does not inspect precompiled headers: Single Pre-Compiled Headers are automatically inspected (and updated when necessary) by icm-precompile (also automatically called by icmake.

By providing another argument than go icm-dep performs a `dry run': it analyzes dependencies, but it won't remove or touch files.

Options of icm-dep may be specified immediately following icmake's --dependencies option. Icm-dep accepts the following options:

As an example, for icmake itself the class dependencies, obtained using the option -VVV are shown as:


    Direct class dependencies:
    --------------------------
                  uses:
                  ------------
        class:     1  2  3  4 
    --------------------------
             .  1  x  x  x  x 
       options  2     x     x 
       handler  3     x  x    
    argoptions  4           x 
    --------------------------
                   1  2  3  4 
    --------------------------
    
    Implied class dependencies:
    --------------------------
                  uses:
                  ------------
        class:     1  2  3  4 
    --------------------------
             .  1  -  x  x  x 
       handler  2     -  x  x 
       options  3        -  x 
    argoptions  4           - 
    --------------------------
                   1  2  3  4 
    --------------------------
    
The second table immediately shows that there are no circular dependencies: its lower triangle remains empty.

ICM-MULTICOMP

Icmake supports multi-threaded source-file compilation, often significantly reducing the compilation time of the source files of projects. When using the standard icmake icmbuild(1) program multi-threaded compilation is automatically used when projects' icmconf files contain the #define MULTICOMP directive (cf. icmconf(7)). It can also be called independently from icmconf using icmake's --multicomp (or -m) option.

Icm-multicomp accepts the following options:

Icm-multicomp needs one command-line argument and an optional second argument:

ICM-SPCH

icmake --spch calls icm-spch.
icmake --spch is followed by icm-spch's options and arguments, as described below.

Pre-compiled headers have been available for quite some time, and usually result in a significant reduction of the compilation time. Traditionally pre-compiled headers are defined for directories containing the sources of components of programs or libraries (e.g., in C++ directories commonly contain the sources of classes). However, there is a disadvantage to this approach: the combined sizes of such separately constructed pre-compiled headers can be huge, often requiring many Giga-Bytes of disk space. But often headers of separate components themselves include identical (e.g., system-based) header files, like (in C++) iostream, string and vector. As a result, these separately constructed pre-compiled headers contain large identical sections.

When using SPCHs these identical sections are avoided: only one precompiled header is constructed which is then used by all components of a project. As identical sections are avoided the sizes (and construction times) of SPCH are much smaller, usually requiring only 5 to 10 % of the space (and construction time) required for separately constructed pre-compiled headers.

When bfIicm-spch) is used for the first time on a project it visits the project's (internal) header files, and modifies them slightly avoiding namespace declarations inside the SPCH that might otherwise arise when identical names are defined in different namespaces. Suppose an internal header file looks like this:


    #include "class.h"
    #include <ctype>
    #include <iostream>
    using namespace std;
    inline void Class::capitalize(string &text)
    {
        for (char &ch: text)
            ch = toupper(ch);
    }
        
then this header file is modified to

    #include "class.h"
    #include <ctype>
    #include <iostream>
    inline void Class::capitalize(string &text)
    {
        for (char &ch: text)
            ch = toupper(ch);
    }
    #ifndef SPCH_
    using namespace std;
    #endif
        
The name SPCH_ is the 'guard'-name, which can be configured using the --guard option, but notice that following this modification the header file cannot be compiled anymore since the inline function is now positioned above the namespace declaration. Definitions and declarations which are positioned above the #ifndef SPCH_ declaration must therefore, where necessary, specify their appropriate namespaces. E.g., for Class::capitalize this means:

    inline void Class::capitalize(std::string &text)
    {
        for (char &ch: text)
            ch = toupper(ch);
    }
        
The first line of the file specifying which headers to process (which is specified as the command-line argument when using the --list option) contains the directive

    #define SPCH_
        
and at the end the namespaces encountered when processing the internal headers are declared, e.g.,

    using namespace std;
        

To use SPCHs in combination with icmbuild specify #define SPCH and maybe #define SPCH_FILE in the icmconf file (cf. icmconf(7)). SPCHs can also be used independently from using icmbuild by using icmake's --spch (or -S) option.

Icm-spch, except when calling it with the --help or --version options, always require one command line argument (dest) (described at options --list, --precompile and --soft-link), and with option --precompile a second (optional) command-line argument may be specified (destribed at that option).

Icm-spch accepts the following options:

When using icm-spch automatically (through icmbuild(1)) the following commands are issued (showing defaults):

    icm-spch -l spch
    icm-spch -p spch tmp/
    icm-spch -s spch tmp/

ICMUN

The icmun support program expects one argument, a bim-file. It disassembles the binary file an shows the assembler instructions and the structure of the bim-file. Note that in standard installations icmun is not located in one of the directories of the PATH environment variable, but it is available in the /usr/libexec/icmake directory, and the command icmake -u bim-file is normally used to unassemble the bim-file.

As an illustration, assume the following script is compiled by icmake (e.g., by calling icmake -c demo.im):


    void main()
    {
        printf("hello world");
    }
        
the resulting demo.bim file can be processed by icmun (e.g., calling /usr/libexec/icmake/icmun demo.bim). Icmun then writes the following to the standard output fle:


    icmun by Frank B. Brokken (f.b.brokken@rug.nl)
    icmun V10.00.00
    Copyright (c) GPL 1992-2021. NO WARRANTY.
    
    Binary file statistics:
            strings      at offset  0x0025
            variables    at offset  0x0032
            filename     at offset  0x0032
            code         at offset  0x0014
            first opcode at offset  0x0021
    
    String constants dump:
            [0025 (0000)] ""
            [0026 (0001)] "hello world"
    
    Disassembled code:
            [0014] 06 01 00   push string "hello world"
            [0017] 05 01 00   push int 0001
            [001a] 1b 1d      callrss 1d (printf)
            [001c] 1c 02      add sp, 02
            [001e] 04         push int 0
            [001f] 24         pop reg
            [0020] 23         ret
            [0021] 21 14 00   call [0014]
            [0024] 1d         exit
        

Offsets are shown using the hexadecimal number system and are absolute byte offsets in the bim-file. The string constants dump also shows, between parentheses, the offsets of the individual strings relative to the beginning of the strings section. The disassembled code shows the opcodes of the instructions of the compiled icmake source files. If opcodes use arguments then these argument values are shown following their opcodes. Each opcode line ends by showing the opcode's mnemonic plus (if applicable) the nature of its argument.

FILES

The mentioned paths are the ones that are used in the source distribution and are used by the Debian Linux distribution. However, they are sugestive only and may have been configured differently:

EXAMPLES

The distribution (usually in /usr/share/doc/icmake) contains a directory examples containing additional examples of icmake script. The icmstart script is an icmake script as is /usr/libexec/icmake/icmbuild, which is called by the /usr/bin/icmbuild program. See also the EXAMPLE section in the icmscript(7) man-page.

SEE ALSO

chmod(1), icmbuild(1), icmconf(7), icmscript(7), icmstart(1), icmstart.rc(7), make(1)

BUGS

Be advised that starting icmake version 10.00.00

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).