home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / make / icmake-6.17 / icmake-6 / icmake / doc / icmake.1 next >
Encoding:
Text File  |  1994-03-01  |  13.2 KB  |  282 lines
  1. =============================================================================
  2.               ICMAKE --- by Frank B. Brokken and Karel Kubat
  3.                F.B.Brokken@icce.rug.nl, K.Kubat@icce.rug.nl
  4.  
  5.                            Distribution: 6.17
  6. =============================================================================
  7.  
  8. PROGRAMS OF THE ICMAKE FAMILY:
  9.  
  10.         icmake  -  the top level program, calls icm-pp, icm-comp, icm-exec
  11.         icmun   -  unassembler, for maintenance purposes
  12.         icm-pp, icm-comp, icm-exec  -  internal programs for preprocessing,
  13.                    compilation, execution
  14.  
  15. PROGRAM INVOCATION:
  16.  
  17.        icmake [flags] source[.im] [dest[.bim]] [-- [args]]
  18.             flags:  optional flags:
  19.                     -a     : information about ICMAKE
  20.                     -b     : blunt execution of the destinationfile
  21.                     -c     : the destination file is compiled
  22.                     -i file: 'file': name of source, end of icmake arguments
  23.                     -o file: all icmake output is redirected to `file'
  24.                     -p     : only the preprocessor is activated
  25.                     -q     : quiet mode: copyright banner not displayed
  26.             source: make description source file (default extension: .im)
  27.             dest:   binary make file             (default:    source.bim)
  28.             -- :   optional icmake-file arguments separator
  29.             args:  optional arguments following -- received by
  30.                    the icmake file in its argv-list
  31.  
  32.         Note: -o is not implemented on unix platforms
  33.  
  34.         icmun bimfile
  35.                 bimfile: file to unassemble
  36.  
  37. SYNTAX OF A MAKEFILE:
  38.  
  39.         (a) Preprocessor directives:
  40.                 // comment              : comment until end-of-line
  41.                 /* comment */           : comment between /* and */
  42.                 #include "filename"     : includes a file
  43.                 #include <filename>     : includes a file from directory
  44.                                           pointed to by IM variable
  45.                 #define ident redef     : defines ident to expand to redef
  46.                 #! ...                  : ignored line
  47.  
  48.             Notes: 
  49.             * Any characters on a line beyond an #include ... directive
  50.               are ignored.
  51.         * Comment in a #define is removed, but must be on one line.
  52.           
  53.                 * #! may be used on unix platforms to use icmake-shell
  54.                   scripts, in combination with the -i flag.
  55.                   E.g., if the first line of an (executable) icmakefile 'icm'
  56.                   (no extension) contains
  57.                                #! /usr/local/bin/icmake -qi
  58.                   then 'icm' may be given as command, thus executing
  59.                                 /usr/local/bin/icmake -qi icm
  60.                 
  61.         (b) Preloaded symbols:
  62.     
  63.         --------------------------------------------------------------
  64.         symbol          1 when defined on the platform ... otherwise 0
  65.         --------------------------------------------------------------
  66.         MSDOS           MS-DOS platform (with MSC 7.00 compiler)
  67.         unix            Unix, usually with GNU's gcc compiler
  68.         linux           '386 or '486 running Linux (usually with gcc)
  69.         M_SYSV, M_UNIX  '386 or '486 running SCO/Unix (usually with
  70.                         Microsoft C)
  71.         _POSIX_SOURCE   Unix with Posix complient compiler
  72.         __hpux          HP-UX, with the native HP compiler
  73.         --------------------------------------------------------------
  74.  
  75.         (c) Types and variables:
  76.                 int             (-0x8000..0x7fff or 'x', x: ASCII character)
  77.                 string          (a piece of text)
  78.                 list            (a number of strings)
  79.                 void            (may be used for user-defined functions)
  80.             Global and local variables are supported, as well as arguments
  81.             to user-defined functions.
  82.  
  83.         (d) Escape sequences in strings:
  84.                 \a \b \f \n \r \t
  85.                 \other: other taken literally, e.g., \\ for \
  86.  
  87.         (e) Flow control statements:
  88.                 if (condition) statement
  89.                 if (condition) statement else statement
  90.                 for (init; condition; increment) statement
  91.                                     - init, condition and increment are
  92.                                       optional
  93.                 return (expression) - no (expression) with void functions
  94.                 break
  95.                 exit (expression)
  96.  
  97.         (f) The user-defined function main():
  98.                 Arguments may be (int argc, list argv, list envp)
  99.                 or a subset of those, similar to C.
  100.                 Argc is the number of elements in argv.
  101.                 Argv holds the arguments, with element 0 the .bim filename,
  102.                 element 1 the first argument etc.
  103.                 Envp holds the environment, element 0 is the first variable,
  104.                 element 1 its setting, element 2 the second variable,
  105.                 element 3 its setting, etc.
  106.  
  107.         (g) Operators:
  108.                 The ternary C-operator  ?:  is not supported.
  109.                 All other arithmetic operators of C are supported, operating
  110.                 on int-operands.
  111.  
  112.                 Operators available for string-operands:
  113.  
  114.                         a + b           concatenates b to a
  115.                         +=              concatenation and assignment
  116.                         == != <= >= < > equality testing
  117.                         !a              empty string test
  118.                         a younger b     true if file a is more recent
  119.                         a older b       true if file b is more recent
  120.                         a newer b       synonym for younger
  121.  
  122.                     Note: Equality testing is also alphabetically, using the
  123.                           ordering of the ASCII-set. Internally strcmp() is
  124.                           used to compare strings.
  125.  
  126.                 Operators available for list-operands:
  127.  
  128.                         a + b           merging of lists
  129.                         a - b           opposite
  130.                         += -=           merging/subtraction and assignment
  131.                         == !=           equality testing
  132.                         !a              empty list test
  133.  
  134.                 Typecasts:
  135.  
  136.                         Strings may be cast to ints and vv. Strings may
  137.                         be cast to lists.
  138.  
  139.         (h) Predefined constants:
  140.  
  141.             Used with makelist():
  142.             ---------------------
  143.             O_ALL       8           O_FILE      1           O_DIR       2
  144.             O_SUBDIR    4
  145.  
  146.             Used with echo():
  147.             -----------------
  148.             OFF         0           ON          1
  149.  
  150.             Used with execute() and system() etc.:
  151.             --------------------------------------
  152.             P_CHECK     0           P_NOCHECK   1
  153.  
  154.             Used with stat():
  155.             -----------------
  156.             S_IFCHR     1           S_IFDIR     2           S_IFREG     4
  157.             S_IREAD     8           S_IWRITE   16           S_IEXEC    32
  158.  
  159. BUILT-IN FUNCTIONS:
  160.  
  161.         Note: In parameterlists below, the notation [type = value,] indicates
  162.               a default function argument of the indicated type and value.
  163.               An argument of the indicated type may be prvided to overrule the
  164.               default.
  165.  
  166.         arghead (string h)
  167.                 defines argument head, to be used with execute ()
  168.         argtail (string t)
  169.                 defines argument tail, to be used with execute ()
  170.         int ascii (string s)
  171.                 returns first character of 's' as an int; e.g.,
  172.                 ascii ("A") gives 65
  173.         string ascii (int i)
  174.                 returns i as a string, e.g., ascii (65) gives "A"
  175.         string change_base (string file, string newbase)
  176.                 changes basename of file, returns changed name
  177.         string change_ext (string file, string newext)
  178.                 changes extension of file, returns changed name
  179.         string change_path (string file, string newpath)
  180.                 changes path specification of file, returns changed name
  181.         string chdir ([int = P_CHECK,] string newdir)
  182.                 changes directory, returns the previous dir.
  183.                 Use "." for newdir to get current working directory.
  184.                 Use ""  for newdir to get startup working directory.
  185.         cmdhead (string h)
  186.                 defines command head, to be used with execute ()
  187.         cmdtail (string t)
  188.                 defines command tail, to be used with execute ()
  189.         echo (int opt)
  190.                 sets re-echoing of called programs, OFF for no echo (default:
  191.                 ON)
  192.         string element (int index, list lst)
  193.                 returns index-th string from list
  194.         string element (int index, string str)
  195.                 returns index-th character from string as a mini-string
  196.         exec ([int = P_CHECK,] string cmd, ...)
  197.                 runs command with arguments.
  198.         execute ([int = P_CHECK,] string cmd, string cmdhd, string arghd, ...,
  199.             string argtl, string cmdtl)
  200.                 same as exec(), except for command head/tail and argument
  201.                 head/tail. The actual executed program will start with the
  202.                 cmd, followed by the cmdhd. Next is a series of arguments,
  203.                 all enclosed by arghd and argtl. The command terminates with
  204.                 cmdtl.
  205.         int exists (string file)
  206.                 returns non-zero if file exists
  207.         list fgets (string file, int offset)
  208.                 reads next string from file at offset. Return value:
  209.                 element(0,retlist) is the read string (including \n),
  210.                 element(1,retlist) is the next offset to read.
  211.                 An empty return list signifies EOF.
  212.         fprintf (string file, ...)
  213.                 same as printf, but appends to file
  214.         string get_base (string file)
  215.                 returns basename of file
  216.         string get_ext (string file)
  217.                 returns extension of file
  218.         string getch ()
  219.                 returns keypress as mini-string
  220.         string get_path (string file)
  221.                 returns path of file
  222.         int getpid ()
  223.                 returns process-id (UNIX) or PSP-paragraph (DOS) of
  224.                 icm-exec
  225.         string gets ()
  226.                 returns string read from keyboard
  227.         list makelist ([int = O_FILE,] string mask)
  228.                 returns list of all files matching mask
  229.                 Use:
  230.                     O_ALL     to obtain all directory entries,
  231.                     O_DIR     to obtain a list of (sub)directories,
  232.                     O_FILE    (default) to obtain a list of only files,
  233.                     O_SUBDIR  to obtain a list of only subdirectories.
  234.         list makelist ([int = O_FILE,] string mask, newer, string comparefile)
  235.                 returns list of all files matching mask which are newer
  236.                 than the comparefile. Operator younger is synonymous to
  237.                 newer.
  238.         list makelist ([int = O_FILE,] string mask, older, string comparefile)
  239.                 see above; returns list of files older than the comparefile.
  240.         list makelist ([int = O_FILE,] string mask, newer, string comparefile)
  241.                 returns list of all files matching mask which are newer than
  242.                 the comparefile. Operator younger is synonymous to newer.
  243.         list makelist ([int = O_FILE,] string mask, older, string comparefile)
  244.                 see above; returns list of files which are older than the
  245.                 comparefile.
  246.         printf (...)
  247.                 prints arguments to screen
  248.         putenv (string)
  249.                 adds string to environment (as long as icmake is running).
  250.                 Use format: "VAR=value".
  251.         int sizeof (list l), int sizeoflist (list l)
  252.                 returns number of strings in list
  253.         list stat ([int = P_CHECK,] string entry)
  254.                 returns 'stat' information of directory entry 'entry' as a
  255.                 list. The following list-elements are defined:
  256.                     Element             Definition
  257.                     --------------------------------------
  258.                         0               attribute value
  259.                         1               size of the file
  260.                     --------------------------------------
  261.                 Attributes are  returned as bit-flags, composed from the
  262.                 following predefined constants:
  263.                     -----------------------------------------------------
  264.                     S_IFCHR     1       S_IFDIR     2       S_IFREG     4
  265.                     S_IREAD     8       S_IWRITE   16       S_IEXEC    32
  266.                     -----------------------------------------------------
  267.         int strlen (string s)
  268.                 returns number of characters in s (as C's strlen() function)
  269.         string strlwr (string s)
  270.                 returns lower-case duplicate of s
  271.         string strupr (string s)
  272.                 returns upper-case duplicate of s
  273.         list strtok (string str, string separators)
  274.                 returns list holding substrings of cut-up string
  275.         int substr (string big, string small)
  276.                 returns index in big where small occurs, or -1 if small does
  277.                 not occur in big
  278.         int system ([int = P_CHECK,] string command)
  279.                 runs command. Return value indicates exit status.
  280.  
  281. (end of info)
  282.