| icmake(1) | A program maintenance utility | icmake(1) |
icmake - A program maintenance (make) utility using a C-like grammar
icmake option(s) [source [dest]] [args]
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:
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
Refer to the icmscript(7) man-page for a description of icmake’s C-like scripting language.
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:
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:
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.
icmake -c -d one --define two source dest.bim
icmake -c -P source dest.bim
icmake -f -P source dest.bim
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;
icmake -p -d one --define two source dest.pim
then icmake first compiles source, defining the pre-processor symbol one, and then executes the bim-file, passing --no-version-check to icm-exec;
icmake -s -d one -en source
it can be called as hello one -two --three, producing output like:
#!/usr/bin/icmake -t.
int main(int argc, list argv)
{
printf << "hello: " << argv << ’\n’;
}
(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.,
hello: /tmp/10434.bim.MKqvAb one -two --three
#!/usr/bin/icmake -t. -d one --define two
Finally, there are some (non-action) options that can be specified before specifying action options:
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:
As an example, for icmake itself the class dependencies, obtained using the option -VVV are shown as:
The second table immediately shows that there are no circular dependencies: its lower triangle remains empty.
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 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):
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:
void main()
{
printf("hello world");
}
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.
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:
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.
chmod(1), icmbuild(1), icmconf(7), icmscript(7), icmstart(1), icmstart.rc(7), make(1)
Be advised that starting icmake version 10.00.00
This is free software, distributed under the terms of the GNU General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).
| 1992-2022 | icmake.10.03.03 |