Provided by: icmake_10.03.00-1_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.
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. Both icmstart and icmbuild can be run without explicitly calling icmake.
This man-page covers icmake (the program), and its 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. Refer to the bv(icmscript)(7) man-page for a description of the
syntax and facilities offered by icmake’s scripting language.
Icmake does not offer an Integrated Development Environment (IDE). Icmake merely performs tasks for which
scripts can be written, and only a minimal set of pre-defined scripts (icmstart and icmbuild) that have
shown 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
In addition, 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/lib/icmake (see also section ICMUN
in this man-page).
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) may optionally inspect class
dependencies, (re)compiling sources of dependent classes when necessary. By default, class-dependencies
are not interpreted, but they are when the PRECOMP and/or USE_ALL defines, found in the file icmconf
file, are activated. Refer to the icmconf(7) man-page for details.
This manpage describes icmake’s options in the next section, followed by two sections covering the
support programs
o ICM-DEP
- the icm-dep dependency analyzer;
o ICMUN
- icmake’s unassembler.
Refer to the icmscript(7) man-page for a description of icmake’s C-like scripting language.
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.
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 --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 --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-directory 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 filed, commonly having extensions .ih.
Icmake automatically calls icm-depd when USE_ALL 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.
When icm-dep is activated (i.e., its argument go is specified) then icm-dep determines directory
dependencies, touching all files in directories that depend on directories containing modified files,
and/or removing precompiled headers if they include headers from other directories that were modified. 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
supports 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 --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 parameter 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 --gch
If icmconf files contain #define PRECOMP specifications then icm-dep checks whether precompiled
headers must be refreshed. If an icmconf file does not contain a #define PRECOMP specifications,
but precompiled headers should nonetheless be inspected, then option --gch can be specified;
o --no-gch
If icmconf files contain #define PRECOMP specifications 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" specifications 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" specifications 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 `USE_ALL’ specification;
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.
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/lib/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/lib/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/lib/icmake/icm-comp: the compiler called by icmake;
o /usr/lib/icmake/icm-exec: the byte-code interpreter called by icmake;
o /usr/lib/icmake/icm-dep: the support program handling class- and precompiled header dependencies;
o /usr/lib/icmake/icm-pp: the preprocessor called by icmake;
o /usr/lib/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/lib/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
o the --summary (-F) option has been discontinued;
o the --source short option -i has been replaced by -s;
o long option --icm-dep has been replaced by --dependencies;
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).
icmake.10.03.00 1992-2022 icmake(1)