icmake

icmake.7.22.01.tar.gz

1992-2015

icmake(1)

icmake.7.22.01.tar.gz A program maintenance utility

1992-2015

NAME

SYNOPSIS

icmun bimfile

DESCRIPTION

Icmake(1) can be used as an alternative to make(1). In its standard operation more, it calls the following programs:

• icm-pp to preprocess the icmake file
• icm-comp to byte-code compile the icmake s
• icm-exec to interpret the byte-code file

Icmake allows the programmer to use a program language (closely resembling the well-known C-programming language) to define the actions involved in (complex) program maintenance. For this, icmake offers various special operators as well as a set of support functions that have proven to be useful in program maintenance.

The program icmun(1) may be used to disassemble the compiled byte-code file.

Traditional make-utilities recompile sources once header files are modified. In the context of C++ program development this is often a bad idea, as adding a new member to a class does not normally require you to recompile the class's sources. To handle class dependencies in a more sensible way, icmake(1)'s CLASSES file may define dependencies among classes. By default, class-dependencies are not interpreted. See the icmconf(7) man-page for details.

ADDITONS SINCE VERSION 7.00

• Integral constants may be specified using hexadecimal notation (e.g., 0x12ab);
• The IM environment variable may contain multiple directories, separated from each other by colons (:).
• #define-directives may refer to other macro definitions using the ${identifier} format.
• #ifdef, #ifndef, #else and #endif directives can be nested.
• The `backtick' operator is defined, executing a program in a shell and collecting its standard output in a list (see below).
• The index operator ([]) is defined as an alternative to the pre-defined function element(), and can be used on lists and strings.
• The function string getenv(string envvar) is predefined. If existing scripts already define a getenv() function of their own, it it suggested to remove this function and use the new getenv() function instead. Alternatively, rename the script-defined function getenv() and calls of this function to, e.g. my_getenv().
• The function int strstr(string haystack, string needle) is renamed to int strfind(string haystack, string needle).

  NOTE: this modification in version 7.00 could very well affect your earlier (6.xx) icmake scripts. Changing `strstr' into `strfind' should bring your older scripts up-to-date again.

OPTIONS

Icmake:

source: icmake script source file (default extension: .im).

dest: binary icmake script file (default: `source'.bim).

--: icmake/icmake-script arguments separator

args: arguments following -- are entered into the icmake scipt main() function's argv-list (see below at section USER DEFINED FUNCTIONS).

• -a
  information about icmake
• -b
  blunt execution of the destinationfile
• -c
  the destination file is only compiled
• -i file
  file: name of source. Icmake argument processing stops.
• -o file
  all icmake output is written to file (Not implemented on unix platforms)
• -p
  only the preprocessor is activated
• -q
  quiet mode: copyright banner not displayed
• -t file
  file is used as a temporary bim-file, to be removed on exit. Icmake argument processing stops.

Icmun:

bimfile: binary icmake script file.

PREPROCESSOR DIRECTIVES

The following preprocessor directives are available:

• comment:
  standard C comment (all between /* and */) as well as comment-to-end-of-line (all line contents following //) are ignored.
• Shell startup: The first line of the icmake-script may start with #!path, where path defines the absolute location of the icmake program. By making the script executable, it can be called without explicitly calling icmake.

  E.g., if the first line of an (executable) icmakefile 'icm' (without extension) contains

  
              #!/usr/bin/icmake -qi
          
  

  then icm may be given as a command, thus executing

  
              /usr/bin/icmake -qi icm ...
          
  

  Alternatively,

  
              #! /usr/bin/icmake -qt /tmp/icm
          
  

  may be used, resulting in the execution of

  
              #! /usr/bin/icmake -qt /tmp/icm icm ...
          
  

  In this case the binary makefile is not kept, but a temporary file /tmp/icm.PID is used and removed on exit. The PID extension being the process-id of the icmake program executing icm.
• #include "filename"
  The file filename is included at the location of the directive
• #include <filename>
  The file filename is included at the location of the #include directive; filename is searched in the directories pointed to by the IM environment variable.
• #define identifier definition
  The text identifier will be replaced by definition. The definition may contain references to already defined identifiers, using the ${identifier} format. If the ${identifier} hasn't been defined (yet), the text ${identifier} is literally kept. At each #define at most 100 text-replacements are performed, preventing infinite recursion.
• #ifdef identifier
  If the identifier macro was defined the next block of code (until a matching #else or #endif directive was detected) is byte-compiled. Otherwise, the block of code is ignored.
• #ifndef identifier
  If the identifier macro was not defined the next block of code (until a matching #else or #endif directive was detected) is byte-compiled. Otherwise, the block of code is ignored.
• #else
  Terminates a #ifdef and #ifndef directive, reversing the acceptance decision about the following code.
• #endif
  Terminates the preprocessor block starting at the matching #ifdef, #ifndef or #else directive.
• #undef identifier
  Remove identifier from the set of defined symbols. This will not affect the specification of any previously defined symbols in which identifier was used.

DATA TYPES

The following data types are available:

• int
  Integral values, ranging from -0x8000 until 0x7fff. int constants may be specified as decimal numbers, hexadecimal numbers or as ASCII character constants (e.g., 'x').
• string
  Text variables. Text constants are delimited by double quotes. Multiple text constants may be concatenated, but a text constant may not extend over multiple lines. To indicate an end-of-line in a text constant use the \n escape sequence. The escape sequences \a \b \f \n \r and \t are available. Otherwise, \x is interpreted as a literal x. So, use \\ to indicate \ within a text constant.
• list
  A data structure containing a series of individually accessible string values. When a list contains elements, its first element is indicated by index 0.
• void
  Used with function definitions to indicate that the function does not return a value.

Variables may be defined both at the global level as well as locally to functions. Variables are strongly typed. A variable cannot have the type void.

Variables may be initialized when they are defined. The initialization can use return values of functions, but cannot use variables. Consider initializations as being constructed from constant values.

PREDEFINED SYMBOLS

The following symbols are predefined by icmake. All are constant int values:

The following symbols are available depending on the architecture:

OPERATORS

All C operators, except for the ternary operator, are supported, operating like their C counterparts on int variables and/or values.

Additionally, for string type variables and/or values the following operators are available:

• a + b: returns a new string value containing the concatenation of string values a and b. Note that string constants may be concatetated without using the + operator, e.g.,

  
      "hello "   "world"
      "hello " + "world"
          
  

• a += b: a must be a string variable, to which the string variable or value b is appended.
• string comparisons: operators == != <= >= < > != and == may be applied to string values or variables, returning 1 if the comparison succeeds, otherwise 0. Comparison is case sensitively, and follows the ASCII character set.
• !a: the boolean ! operator returns 1 if the string a is empty, otherwise 0 is returned.
• a younger b, a newer b: returns 1 if file a is more recent than file b. E.g., "source.cc" newer "source.o". If b doesn't exist, 1 is returned; if a doesn't exist 0 is returned; if neither a nor b exists, 0 is returned; if they are of the same age, 0 is returned. Explicit tests for the existence of a file can be performed using the exists() predefined function (see below, section PREDEFINED FUNCTIONS).
• a older b: turns 1 if file a is older than file b. E.g., "libprog.a" older "source.o". If a doesn't exist, 1 is returned; if b doesn't exist 0 is returned; if neither a nor b exists, 0 is returned; if they are of the same age, 0 is returned.
• []: the index operator is defined as an alternative to the built-in function element. It can only be applied (as holds true for element() as well) as so-called rvalue. Therefore, constructions like:

  
          // assume str1 and str2 are strings
      str1 = str2[3]
          
  

  will be accepted, but the following construction will not be accepted:

  
      str2[3] = str; // won't compile
          
  

For list type variables and/or values the following operators are available:

• a + b: returns a new list value containing the concatenation of list values a and b. This is not a set operation: if an element appears both in a and in b, they will appear twice in the resulting list.
• a - b: returns a new list value containing the elements in a that are not present in b. This is a set operation.
• a += b: elements in b are added to the elements in a, which must be a list variable. This is not a set operation.
• a -= b: elements in b are removed from the elements in a, which must be a list variable. This is a set operation.
• list equality comparisons: operators != and == may be applied to list values or variables. Operator == returns 1 if both lists have element-by-element identical elements, 0 otherwise. Operator != reverses the result of ==.
• !a: the boolean ! operator returns 1 if the list a is empty, otherwise 0 is returned.
• []: the index operator is defined as an alternative to the built-in function element. It can only be applied (as holds true for element() as well) as so-called rvalue. Therefore, constructions like:

  
          // assume lst is a list, str is a string
      str = lst[3]
          
  

  will be accepted, but the following construction will not be accepted:

  
      lst[3] = str; // won't compile
          
  

Typecasts may be performed using the standard C cast-operator to cast:

• Strings to ints and vice versa ((int)"123", (string)55)
• Strings may be cast to lists (list lst = (list)"hello")

FLOW CONTROL

Icmake offers the following subset of C's statement types. They can be used as in the C programming language.

• expression ;
  The plain expression statement;
• The compound statement
  Different from C icmake does not support variable definitions inside a compound statement. All variables used locally by a function must be defined as either function parameters or as variables that are defined immediately at the beginning of a function's body.
• if (condition) statement
• if (condition) statement else statement
• for (init; condition; increment) statement
  The variable(s) used in the initialization section must already have been defined. The init, condition and increment sections may be left empty. The empty condition section is interpreted as `always true'.
• while (condition) statement
  The do ... while() statement is not implemented for icmake.
• return (for void functions) and return expression for other functions.
• break
  To leave for and while statements, overruling the statement's condition. C's continue is not available.
• exit(expression)
  To terminate the icmake-script. The expression must evaluate to an int value, which becomes the script's exit value.

PREDEFINED FUNCTIONS

Icmake offers the following predefined functions, which can be used immediately by icmake scripts. The function overview is ordered alphabetically by function name, but where appropriate short summary labels are provided:

Helper functions of exec() (see also below at exec()):

• void arghead(string h)
  Defines the `argument head', to be used with exec(). By default, the `argument head' is an empty string.
• void argtail (string t)
  Defines the `argument tail', to be used with exec(). By default, the `argument tail' is an empty string.

String-to-ascii converters:

• int ascii(string s)
  Returns the first character of s as an int; e.g., ascii("A") returns 65;
• string ascii(int i)
  Returns i as a string, e.g., ascii(65) returns the string "A";

System calls:

• The `backtick` operator (`)
  A string placed between two backticks is executed by the popen(3) function. The standard output gererated by the command that is stored in the string argument is returned as a list. An empty list indicates that the command could not be executed. A command that could be executed but did not produce any output returns a list containing one empty element. The command's standard error stream output is not automatically collected. Standard shell redirection could be used to collect the standard error stream's output as well. Example:

  
          string s = "ls";
          printf(`s`);        // prints the elements in the current
                              // directory
              
  

Filename modifiers:

• string change_base(string file, string newbase)
  Changes the basename of file, returns the changed name. E.g, change_base("/path/demo.im", "out") returns "/path/out.im";
• string change_ext(string file, string newext)
  Changes the extension of file, returns the changed name. E.g, change_ext("source.cc", "o") returns "source.o";
• string change_path(string file, string newpath)
  Changes the path specification of file, returns the changed name. E.g, change_path("tmp/binary", "/usr/bin") returns "/usr/bin/binary". Note that the /-separator is inserted if required.

System calls:

• string chdir(string newdir)
  Changes the script's working directory, returns the previous dir as an absolute path.
  Use chdir(".") to get current working directory, chdir("") may be used to obtain the startup working directory (this functionality was broken in releases before than 7.00, but is now operational). The function terminates the icmake-script if the specified newdir does not exist.
• string chdir(int checking, string newdir)
  Same functionality as the previous function, but by specifying checking as P_NOCHECK the function won't terminate the script. Rather, it will return the script's current working directory.

Helper functions of exec() (see also below at exec()):

• cmdhead(string h)
  Defines a `command head', to be used with exec(). By default, the `command head' is an empty string.
• cmdtail(string t)
  Defines a `command tail', to be used with exec(). By default, the `command tail' is an empty string.

Icmake execution modifier:

• echo(int opt)
  Controls echoing of called programs (and their arguments), specify OFF if echoing is not requested. By default ON is active.

Functions returning elements of aggregates:

• string element(int index, list lst)
  Returns string index (0-based) from lst. An empty string is returned if an unavailable index value is provided. See also the [] operator in the section OPERATORS.
• string element(int index, string str)
  Returns character index (0-based) from str. An empty string is returned if an unavailable index value is provided. See also the [] operator in the section OPERATORS.

System calls:

    void main(int argc, list argv, list envp)
        

    void main(int argc, list argv)
    {
        list toCompile;
        int idx;

        if (argc == 1)
            usage(element(0, argv));

        if (toCompile = altered("*.cc"))
        {
            for (idx = sizeof(toCompile); idx--; )
                compile(element(idx, toCompile));

            if (getenv("dryrun")[0] == "0")
                linking(element(2, argv));
        }
        exit (0);
    }