Provided by: icmake_12.03.00-1ubuntu1_amd64 
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:
o icm-pp to pre-process the icmake file,
o icm-comp to byte-code compile the icmake s,
o icm-dep to handle class-dependencies (see the ICM-DEP section in this man-page for
more information about icm-dep),
o icm-exec to execute the byte-code file.
Since version 11.00.00, icmake contains these support programs:
o icm-multicomp to use multi-threaded source file compilation,
o icm-spch to construct a project-wide Single Pre-Compiled Hbeader file (SPCH).
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.
Icmake version 12.02.00 added icmodmap(1) to icmake. Icmodmap(1) can be used when
developing C++ programs using modules. Refer to the icmodmap(1) man-page for details.
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
o ICM-DEP
the icm-dep dependency analyzer;
o ICM-MULTICOMP
the icm-multicomp multi-threaded compiler program.
o ICM-SPCH
the icm-spch SPCH construction support program
o ICMUN
icmake’s unassembler.
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:
o --about (-a)
Shows some information about icmake;
o --help (-h)
Provides usage info, returning 0 to the operating system. Usage information is also
provided if icmake is started without providing arguments. In that case 1 is
returned to the operating system;
o --version (-v)
Displays icmake’s version.
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:
o --compile (-c) [options] source [bim-file]
The source file is first pre-processed (by icm-pp) whereafter the pre-processed
file is compiled (by icm-comp), producing a bim-file. If the bim-file name is not
specified then source’s base-name, receiving extension .bim, is used.
If the bim-file exists and is younger than source then source is not compiled.
With this option pre-processor symbol-defining options can be used: symbols having
values 1 which can be used in source. E.g., when issuing the command
icmake -c -d one --define two source dest.bim
then icmake compiles source, defines the pre-processor symbols one and two (each
having value 1), and produces the bim-file dest.bim. Note that instead of using
long options --define short options -d can also be used.
If source is a previously pre-processed file then option -P must be specified to
compile it. E.g.,
icmake -c -P source dest.bim
o --dependencies (-d) [options] action
Icmake calls icm-dep to determine the dependencies among classes. All options and
arguments following this option are forwarded to icm-dep. Refer to the ICM-DEP
section of this man-page for information about icm-dep;
o --execute (-e) [option] bim-file [arguments]
Executes the bim-file, specified as icmake’s first file argument. Before the
bim-file option --no-version-check (or the equivalent short option -n) can be
specified to allow mismatches between icmake’s main version and the icmake version
that was used to compile the bim-file. See also the description of the
--no-version-check option at the description of the non-action options below.
Options and arguments specified beyond the bim-file are forwarded as arguments to
the bim-file’s main function (refer to the icmscript(7) man-page for details about
how to write icmake-scripts);
o --force (-f) [options] source [bim-file]
Acts like option --compile, but compilation is always performed, even if the
bim-file is up-to-date. As with --compile, if source is a previously pre-processed
file then option -P must be specified to compile it. E.g.,
icmake -f -P source dest.bim
o --multicomp (-m) [options] jobs ’compiler-spec’
The optional options are the options of the icm-multicomp program: --threads (-t)
and/or --quiet (-q). The ’compiler-spec’ argument is the (quoted) compiler call
specification, using $1 to refer to the source file to compile, $2 to refer to the
object file’s path, like ’/usr/bin/g++ -c -o $2 --Wall -Werror $1’ Threaded
compilation is automatically used when the #define MULTICOMP directive is specified
in projects’ icmconf files.
Refer to section ICM-MULTICOMP (below) for a description of icm-spch’s usage and
arguments.
o --preprocess (-p) [options] source [pim-file]
The file specified as first argument is pre-processed, producing a `.pim’ file. If
a second filename argument is provided then that file becomes the .pim file. If not
specified, then the first filename, using the extension .pim, is used.
With this option pre-processor symbol-defining options can be used: symbols having
values 1 which can be used in source. E.g., when issuing the command
icmake -p -d one --define two source dest.pim
then icmake pre-processes source, defines the pre-processor symbols one and two
(each having value 1), and produces the pim-file dest.pim. Note that instead of
using long options --define short options -d can also be used;
o --spch (-S) ...
A SPCH is built. All options and arguments following --spch are forwarded to the
icm-spch support program.
A SPCH is automatically constructed when the #define SPCH directive is specified in
projects’ icmconf files.
Refer to section ICM-SPCH (below) for a description of icm-spch’s usage and
arguments.
o --source (-s) [options] source [arguments]
Icmake uses --compile to compile the icmake source file specified as first argument
(constructing the default bim-file if necessary) and then uses --execute to execute
the bim-file, forwarding any subsequent arguments as-is to the bim-file’s main
function.
With this option pre-processor options as well as the --no-version-check execute
option can be used. When using the latter option it must follow the pre-processor
options (if specified) and it must be preceded by --execute (or -e). E.g., when
issuing the command
icmake -s -d one -en source
then icmake first compiles source, defining the pre-processor symbol one, and then
executes the bim-file, passing --no-version-check to icm-exec;
o -t tmpspec [options] source [arguments]
This option is intended for icmake-scripts although it can also be used in a
command-line icmake call. Its argument tmpspec is either a single dot (as in -t.)
in which case icmake determines the name of the bim-file in the directory icmake
uses for temporary files (see option --tmpdir below), or it uses tmpspec as the
filename to write the bim-file to (which file is also removed once the script’s
execution ends).
At the options pre-processor options as well as the --no-version-check execute
option can be specified. When using the latter option it must follow the
pre-processor options (if specified) and it must be preceded by --execute (or -e).
The argument source is the name of the icmake script to process, and source may
optionally be followed by arguments. Those arguments are forwarded as-is to the
script’s main function, where they appear as elements of its list argv parameter.
Rather than using the explicit command-line call icmake -t. ... the -t option is
normally used in the first line of an (executable) (so usually chmod +x source has
been specified before calling the script), where its pre-processor and execute
options can also be specified. For example after writing the executable script
hello:
#!/usr/bin/icmake -t.
int main(int argc, list argv)
{
printf << "hello: " << argv << ’\n’;
}
it can be called as hello one -two --three, producing output like:
hello: /tmp/10434.bim.MKqvAb one -two --three
(the name following hello: will be different, as it is the name of the compiled
temporary bim-file). If icmake pre-process and/or execute options are required they
can be specified in the first line, following the -t option. E.g.,
#!/usr/bin/icmake -t. -d one --define two
o --unassemble (-u)
The file specified as first argument is an icmake bim-file, which is unassembled.
Refer to the icmun section further down this man-page for more information about
icmun;
The program icmun unassembles bim-files. This program also supports the
--no-version-check (-n) option.
Finally, there are some (non-action) options that can be specified before specifying
action options:
o --no-process (-N)
Implies option --verbose. This option may precede options -d, -e, -s and -t (either
as two separate options or by `gluing’ both options together, like -Ne). When
specified, the actions are not activated, but the command(s) that would have been
used are shown to the standard output;
o --no-version-check (-n)
This option is available with the action options --execute, --source, --unassemble,
and -t. When specified the main versions of icm-bim files and icmake itself may
differ. This option should normally not be used, and was added for development
purposes only;
o --tmpdir=directory (-T)
The specified directory is used for storing temporary files. E.g., when compiling
an icmake script, the output of icmake’s preprocessor is written to a temporary
file which is removed when icmake ends. By default /tmp is used, unless /tmp is not
a writable directory, in which case the current user’s $HOME directory is used;
o --verbose (-V)
The child processes and their arguments are written to the standard output stream
before they are called. This option may precede options -d, -e, -s and -t (either
as two separate options or by `gluing’ both options together, like -Ve).
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:
o --classes=filename (-c)
By default, icm-dep inspects dependencies of the directories mentioned in the file
CLASSES. Furthermore, if the icmconf(7) file specifies PARSER_DIR and SCANNER_DIR
then those directories are also considered. Use this option to specify the file
containing the names of directories to be inspected by icm-dep.
o --gch
If icmconf files contain #define PRECOMP directives then icm-dep checks whether
precompiled headers must be refreshed. If an icmconf file does not contain a
#define PRECOMP diretive, but precompiled headers should nonetheless be inspected,
then option --gch can be specified;
o --help (-h)
Icm-dep writes a summary of its usage to the standard output and terminates,
returning 0 to the operating system;
o --icmconf=filename (-i)
By default icm-dep inspects the content of icmconf files, This option is used if
instead of icmconf another file should be inspected;
o --mainih=mainheader (-m)
In the icmconf file the #define IH directive is used to specify the suffix of class
header files that should be precompiled, assuming that their filenames are equal to
the names of the directories which are listed in the CLASSES file. But CLASSES does
not specify the name of the program’s top-level directory. This option is used to
specify the name of the top-level header file to precompile. By default main.ih is
used;
o --no-gch
If icmconf files contain #define PRECOMP directives but icm-dep should not check
whether precompiled headers must be refreshed then option --no-gch should be
specified;
o --no-use-all
If icmconf files contain #define USE_ALL "filename" directives then all source
files in directories containing files named filename are recompiled. When
specifying this option inspections of `USE_ALL’ specifications is suppressed;
o --use-all=filename
If icmconf files contain #define USE_ALL "filename" directives then all source
files in directories containing files named filename are recompiled. Specify this
option to inspect the presence of filename files if icmconf does not contain a
#define USE_ALL directive;
o --verbose (-V)
This option can be specified multiple times. The number of times it is specified
determines icm-dep’s verbosity. If not used then icm-dep silently performs its
duties. If specified once, then icm-dep reports to the standard output what actions
it performs; if specified twice it also reports non-default options and
automatically included directories; if specified three times it also reports class
dependencies; if specified more often it reports what files it encountered and what
decision it would make when go would be specified;
o --version (-v)
Icm-dep reports its version number to the standard output and terminates, returning
0 to the operating system.
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:
o --help (-h)
Icm-multicomp writes a summary of its usage to the standard output and terminates,
returning 0 to the operating system;
o --nr (-n)
When compiling source files and option --nr is specified then the thread number
compiling a source file is written to the standard output stream.
o --quiet (-q)
When this options is not specified then the path names of the compiled object and
source files are written to the standard output stream. When it is specified once
only the source files’ directories and filenames are written to the standard output
stream, and when it is specified more than once no information about the compiled
files is written to the standard output stream.
o --threads=nThreads (-t)
By default the computer’s number of cores determines the number of threads being
used when compiling the source files. Optionally a different number of threads can
be requested using this option, e.g., --threads 5.
o --version (-v)
Icm-multicomp reports its version number to the standard output and terminates,
returning 0 to the operating system.
Icm-multicomp needs one command-line argument and an optional second argument:
o the first argument is the name of the file specifying which files must be compiled.
Use icmbuild(1) to write this file. It can also be constructed otherwise. It
ccontains groups of file specifications where each group starts with a line like :
support tmp/o 5 where the 2nd element specifies the location (directory) of the
source files (use . to refer to the project’s top-level directory); the 3rd element
specifies the destination directory of the compiled files (which is created if not
existing); and the 4th element specifies the prefix to add in front of the compiled
object files.
Following this line the remaining lines of a group specify the names of the source
files to compile.
Once the compilation ends (either because all files were successfully ccompiled, or
because a compilation failed) the specification file is removed;
o the second argument is optional. By default the following specification is used
(all on one line)
g++ -c -o $2 ${ICMAKE_CPPSTD} --Wall -Werror $1
In this specification $1 is replaced by the location of the source file to compile
and $2 is replaced by the location of the compiled object file. If the environment
variable ICMAKE_CPPSTD is defined (specifying the C++ standard to use, e.g.,
ICMAKE_CPPSTD=--std=c++26) then its value replaces ${ICMAKE_CPPSTD} in the
specification.
Alternatively, the command compiling source files can be provided as second
command-line argument, which should be quoted, like
’g++ -c -o $2 ’${ICMAKE_CPPSTD}’ --Wall -Werror $1’
or the second command-line argument can be f:file, where file is the name of a file
whose first line contains the specification of the command compiling source files
(which must specify $1 and $2 and optionally $ICMAKE_CPPSTD).
The PATH environment variable is used to locate the compiler; the compiler’s
absolute path can also be used.
ICM-SPCH
icmake --spch calls icm-spch.
icmake --spch is followed by icm-spch’s options and arguments.
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.
Icm-spch accepts the following options (after covering the options, a more extensive
description of icm-spch is provided):
o --classes=file (-c)
this option can only be used in combination with the --list option. File contains
the list of directories inspected by the --list option (by default CLASSES). The
project’s top directory is automatically inspected unless the option --no-topdir is
specified;
o --guard=name (-g)
this option can only be used in combination with the --list option. Name is the
name of the include-guards used in internal headers. By default name is SPCH_;
o --help (-h)
Icm-multicomp writes a summary of its usage to the standard output and terminates,
returning 0 to the operating system;
o --internal=.ext (-i)
this option can only be used in combination with the --list option. .ext is the
extension used for the internal headers (including the dot) by default: .ih;
o --keep=regex (-k)
this option can only be used in combination with the --list option. It keeps (and
does not inspect) include-specification(s) in the internal header matching (POSIX
extended) regular expressions in regex. Use (...)|(...) to specify multiple
regexes. Use f:file to specify a file whose non-empty lines contain regexex;
o --list (-l)
write the filenames of the files to process when constructing a single precompiled
header (SPCH) to the file (dest) specified as the command line argument. Dest must
specify a filename (without extension) in the current working directory.
o --no-topdir (-n)
this option can only be used in combination with the --list option. Ignore the
internal header found in the project’s top directory. This option is used when
merely constructing a library instead of a program;
o --precompile=file (-p)
precompile file (which is the name of the file specified at the option --list) to
the SPCH file dest, specified as icm-spch’s first command-line argument. If dest
ends in / then the SPCH is the file ’dest’file.gch.
By default the SPCH is constructed using the following command (all on one line):
g++ -c -o $2 ${ICMAKE_CPPSTD} -Wall -Werror -O2 -x c++-header $1
Here, $1 refers to ’file’, $2 refers to ’dest’, and $ICMAKE_CPPSTD refers to the
value of the ICMAKE_CPPSTD environment variable (specifying the C++ standard to
use, e.g., ICMAKE_CPPSTD=--std=c++26).
Alternatively, the command constructing the SPCH can be provided as second
command-line argument, which should be quoted like
’g++ -c -o $2 ’${ICMAKE_CPPSTD}’ -Wall -Werror -O2 -x c++-header $1’
or the second command-line argument can be f:file, where file is the name of a file
whose first line specifies the command constructing the SPCH (which must specify $1
and $2 and optionally $ICMAKE_CPPSTD).
The PATH environment variable is used to locate the compiler; the compiler’s
absolute path can also be used.
o --soft-links=file (-s)
this option uses the same arguments as the arguments used with the --precompile
option. This option creates .gch soft-links from the header files listed in file to
the SPCH-file specified as the program’s command-line argument dest;
o --version (-v)
Icm-multicomp reports its version number to the standard output and terminates,
returning 0 to the operating system;
o --warn (-w)
interactively warn when existing header files are about to be modified, accepting
or refusing the modifications. Once refused icm-spch ends.
Pre-compiled headers have been available for quite some time, and usually result in a
significant reduction of the compilation time. Using single precompiled headers results in
a large reduction of required disk-space compared to using precompiled headers for
separate directories.
When using SPCHs almost identical precompiled headers for separate directories 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
SPCHs are much smaller, usually requiring only 5 to 10 % of the space (and construction
time) ccompared to using 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 to avoid 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 requires 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).
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:
o /usr/bin/icmake: the main icmake program;
o /usr/bin/icmbuild: the wrapper program around the icmbuild script handling standard
program maintenance;
o /usr/bin/icmstart: an icmake-script that is can be used to create the startup-files
of new projects;
o /usr/libexec/icmake/icm-comp: the compiler called by icmake;
o /usr/libexec/icmake/icm-exec: the byte-code interpreter called by icmake;
o /usr/libexec/icmake/icm-dep: the support program handling class- and precompiled
header dependencies;
o /usr/libexec/icmake/icm-pp: the preprocessor called by icmake;
o /usr/libexec/icmake/icmun: the icmake unassembler.
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), icmodmap(1), icmscript(7), icmstart(1), icmstart.rc(7),
make(1)
BUGS
None reported.
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).