return to first page linux journal archive
keywordscontents

ICMAKE Part 1

In this first part of a three part article, Frank and Karel explore their motivation for writing a new programming "make tool", the organization of the system itself and where you can get a copy. Part 2 of the article will cover the icmake grammer and the final part will show examples of its use. For those of you without Internet access, we plan to have this program (as well as other code covered in LJ) is available on floppies for a nominal fee. See page 45.

by Frank B. Brokken and K. Kubat

Introduction

Icmake was developed initially as a make-tool to be used under MS-DOS. Although make-utilities under MS-DOS exist, we tended not to use these utilities for a two main reasons:

  1. Since our primary language is C (C++), we considered the grammar of the make utilities awkward.
  2. In a program development cycle in which sources are compiled, included in a library, which is then linked to a main object module we experienced problems in setting up the correct dependencies between files.

Once icmake was developed, it was soon thereafter ported to UNIX, where it now not only serves as our make-utility of choice. However, by now it also serves as a utility with which we find it easy to write shell-scripts.

Currently icmake has been ported to several UNIX platforms, such as LINUX, SCO-UNIX, HP-UX, and SunOS. Icmake, therefore, reflects almost perfectly the transition from DOS to UNIX we experienced ourselves: developed initially under MS-DOS, it has now become primarily a UNIX tool. But then, we used the `tools of the trade', already under MS-DOS: both bison and flex were used for the construction of the icmake compiler icm-comp. The first version of icmake was available after some nine days, including the decisions we had to take about what form it should take. Since we were also working with some UNIX platforms (SunOS and AIX) by that time, the `porting daemon' started to influence our implementation descisions as well. The first port of icmake to a unix operatingsystem took only a few days, which time was mainly invested in porting some specific MS-DOS functions to an acceptable UNIX form.

In this article we describe icmake from the point of view of its users. The organization of the software, the grammar of icmake files, icmake-scripts and —to start with—the way to obtain icmake is described in the remainder of this article. At the end some illustrative examples of icmake-scripts are given.

2. Obtaining Icmake

Icmake can be obtained by anonymous ftp from the site beatrix.icce.rug.nl, where it is found in the directory pub/unix.

The package consists of an archive, usually in the form icmake-X.XX.tar.gz, where the current version of icmake is denoted by X.XX. This archive contains a tarred and gzipped directory structure, in which the source files for icmake (and the executable programs for MS-DOS) can be found. Also at beatrix.icce.rug.nl the file icmake.doc can be be found, which is a guide to the installation of icmake. This latter file is especially useful for UNIX installations.

Alternatively, icmake can also be found at tsx-11.mit.edu, where it is part of the Linux Operating System distribution. At tsx-11.mit.edu the icmake-files are usually located in pub/linux/sources/usr.bin.

Apart from the source-distribution and the installation guide there is a icmake.dvi file available at beatrix.icce.rug.nl describing icmake in somewhat more detail than is possible in this article. Also, a postscript version (icmake.ps) of the documentation is available.

The Organization of the Software.

Icmake consists of five programs. One program is a nitor program, monitoring the construction and execution of an icmake file. The monitor program may call an icmake preprocessor, an icmake compiler and an icmake executor. A fifth program is the icmake unassembler, showing the code generated by the icmake compiler in a human-readable form.

The programs can be divided in two categories: programs of which the ordinary user of icmake must be aware (the top-level programs) and programs which are called internally by icmake (the nested-level programs). The top-level programs are the icmake-monitor program and the icmake unassembler. Normally, only the monitor program is started at the command line, but programs of the nested-level are sometimes called explicitly. All icmake programs can be started as stand-alone programs.

The normal processing of an icmake script runs as follows:

  1. An icmake source script is written, containing a description of the tasks to be performed by icmake. This script is very C-like.
  2. The monitor is started, receiving the name of the file containing the icmake source script as its argument.
  3. The monitor program may call the icmake preprocessor and the icmake compiler to convert the source file in a binary file to be processed by the icmake executor.
  4. The icmake executor is started by the monitor. The executor reads the compiled icmake script, executing the instructions found in the compiled script.

Once an icmake-script has beenompiled, the compilation and preprocessing phases are skipped by the monitor program, and the icmake executor is called immediately. In this way icmake monitors its own dependency between the icmake source script and the compiled icmake script.

Each of the programs of the icmake family has a version number. The version numbers consist of a major and a minor number. E.g., in the version number 6.03, the major version is 6 and the minor version is 03. The programs can only communicate when the major version numbers of all icmake programs are equal. So a working set of programs must all have the same major version number. The minor number is used to indicate small changes in the separate programs.

3.1. The top-level programs.

At the top-level of icmake two programs are found. icmake itself and icmun. The program `icmake' is the monitor program, monitoring the execution of anicmake-script. The program `icmun' is an unassembler, showing the contents of the compiled icmake script in a human-readable form. Normally, icmun is not used: it serves mainly as a debugging tool (although we've used icmun also for instructional purposes, showing people some basic notions of assembly-language programming).

Icmake

The icmake program monitors the execution of an icmake script, and acts therefore as an interface between the user and nested-level icmake programs. Normally, the nested-level icmake programs are not started explicitly at the command-line, but are called by icmake itself.

ICCE Make Utility Version 6.00

Icmake may be invoked unsing one of the two following command lines:

icmake [flags] asciifile [binaryfile] [arguments]

or

icmake [flags] -i asciifile [arguments]

The two invocation modes differ in the fact that the first invocation (without the i flag) makes it possible to specify explicitly the name of the compiled icmake file (the "binaryfile"). The second mode uses a predefined name for the compiled icmake file. In this form the name of the asciifile is used, having the extension ".bim".

With both invocation modes the "flags", the two consecutive hyphens and the arguments are optional. The arguments are passed to the makefile and can be inspected there. The flags are used for requesting specific actions of icmake. The specification of the asciifile is obligatory in both invocations: this file is the make script, which is interpreted by icmake and defines the actions to be performed.

Whenever program from the icmake-family is started without arguments, a help summary is displayed.

When icmake is activated without any arguments, the help shows among other things the flags which are recognized by icmake. In that case, something like the following table below will appear on the screen:

The following flags are recognized:

-b. When this flag is used, no recency test is performed. Rather, the binary make file is executed immediately `as is'. When this flag is absent, icmake compiles the input file (.im file) into a binary file (.bim file) if the input file is more recent.

-c. When this flag is used, the ascii input file is compiled to a binary makefile, but is not executed. The compilation occurs irrespective to the recency of the input file and the binary file.

-i file. This option specifies file as the input file for icmake and stops the further processing of the arguments. In this case the nam of the binary makefile (.bim file) is equal to the name of the input file receiving the extension .bim. The default input file extension, .im, is not supplied by icmake when this flag is given: the specified name is taken literally.

-p. When this option is used, only the icmake preprocessor is activated. The output of the preprocessor is sent to a file having the same name as the input file, but having the extension .pim. When this flag is absent, icmake's preprocessor still generates a .pim file. However, this file is deleted after the compilation-phase.

-q. When this option is used, icmake operates quietly. I.e., the copyright banner is not displayed.

--. By default, the first non-flag argument on the command line is the input file, for which the extension .im is assumed. When a second non-flag argument is given, then this name is used for the binary file (.bim file). The processing of arguments stops only when two consecutive hyphens are encountered. All arguments which follow the -- flag can be inspected by the icmake-file.

Note that the -- flag is not required when icmake is activated with the -i flag.

The asciifile specification is obligatory. This is the icmake source file which will be compiled and tested by icmake. Icmake assumes a default extension .im. E.g., the command line:

icmake test will activate icmake to process the icmake sourcefile test.im. Note however that the command line:

icmake -i test will start icmake to process the makefile test. The presence of the -i flag prevents icmake from supplying an extension.

The binaryfile specification is optional. When given, icmake uses this file as the binary intermediate file in the process of making. Extension .bim is the default. By default icmake uses the basename of the asciifile and extension .bim.

Following the binaryfile specification, several arguments to the makefile itself may be given. However, before any extra arguments are specified two consecutive hyphens are needed. Following these hyphens extra arguments may follow which will be passed to the icmake dependent programs. As described above, the delimiting two hyphens are not necessary when the -i flag is used.

The icmake specification file is written as a C program, and contains a main() function which receives some of the arguments specified on the command line. The first argument is always the name of the binairy make file (normally having the .bim extension). Remaining arguments are the arguments that follow the two hyphens. The hyphens themselves are not included in the series of arguments which are passed to main() (The user-defined function main() is described below).

Icmun

Icmun is mainly used in developing icmake. The icmun program is an unassembler for the compiled icmake file created by icmake. Icmun produces an assembly-like listing of the instructions contained in the compiled makefile. Normally it is hardly ever used. More information about icmun is beyond the scope of this article, but can be found in the icmake documentation, which may be obtained from, e.g., beatrix.icce.rug.nl.

The nested-level programs.

The following programs are icmake's `nested-level' programs. Normally these programs are not started at the command-line, but are started as child- or overlay-processes of icmake itself.

The preprocessor icm-pp.

Icm-pp is the preprocessor of the icmake compiler (described in the next section). This program scans the icmake source file for preprocessor directives (e.g., #include, see the section on the preprocessor directives below). and takes appropriate actions when they are encountered. Icm-pp writes an output file in which the preprocessor directives have been `expanded'. This (temporary) file is used thereupon by the icmake compiler.

The compiler icm-comp.

The stage following the preprocessing is the compilation. The icmake compiler is called icm-comp, and this program translates an icmake source file, generated by icm-pp, into a binary format and performs error checking. The resulting binary file contains opcodes, much like the output file of a compiler of a programming language. When a binary makefile is generated, the intermediate output file of the preprocessor is no longer needed and is removed.

The executor icm-exec.

Icm-exec is the executor of the binary makefile generated by icm-comp. In this phase the compiled icmake file is read. It contains opcodes which are interpreted, thus executing the commands defined in the icmake source file: lists of files are built, files are compared by dates, and other actions may be taken.

Executable makefiles under Linux (Unix)

Under the Linux (UNIX) operating system it is possible to create makefiles for icmake which are themselves executable. As an example, this could result in a setup in which an icmakefile "backup" exists, which can simply be started as:

backup

In such a setup the same effect may be achieved by creating an icmakefile backup.im, which is then started with the command:

icmake backup

The former form is certainly simpler to use, and requires an executable icmake script called `backup'. To create an executable makefile, the following steps should be taken:

  1. The makefile can be given a suitable name. This name is later used to invoke the process which executes the makefile. For this reason, the name backup may be preferred to backup.im.
  2. The makefile is made executable using the UNIX chmod program: chmod +x backup

    This labels the file backup as an executable program. Furthermore, the makefile may be placed in a directory pointed to by the PATH environment. E.g., the makefile may be placed in a user's private bin directory.

  3. The following line is added as the first line in the icmake source file:
    #!/usr/local/bin/icmake -qi

This line informs the operating system that, when executing this file, the program /usr/local/bin/icmake should be started, using the flags -qi and then appending the name of the icmake file. As discussed before, the flag -q suppresses icmake's copyright banner, while the flag -i causes icmake to take the following file argument as the literal input file instead of supplying the default extension .im.

Note that this line must contain a full reference, including the path, to the program icmake. In this example this path is taken to be /usr/local/bin.

The compiled icmake file (.bim file) is placed by icmake in the same directory as the icmake source This directory must therefore be accessible to the user invoking the makefile. If the icmake script and the associated .bim file is to be accessible system-wide, the icmake script could be installed by root. Using the example of the backup script again, root could install the "backup" script using the following command in the directory where the "backup" script is stored:

icmake -c backup

This will merely result in a compilation of "backup", thus generating backup.bim.

Frank B. Brokken and K. Kubat, ICCE, Department of Education Universtiy of Groningen. Groningen, the Netherlands.