NOUSERMACRO(option command specification)

includefile(release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(lsvoption)(3)(\
    bf(--ARG1)=tt(ARG3) (bf(-ARG2))\
)
DEFINEMACRO(lsoption)(2)(\
    bf(--ARG1) (bf(-ARG2))\
)
DEFINEMACRO(lvoption)(2)(\
    bf(--ARG1)=tt(ARG2)\
)
DEFINEMACRO(loption)(1)(\
    bf(--ARG1)\
)
DEFINEMACRO(svoption)(2)(\
    bf(-ARG1) tt(ARG2)\
)
DEFINEMACRO(soption)(1)(\
    bf(-ARG1)\
)

DEFINEMACRO(itt)(1)(\
    it()tt(ARG1)\
)

DEFINEMACRO(itb)(1)(\
    it()bf(ARG1)nl()\
)

DEFINEMACRO(icm)(0)(bf(icmake))
DEFINEMACRO(Icm)(0)(bf(Icmake))

DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))

COMMENT( man-request, section, date, distribution file, general name)
manpage(icmake)(1)(_CurYrs_)(icmake._CurVers_)
        (A program maintenance utility)

COMMENT( man-request, larger title )
manpagename(icmake)(A program maintenance (em(make)) utility using a
                    bf(C)-like grammar)

COMMENT( all other: add after () )
manpagesynopsis()
       icm() option(s) tt([source [dest]]) [args]

manpagedescription()

      Icm()(1) is a generic tool for program maintenance which can be
used as an alternative for, e.g., bf(make)(1). It's a generic tool in that
tt(icmake)-scripts, written in a language closely resembling the bf(C)
programming language, can perform tasks that are traditionally the domain of
scripting languages. 

This man-page consists of the following sections:
    itemization(
    it() bf(ICMAKE V. 13.00.00) covers the changes since icm() version
        12.03.00;
    it() bf(OPTIONS) covers icm()'s options;
    it() bf(EXECUTING ICMAKE SCRIPTS) covers how to call icm() scripts;
    it() bf(ICM-DEP) describes the tt(icm-dep) support program;
    it() bf(ICM-MULTICOMP) describes the tt(icm-multicomp) support program;
    it() bf(ICM-SPCH) describes the tt(icm-spch) support program;
    it() bf(ICM-UN) describes the tt(icm-un) support program;
    it() bf(FILES) provides an overvieuw of the locations of icm() and its
        support programs (as used by the Debian Linux distribution);
    it() bf(EXAMPLES) contains references to locations containing some
        examples;
    it() bf(SEE ALSO) contains references to man-pages of icm() support
        programs and man-pages of programs related to icm(). In particular
        quote(
            itemization(
            it() bf(icmstart)(1), describes how to initialize a directory for
                (bf(C++) or bf(C)) program development;
            it() bf(icmbuild)(1), covers how to use icm() for the maintenance
                of such programs.
            it() bf(icmscript)(7) covers the syntax and facilities of icm()'s
                scripting language, allowing you to write your own icm()
                scripts.
            )
        )
    )

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

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

When using bf(icmbuild)(1) for program maintenance the following icm() support
programs are used: 
    itemization(
    itt(icm-comp)       byte-code compiling an icm() script;
    itt(icm-dep)        handling class-dependencies;
    itt(icm-exec)       executing a byte-code compiled icm() script;
    itt(icm-multicomp)  (optionally) using multi-threaded source file
                        compilation;
    itt(icm-pp)         pre-processing an icm() script;
    itt(icm-spch)       (optionally) constructing a project-wide Single
                        Pre-Compiled Hbeader file (SPCH).
    )

In addition to the above programs the icm() project provides
    itemization(
    it() the bf(icmodmap) program can be used when developing tt(C++)
        programs using modules (cf. the bf(icmodmap)(1) man-page);
    itt(icm-un) disassembling compiled icm() byte-code files
        (`tt(bim-files)'). bf(icm-un) is primarily used for illustration,
        education, and debugging and is called by icm() when specifying its
        option tt(--unassemble) or tt(-u) (see also section bf(ICMUN)).
    )

Some make-utilities by default recompile sources once header files are
modified. When developing bf(C++) programs this is often not required, as
adding new member functions to classes does not require the recompilatopm of
all source files of those classes. Class dependencies are optionally inspected
by bf(icmbuld)(1) (they are inspected when the tt(USE_ALL, SPCH), and/or 
(now deprecated) tt(PRECOMP) tt(#define) directives in the tt(icmconf) file
are activated (cf. the bf(icmconf)(7) man-page for details).

manpagesection(ICMAKE V. 13.00.00)

In icm() version 13.00.00 the following modifications were implemented
w.r.t. its version 12.03.00:
    itemization(
    it() option tt(--all) (tt(-a)) was added to the bf(icm-spch) program
        performing in sequence the actions of its tt(--list, --precompile,)
        and tt(--soft-link) options. Several existing options were
        altered. See the bf(ICM-SPH) section for details.
    it() the (internal) headers inspected by tt(icmake --spch) (or tt(-S)) are
        not modified anymore. 
    it() to remove the (now obsoleted) tt(#ifndef SPCH_) specifications from
        files listed in existing tt(spch) files written by previous versions
        of bf(icm-spch) the program tt(noifndef.cc), available in the icm()
        source distribution in its tt(support/) sub-directory can be used to
        remove existing tt(#ifnef SPCH_) sections from a project's tt(.ih)
        files;
    it() icm() tt(--source) compiles the icm() script to a temporary tt(.bim)
        file;
    it() the support program tt(icmun) was renamed to bf(icm-un) (called by
        icm() when specifying the tt(--unassemble) (tt(-u)) option, so in
        practice the name change is automatically handled).
    it() The bf(icmconf)(7) script can use tt(-o) in its tt(#define SPCH)
        specification. All (space character delimited) words following tt(-o)
        are passed to bf(icm-spch) as separate `tt(-o word)' options;
    it() When developing bf(C++) programs the environment variable
        tt(ICMAKE_CXXFLAGS) is no longer used. Instead the environment
        variable tt(ICMAKE_CPPSTD) is used. Use this latter environment
        variable to define one point of maintenance specifying the version of
        the bf(C++) standard used when compiling sources;
    it() When using Debian (or a comparable distributions) the script
        'rebuild' can be used to rebuild icmake's binaries after installing
        'libbobcat-dev', resulting in a reduction of their sizes of about 40%.
    it() The icm() program itself was redesigned.
    )

manpageoptions()

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

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

    itemization(
    it() lsoption(about)(a)nl()
       Ends icm() after showing some information about icm();

    it() lsoption(compile)(c) tt([options] source [bim-file]) nl()
       The icm() script is first pre-processed (see option tt(--preprocess)
        below) whereafter the pre-processed file is compiled by tt(icm-comp)
        producing a tt(bim-file). If the tt(bim-file) name is not specified
        then tt(source's) base-name, receiving extension tt(.bim), is
        used.nl()
       If tt(source) is a previously pre-processed file then option tt(-P)
        can be specified to suppress its pre-processing. E.g.,
       verb(
    icmake -c -P source dest.bim
       )
       If the bim-file exists and is younger than tt(source) then tt(source)
        is not compiled;
        
    it() lsoption(dependencies)(d) tt([options] action)nl()
       The bf(icm-dep) program is called determining the dependencies among
        classes. All options and arguments following this option are forwarded
        to bf(icm-dep). Refer to the bf(ICM-DEP) section of this man-page for
        information about tt(icm-dep);

    it() lsoption(execute)(e) tt([option] bim-file [arguments])nl() 
       Executes the bim-file, Before specifying tt(bim-file) option
        tt(--no-version-check) (see below, or the equivalent short option
        tt(-n)) can be specified to allow mismatches between icm()'s main
        version and the icm() version that was used to compile the
        bim-file.nl()
       Command-line arguments specified beyond tt(bim-file) are forwarded as
        arguments to the tt(bim-file's main) function (cf. the
        bf(icmscript)(7) man-page for details about writing icm()-scripts);

    it() lsoption(force)(f) tt([options] source [bim-file]) nl()
       Acts like option tt(--compile), but compilation is always performed,
        even if the bim-file is up-to-date;

    it() lsoption(help)(h)nl() 
       Ends icm() after providing usage info. Usage info is also provided when
        icm() is started without arguments;

    it() lsoption(multicomp)(m) tt([options] jobs 'compiler-spec') nl()
       The optional tt(options) are the options passed to the
        tt(icm-multicomp) program (cf. section bf(ICM-MULTICOMP) below).nl()
       See also the bf(icomonf)(7) man-page's tt(#define MULTICOMP) directive:
        when specified threaded compilation is automatically used;
 
    it() lsoption(no-process)(N)nl()
       Implies option tt(--verbose) (see below). This option is recognized by
        options tt(--dependencies, --execute, --source) and tt(-t) (either as
        two separate options or by `gluing' both options together, like
        tt(-Ne)). When specified, the support program is not run, but the
        command(s) that would have been used are shown to the standard output;

    it()  lsoption(no-version-check)(n)nl()
       This option is available with the action options tt(--execute,
        --source, --unassemble), and tt(-t). When specified the main versions
        stored in the specified icm-bim file and icm() itself may differ. This
        option should normally not be required, but was primarily added for
        development purposes;

    it() lsoption(preprocess)(p)  tt([options] source [pim-file]) nl()
       The file specified as first argument is pre-processed, producing a
        `tt(.pim)' file. If a second filename argument is provided then that
        file becomes the tt(.pim) file. If not specified, then
        the first filename, using the extension tt(.pim), is used. nl()
       With this option pre-processor symbol-defining options can be used:
        symbols whose values can be used in tt(source). E.g., when
        issuing the command
       verb(
    icmake -p -d one --define two source dest.pim
       )
       icm() pre-processes tt(source), defines the pre-processor symbols
        tt(one) and tt(two) (each having value 1), and produces the pim-file
        tt(dest.pim). Note that instead of using long options tt(--define)
        short options tt(-d) can also be used;

    it() lsoption(spch)(S) tt(...) nl()
       A SPCH is built. All options and arguments following tt(--spch) are
        forwarded to the tt(icm-spch) support program.  (cf. section
        bf(ICM-SPCH) below).nl()
       See also the bf(icomonf)(7) man-page's tt(#define SPCH) directive: when
        specified a SPCH is automatically constructed;

    it() lsoption(source)(s)  tt([options] source [arguments]) nl()
       Icm() uses tt(--compile) to compile the icm() source file specified as
        first argument (constructing a temporary bim-file) and
        then uses tt(--execute) to execute the bim-file, forwarding any
        subsequent tt(arguments) as arguments to the tt(bim-file's main)
        function.nl()
       Following the tt(--source) option options available for icm()'s
        tt(--compile) command can be specified. Following those options 
        options of icm()'s tt(--execute) options can be specified. Those
        latter options must be preceded by tt(--execute) or tt(-e). E.g., when
        issuing the command
       verb(
    icmake -s -d one -en source 
       )
       then icm() first compiles tt(source) after defining the pre-processor
        symbol tt(one), and then executes the bim-file, passing
        tt(--no-version-check) to tt(icm-exec)nl()
       When merely compiling icm() source files (using icm() tt(-c)) the
        compiled file by default receives the extension tt(.bim). But when
        using icm() tt(-s) temporary files are used  which are
        removed after executing the constructed binary file. When compilation
        errors are encountered the name of the temporary file is reported. It
        consists of three parts: the directory receiving icm()'s temporary
        files; the filename of the icm() script which is passed to icm()
        tt(-s); and a random 6-character extension. E.g., when calling icm()
        tt(-s script) error messages may refer to
        tt(/tmp/script.2JS49A);

    it() svoption(t)(tmpspec) tt([options] source [arguments]) nl() 
       This option is intended for icm()-scripts although it can also be used
        in a command-line icm() call. The tt(-t) option can be used in
        quite a few different ways which is covered in the next section
        (bf(EXECUTING ICMAKE SCRIPTS)).

    it() lsvoption(tmpdir)(T)(directory)nl() 
       By default temporary files are created in the tt(/tmp) sub-directory,
        or in the user's home (tt(${HOME})) directory if tt(/tmp/) cannot be
        used. To specify another directory to write temporary files in icm()'s
        option tt(--tmpdir) (or tt(-T)) can be specified, followed by the name
        of an (existing) directory to use for temporary files.nl()
       E.g., when compiling an icm() file tt(main.im), the output of icm()'s
        pre-processor is written to a temporary file which is removed after
        compilation. To write the temporary file to tt(~/.icmake) icm() can be
        called as
       verb(
    icmake -T ~/.icmake -c main.im
        )

    it() lsoption(unassemble)(u)nl()
       The file specified as first argument is an icm() bim-file, which is
        unassembled (cf. section bf(ICM-UN) below for more information about
        unassembling icm() bim-files);

    it() lsoption(verbose)(V)nl()
       Icm() child processes and their arguments are written to the standard
        output stream before they are called. This option may precede `action'
        options (tt(-c, -d, -e, -s) and tt(-u)), either as two separate
        options or by `gluing' both options together, like tt(-Ve).

    it() lsoption(version)(v)nl()
       Ends icm() after displaying its version.
    )

manpagesection(EXECUTING ICMAKE SCRIPTS) 
COMMENT(see also icmake/icmake/options/script.cc
                 icmake/scriptopts/bimbase.cc)

The tt(-t) option is available primarily for being used in executable icm()
scripts. The first line of executable icm() scripts consists of the following
components:
    itemization(
    it() a em(shebang) (tt(#!)) specification followed by icm()'s location;
    it() the tt(-t) option followed by its argument (see below);
    )

and optionally:
    itemization(
    it() compilation and execution options (specified as described at the
        tt(--source) option);
    it() a non-option component (e.g., tt(:)) which will be replaced by the
        location of the executable icm() script;
    it() remaining components on the first line are forwarded as-is to the
        icm() script's tt(main) function;
    )

E.g., the following simple tt(icm) executable script `tt(args)' could be
defined in tt(~/bin):
        verb(    #!/usr/bin/icmake -t. -d one : two --dir three
    void main(int argc, list argv)
    {
        #ifdef one
            printf << "one is defined\n";
        #endif
        printf << argc << " arguments: " << argv << '\n';
    }
        )
    When it's called as tt(~/bin/args four five) then the arguments tt(four)
and tt(five) are added to the tt(two --dir three) arguments already specified
by the script itself. Called this way the script outputs. Its 1st argument is
the name of a temporary tt(.bim) file whose finale extension is different at
each new call (see also this section's final paragraph):
    verb(    one is defined
    /tmp/args.F04dgh two --dir three four five
        )

The argument of the tt(-t) option is used to specify the location of the files
used by icm()'s tt(-t) option (tt(/dir) can also be specified as multiple
directories, like tt(/dir/sub1/sub2)):
    itemization(
    it() if it's a single dot (tt(-t.)) the compiled (temporary) bim-file is
        written in icm()'s directory used for temporary files (e.g., tt(/tmp)
        or tt($HOME));
    it() if it's tt(~/dir) or tt(/dir) then icm() writes temporary files in
        the specified directory, replacing tt(~) by the user's tt($HOME)
        directory;
    it() if it's tt(~/dir/name) or tt(/dir/name) then tt([~]/dir/name)
        specifies the path of the compiled tt(.bim) file, writing all other
        temporary files in the same directory as the tt(.bim) file. The
        tt(.bim) file is kept after execution (allowing it to be executed
        repeatedly using 'icm() tt(-e)'). The icm()-script is not compiled if
        the tt(.bim) file is younger than the script.
    )

When executing icm() scripts (either by using executable tt(#/bin/icmake)
scripts explicitly calling icm() tt(-t)) the preprocessed scripts and usually
the compiled script are temporary files are used which are removed after
executing the constructed binary file. When errors are encountered the name of
the temporary file containing the errors is reported. Those temporary files
consist of three parts: the directory receiving icm()'s temporary files; the
filename of the icm() script which is passed to icm() tt(-s); and a random
6-character extension. E.g., when executing a script like tt(showfiles) (using
tt(#!/bin/icmake -t .)) and the script contains errors then the error messages
may refer to tt(/tmp/showfiles.2JS47P);)


manpagesection(ICM-DEP) 

    includefile(icmdep.inc)

manpagesection(ICM-MULTICOMP)

    includefile(icmmulticomp.inc)

manpagesection(ICM-SPCH)

    includefile(icmspch.inc)
        
manpagesection(ICM-UN)

    includefile(icmun.inc)

manpagefiles()

    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:

Binary programs:
    itemization(
    it() bf(/usr/bin/icmake): the main icm() program;
    it() bf(/usr/bin/icmbuild): the wrapper program around the tt(icmbuild)
        script handling standard program maintenance;
    it() bf(/usr/bin/icmodmap): the module mapper which initializes the
        maintenance of bf(C++) programs using modules;
    it() bf(/usr/bin/icmstart): an icm()-script that is can be used to create
        the startup-files of new projects;
    )

Support programs:

    itemization(
    it() bf(/usr/libexec/icmake/icm-comp): the compiler called by icm();
    it() bf(/usr/libexec/icmake/icm-dep): the support program handling
        class-dependencies;
    it() bf(/usr/libexec/icmake/icm-exec): the byte-code interpreter;
    it() bf(/usr/libexec/icmake/icm-multicomp): the multi-thread source file
        compiler; 
    it() bf(/usr/libexec/icmake/icm-pp): the preprocessor called by icm();
    it() bf(/usr/libexec/icmake/icm-spch): the program preparing SPCHs;
    it() bf(/usr/libexec/icmake/icm-un): the icm() unassembler.
    )

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

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

manpagebugs()

    None reported.

includefile(trailer.inc)
