This file has been translated from LaTeX by HeVeA.

Node: Subsection 10-11-25,	Next: Subsection 10-11-26,	Prev: Subsection 10-11-24,	Up: Section 10-11
  

10.11.25   prompt-invisible-begin, prompt-invisible-end
=======================================================

<<   $(prompt-invisible-begin) : String
     $(prompt-invisible-end) : String
>>
  
  The 'prompt-invisible-begin' and 'prompt-invisible-end' functions
return the escape sequences that must used to mark the "invisible"
sections of the shell 'prompt' (such as various escape sequences). 

Node: Subsection 10-11-26,	Next: Subsection 10-11-27,	Prev: Subsection 10-11-25,	Up: Section 10-11
  

10.11.26   prompt-invisible
===========================

<<   $(prompt-invisible s) : Sequence
>>
  
  The 'prompt-invisible' will wrap its argument with
'$(prompt-invisible-begin)' and '$(prompt-invisible-end)'. All the
`invisible" sections of the shell 'prompt' (such as various escape
sequences) must be wrapped this way. 

Node: Subsection 10-11-27,	Next: Subsection 10-11-28,	Prev: Subsection 10-11-26,	Up: Section 10-11
  

10.11.27   gettimeofday
=======================

<<   $(gettimeofday) : Float
>>
  
  The 'gettimeofday' function returns the time of day in seconds since
January 1, 1970.

Node: Subsection 10-11-28,	Next: Subsection 10-11-29,	Prev: Subsection 10-11-27,	Up: Section 10-11
  

10.11.28   Tm
=============
 The 'Tm' object is a
structure that represents the time and date.
  
  
  'tm_sec' ': Int' Seconds (0--59). 
  'tm_min' ': Int' Minutes (0--59). 
  'tm_hour' ': Int' Hours (0--23). 
  'tm_mday' ': Int' Day of the month (0--31). 
  'tm_mon' ': Int' Month (0--11). 
  'tm_year' ': Int' Year (minus 1900). 
  'tm_wday' ': Int' Day of the week (0--6, Sunday is
   0). 
  'tm_yday' ': Int' Day of the year (0--365). 
  'tm_isdst' ': Bool' True iff daylight savings time
   is in effect. 
  

Node: Subsection 10-11-29,	Next: Subsection 10-11-30,	Prev: Subsection 10-11-28,	Up: Section 10-11
  

10.11.29   gmtime, localtime
============================
 
<<   $(gmtime time) : tm
     $(localtime time) : tm
         time : Float
>>
  
  Convert the time in seconds since the Unix epoch to calendar format.
The function 'gmtime' assumes UTC (Coordinated Universal Time); the
function 'localtime' uses the local time zone. 

Node: Subsection 10-11-30,	Next: Chapter 11,	Prev: Subsection 10-11-29,	Up: Section 10-11
  

10.11.30   mktime, normalize-time
=================================
 
<<   $(mktime tm) : Float
     $(normalize-time tm) : Tm
         tm : Tm
>>
  
  Convert the calendar time to time in seconds since the Unix epoch.
Assumes the local time zone.
  The fields 'tm_wday', 'tm_mday', 'tm_yday' are ignored. The other
components are not restricted to their normal ranges and will be
normalized as needed.
  The function 'normalize-time' normalizes the calendar time. The
returned object contains an additional field 'tm_time : Float' that
represnets the time in seconds since the Unix epoch (the same value
returned by 'mktime'). 

Node: Chapter 11,	Next: Section 11-1,	Prev: Section 10-11,	Up: Top
  

Chapter 11     Shell commands
*****************************
    
  Shell commands (commands to be executed by the operating system) can
be freely mixed with other code.
  NOTE: the syntax and shell usage is identical on all platforms,
including Win32. To avoid portability problems on Win32, it is
recommended that you avoid the use of the native shell interpreter
'cmd'.
<<    LIB = $(dir lib)
      println(The contents of the $(LIB) directory is:)
      ls $(LIB)
>>
  
* Menu:

* Section 11-1::	Simple commands
* Section 11-2::	Globbing
* Section 11-3::	Background jobs
* Section 11-4::	File redirection
* Section 11-5::	Pipelines
* Section 11-6::	Conditional execution
* Section 11-7::	Grouping
* Section 11-8::	What is a shell command?
* Section 11-9::	Basic builtin functions
* Section 11-10::	Job control builtin functions
* Section 11-11::	Command history


Node: Section 11-1,	Next: Section 11-2,	Prev: Chapter 11,	Up: Chapter 11
  

11.1   Simple commands
*=*=*=*=*=*=*=*=*=*=*=

  
  The syntax of shell commands is similar to the syntax used by the Unix
shell 'bash'. In general, a command is a pipeline. A basic command is
part of a pipeline. It is specified with the name of an executable and
some arguments. Here are some examples.
<<    ls
      ls -AF .
      echo Hello world
>>
  
  The command is found using the current search path in the variable
'PATH[]', which should define an array of directories containing
executables.
  A command may also be prefixed by environment variable definitions.
<<    # Prints "Hello world"
      env X="Hello world" Y=2 printenv X
      # Pass the include path to the Visual C++
      env include="c:\Program Files\Microsoft SDK\include" cl foo.cpp
>>
  

Node: Section 11-2,	Next: Section 11-3,	Prev: Section 11-1,	Up: Chapter 11
  

11.2   Globbing
*=*=*=*=*=*=*=*

  
  Commands may contain wildcard patterns. A pattern specifies a set of
files through a limited kind of regular expression. Patterns are
expanded before the function is executed.
<<   # List all files with a .c suffix
     ls *.c
  
     # List all files with a single character prefix, and .c suffix
     ls ?.c
  
     # Rename the file hello.ml to foo.ml
     mv {hello,foo}.ml
>>
  
  A comprehensive description of OMake glob patterns is given in
Section 10.4*Note Section 10-4::.

Node: Section 11-3,	Next: Section 11-4,	Prev: Section 11-2,	Up: Chapter 11
  

11.3   Background jobs
*=*=*=*=*=*=*=*=*=*=*=

  
  The command may also be placed in the background by placing an
ampersand after the command. Control returns to the shell without
waiting for the job to complete. The job continues to run in the
background.
<<    gcc -o hugeprogram *.c &
>>
  

Node: Section 11-4,	Next: Section 11-5,	Prev: Section 11-3,	Up: Chapter 11
  

11.4   File redirection
*=*=*=*=*=*=*=*=*=*=*=*

  
  Input and output can be redirected to files by using the '<', '>', and
'>&' directives after the command.
<<    # Write to the "foo" file
      echo Hello world > foo
  
      # Redirect input from the foo file
      cat < foo
  
      # Redirect standard output and errors to the foo file
      gcc -o boo *.c >& foo
>>
  

Node: Section 11-5,	Next: Section 11-6,	Prev: Section 11-4,	Up: Chapter 11
  

11.5   Pipelines
*=*=*=*=*=*=*=*=

  
  Pipelines are sequences of commands, where the output from each
command is sent to the next. Pipelines are defined with the '|' and '|&'
syntax. With '|' the output is redirected, but errors are not. With '|&'
both output and errors are redirected.
<<   # Send the output of the ls command to the printer
     ls *.c | lpr
  
     # Send output and errors to jyh as email
     gcc -o hugefile *.c |& mail jyh
>>
  

Node: Section 11-6,	Next: Section 11-7,	Prev: Section 11-5,	Up: Chapter 11
  

11.6   Conditional execution
*=*=*=*=*=*=*=*=*=*=*=*=*=*=

  
  Commands may also be composed though conditional evaluation using the
'||' and '&&' syntax. Every command has an integer exit code, which may
be zero or some other integer. A command is said to succeed if its exit
code is zero. The expression 'command1 && command2' executes 'command2'
only if 'command1' succeeds. The expression 'command1 || command2'
executes 'command2' only if 'command1' fails.
<<   # Display the x/y file if possible
     cd x && cat y
  
     # Run foo.exe, or print an error message
     (test -x foo.exe && foo.exe) || echo "foo.exe is not executable"
>>
  

Node: Section 11-7,	Next: Section 11-8,	Prev: Section 11-6,	Up: Chapter 11
  

11.7   Grouping
*=*=*=*=*=*=*=*

  
  Parenthesis are used for grouping in a pipeline or conditional
command. In the following expression, the 'test' function is used to
test whether the 'foo.exe' file is executable. If it is, the 'foo.exe'
file is executed. If the file is not executable (or if the 'foo.exe'
command fails), the message '"foo.exe is not executable"' is printed.
<<   # Run foo.exe, or print an error message
     (test -x foo.exe && foo.exe) || echo "foo.exe is not executable"
>>
  

Node: Section 11-8,	Next: Section 11-9,	Prev: Section 11-7,	Up: Chapter 11
  

11.8   What is a shell command?
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

  
  Syntactially, shell commands are any line that is not one of the
following:
  
  
   - A variable definition of the form 'VAR=string' 
   - A function call 'f(...)' or method call 'o.f(...)' 
   - A rule definition containing a colon 'string: ...' 
   - A special command, including the following: 
     
      - 'if ...' 
      - 'switch ...' 
      - 'match ...' 
      - 'section ...' 
      - 'return ...' 
  
  
  Commands may also be builtin (aliases). See the documentation for the
'Shell' object for more information.

Node: Section 11-9,	Next: Subsection 11-9-1,	Prev: Section 11-8,	Up: Chapter 11
  

11.9   Basic builtin functions
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

   
* Menu:

* Subsection 11-9-1::	echo
* Subsection 11-9-2::	cd


Node: Subsection 11-9-1,	Next: Subsection 11-9-2,	Prev: Section 11-9,	Up: Section 11-9
  

11.9.1   echo
=============

  The 'echo' function prints a string.
<<$(echo <args>)
  echo <args>
>>

Node: Subsection 11-9-2,	Next: Section 11-10,	Prev: Subsection 11-9-1,	Up: Section 11-9
  

11.9.2   cd
===========

  The 'cd' function changes the current directory.
<<    cd(dir)
         dir : Dir
>>
  
  The 'cd' function also supports a 2-argument form:
<<    $(cd dir, e)
         dir : Dir
         e : expression
>>
  
  In the two-argument form, expression 'e' is evaluated in the directory
'dir'. The current directory is not changed otherwise.
  The behavior of the 'cd' function can be changed with the 'CDPATH'
variable, which specifies a search path for directories. This is
normally useful only in the osh command interpreter.
<<    CDPATH : Dir Sequence
>>
  
  For example, the following will change directory to the first
directory './foo', '~/dir1/foo', '~/dir2/foo'.
<<    CDPATH[] =
         .
         $(HOME)/dir1
         $(HOME)/dir2
      cd foo
>>
  

Node: Section 11-10,	Next: Subsection 11-10-1,	Prev: Section 11-9,	Up: Chapter 11
  

11.10   Job control builtin functions
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 11-10-1::	jobs
* Subsection 11-10-2::	bg
* Subsection 11-10-3::	fg
* Subsection 11-10-4::	stop
* Subsection 11-10-5::	wait
* Subsection 11-10-6::	kill


Node: Subsection 11-10-1,	Next: Subsection 11-10-2,	Prev: Section 11-10,	Up: Section 11-10
  

11.10.1   jobs
==============

  The 'jobs' function prints a list of jobs.
  'jobs' 

Node: Subsection 11-10-2,	Next: Subsection 11-10-3,	Prev: Subsection 11-10-1,	Up: Section 11-10
  

11.10.2   bg
============

  The 'bg' function places a job in the background.
  'bg <pid...>' 

Node: Subsection 11-10-3,	Next: Subsection 11-10-4,	Prev: Subsection 11-10-2,	Up: Section 11-10
  

11.10.3   fg
============

  The 'fg' function brings a job to the foreground.
  'fg <pid...>' 

Node: Subsection 11-10-4,	Next: Subsection 11-10-5,	Prev: Subsection 11-10-3,	Up: Section 11-10
  

11.10.4   stop
==============

  The 'stop' function suspends a job.
  'stop <pid...>' 

Node: Subsection 11-10-5,	Next: Subsection 11-10-6,	Prev: Subsection 11-10-4,	Up: Section 11-10
  

11.10.5   wait
==============

  The 'wait' function waits for a job to finish. If no process
identifiers are given, the shell waits for all jobs to complete.
  'wait <pid...>' 

Node: Subsection 11-10-6,	Next: Section 11-11,	Prev: Subsection 11-10-5,	Up: Section 11-10
  

11.10.6   kill
==============

  The 'kill' function signals a job.
  'kill [signal] <pid...>' 

Node: Section 11-11,	Next: Subsection 11-11-1,	Prev: Section 11-10,	Up: Chapter 11
  

11.11   Command history
*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 11-11-1::	history


Node: Subsection 11-11-1,	Next: Chapter 12,	Prev: Section 11-11,	Up: Section 11-11
  

11.11.1   history
=================

<<    $(history-index) : Int
      $(history) : String Sequence
      history-file : File
      history-length : Int
>>
  
  The history variables manage the command-line history in osh. They
have no effect in omake.
  The 'history-index' variable is the current index into the
command-line history. The 'history' variable is the current command-line
history.
  The 'history-file' variable can be redefined if you want the
command-line history to be saved. The default value is
'~/.omake/osh_history'.
  The 'history-length' variable can be redefined to specify the maximum
number of lines in the history that you want saved. The default value is
'100'.   

Node: Chapter 12,	Next: Section 12-1,	Prev: Section 11-11,	Up: Top
  

Chapter 12     The standard objects
***********************************
    
  'Pervasives' defines the objects that are defined in all programs. The
following objects are defined.
* Menu:

* Section 12-1::	Pervasives objects


Node: Section 12-1,	Next: Subsection 12-1-1,	Prev: Chapter 12,	Up: Chapter 12
  

12.1   Pervasives objects
*=*=*=*=*=*=*=*=*=*=*=*=*

  
* Menu:

* Subsection 12-1-1::	Object
* Subsection 12-1-2::	Map
* Subsection 12-1-3::	Number
* Subsection 12-1-4::	Int
* Subsection 12-1-5::	Float
* Subsection 12-1-6::	Sequence
* Subsection 12-1-7::	Array
* Subsection 12-1-8::	String
* Subsection 12-1-9::	Fun
* Subsection 12-1-10::	Rule
* Subsection 12-1-11::	Target
* Subsection 12-1-12::	Node
* Subsection 12-1-13::	File
* Subsection 12-1-14::	Dir
* Subsection 12-1-15::	Channel
* Subsection 12-1-16::	InChannel
* Subsection 12-1-17::	OutChannel
* Subsection 12-1-18::	Location
* Subsection 12-1-19::	Exception
* Subsection 12-1-20::	RuntimeException
* Subsection 12-1-21::	UnbuildableException
* Subsection 12-1-22::	Shell


Node: Subsection 12-1-1,	Next: Subsection 12-1-2,	Prev: Section 12-1,	Up: Section 12-1
  

12.1.1   Object
===============

  Parent objects: none.
  The 'Object' object is the root object. Every class is a subclass of
'Object'.
  It provides the following fields:
  
  
   - '$(o.object-length)': the number of fields and methods in the
   object. 
   - '$(o.object-mem <var>)': returns 'true' iff the '<var>' is a field
   or method of the object. 
   - '$(o.object-add <var>, <value>)': adds the field to the object,
   returning a new object. 
   - '$(o.object-find <var>)': fetches the field or method from the
   object; it is equivalent to '$(o.<var>)', but the variable can be
   non-constant. 
   - '$(o.object-map <fun>)': maps a function over the object. The
   function should take two arguments; the first is a field name, the
   second is the value of that field. The result is a new object
   constructed from the values returned by the function. 
   - 'o.object-foreach': the 'object-foreach' form is equivalent to
   'object-map', but with altered syntax.
   <<   o.object-foreach(<var1>, <var2>) =>
           <body>
        >>
 
 For example, the following function prints all the fields of an object
   'o'.
   <<   PrintObject(o) =
           o.object-foreach(v, x) =>
              println($(v) = $(x))
        >>
 
 The 'export' form is valid in a 'object-foreach' body. The following
   function collects just the field names of an object.
   <<   FieldNames(o) =
           names[] =
           o.object-foreach(v, x) =>
              names[] += $(v)
              export
           return $(names)
        >>
  

Node: Subsection 12-1-2,	Next: Subsection 12-1-3,	Prev: Subsection 12-1-1,	Up: Section 12-1
  

12.1.2   Map
============

  Parent objects: 'Object'.
  A 'Map' object is a dictionary from values to values. The '<key>'
values are restricted to simple values: integers, floating-point
numbers, strings, files, directories, and arrays of simple values.
  The Map object provides the following methods.
  
  
   - '$(o.length)': the number of items in the map. 
   - '$(o.mem <key>)': returns 'true' iff the '<key>' is defined in the
   map. 
   - '$(o.add <key>, <value>)': adds the field to the map, returning a
   new map. 
   - '$(o.find <key>)': fetches the field from the map. 
   - '$(o.keys)': fetches an array of all the keys in the map, in
   alphabetical order. 
   - '$(o.values)': fetches an array of all the values in the map, in
   the alphabetical order of the corresponding keys. 
   - '$(o.map <fun>)': maps a function over the map. The function should
   take two arguments; the first is a field name, the second is the
   value of that field. The result is a new object constructed from the
   values returned by the function. 
   - 'o.foreach': the 'foreach' form is equivalent to 'map', but with
   altered syntax.
   <<   o.foreach(<var1>, <var2>) =>
           <body>
        >>
 
 For example, the following function prints all the fields of a map 'o'.
   <<   PrintMap(o) =
           o.foreach(v, x) =>
              println($(v) = $(x))
        >>
 
 The 'export' form is valid in a 'foreach' body. The following function
   reimplements the 'key' method.
   <<   FieldNames(o) =
           names =
           o.foreach(v, x) =>
              names += $(v)
              export
           return $(names)
        >>
  
  There is also simpler syntax when the key is a string. The table can
be defined using definitions with the form '$|key|' (the number of pipe
symbols '|' is allowed to vary).
<<    $|key 1| = value1
      $||key1|key2|| = value2    # The key is key1|key2
      X = $|key 1|               # Define X to be the value of field
$|key 1|
>>
  
  The usual modifiers are also allowed. The expression '$`|key|'
represents lazy evaluation of the key, and '$,|key|' is normal
evaluation.

Node: Subsection 12-1-3,	Next: Subsection 12-1-4,	Prev: Subsection 12-1-2,	Up: Section 12-1
  

12.1.3   Number
===============

  Parent objects: 'Object'.
  The 'Number' object is the parent object for integers and
floating-point numbers. 

Node: Subsection 12-1-4,	Next: Subsection 12-1-5,	Prev: Subsection 12-1-3,	Up: Section 12-1
  

12.1.4   Int
============

  Parent objects: 'Number'.
  The 'Int' object represents integer values. 

Node: Subsection 12-1-5,	Next: Subsection 12-1-6,	Prev: Subsection 12-1-4,	Up: Section 12-1
  

12.1.5   Float
==============

  Parent objects: 'Number'.
  The 'Float' object represents floating-point numbers. 

Node: Subsection 12-1-6,	Next: Subsection 12-1-7,	Prev: Subsection 12-1-5,	Up: Section 12-1
  

12.1.6   Sequence
=================

  Parent objects: 'Object'.
  The 'Sequence' object represents a generic object containing
sequential elements. It provides the following methods.
  
  
   - '$(s.length)': the number of elements in the sequence. 
   - '$(s.is-nonempty)': true iff the expression '$(s.nth 0)' will
   complete without failure. 
   - '$(s.nth <i>)': return the n'th element of the sequence. 
   - '$(s.nth-tl <i>)': return the n'th tail of the sequence. 
   - '$(s.map <fun>)': maps a function over the fields in the sequence.
   The function should take one argument. The result is a new sequence
   constructed from the values returned by the function. 
   - 's.foreach': the 'foreach' form is equivalent to 'map', but with
   altered syntax.
   <<   s.foreach(<var>) =>
           <body>
        >>
 
 For example, the following function prints all the elements of the
   sequence.
   <<   PrintSequence(s) =
           s.foreach(x) =>
              println(Elem = $(x))
        >>
 
 The 'export' form is valid in a 'foreach' body. The following function
   counts the number of zeros in the sequence.
   <<   Zeros(s) =
           count = $(int 0)
           s.foreach(v) =>
              if $(equal $(v), 0)
                 count = $(add $(count), 1)
                 export
              export
           return $(count)
        >>
 
 
   - '$(s.forall <fun>)': tests whether each element of the sequence
   satifies a predicate. 
   - '$(s.exists <fun>)': tests whether the sequence contains an element
   that satisfies a predicate. 
   - '$(s.sort <fun>)': sorts a sequence. The '<fun>' is a comparison
   function. It takes two elements '(x, y)' of the sequence, compares
   them, and returns a negative number if x < y, a positive number if x
   > y, and zero if the two elements are equal.
   <<  osh> items = $(int 0 3 -2)
       osh> items.forall(x => $(gt $x, 0))
       - : bool = false
       osh> items.exists(x => $(gt $x, 0))
       - : bool = true
       osh> items.sort($(compare))
       - : Array = -2 3 0
       >>
 
   

Node: Subsection 12-1-7,	Next: Subsection 12-1-8,	Prev: Subsection 12-1-6,	Up: Section 12-1
  

12.1.7   Array
==============

  Parent objects: 'Sequence'.
  The 'Array' is a random-access sequence. It provides the following
additional methods.
  
  
   - '$(s.nth <i>)': returns element 'i' of the sequence. 
   - '$(s.rev <i>)': returns the reversed sequence. 
  

Node: Subsection 12-1-8,	Next: Subsection 12-1-9,	Prev: Subsection 12-1-7,	Up: Section 12-1
  

12.1.8   String
===============

  Parent objects: 'Array'. 

Node: Subsection 12-1-9,	Next: Subsection 12-1-10,	Prev: Subsection 12-1-8,	Up: Section 12-1
  

12.1.9   Fun
============

  Parent objects: 'Object'.
  The 'Fun' object provides the following methods. 
  
   - '$(f.arity)': the arity if the function. 
   

Node: Subsection 12-1-10,	Next: Subsection 12-1-11,	Prev: Subsection 12-1-9,	Up: Section 12-1
  

12.1.10   Rule
==============

  Parent objects: 'Object'.
  The 'Rule' object represents a build rule. It does not currently have
any methods. 

Node: Subsection 12-1-11,	Next: Subsection 12-1-12,	Prev: Subsection 12-1-10,	Up: Section 12-1
  

12.1.11   Target
================

  Parent object: 'Object'.
  The 'Target' object contains information collected for a specific
target file.
  
  
   - 'target': the target file. 
   - 'effects': the files that may be modified by a side-effect when
   this target is built. 
   - 'scanner_deps': static dependencies that must be built before this
   target can be scanned. 
   - 'static-deps': statically-defined build dependencies of this
   target. 
   - 'build-deps': all the build dependencies for the target, including
   static and scanned dependencies. 
   - 'build-values': all the value dependencies associated with the
   build. 
   - 'build-commands': the commands to build the target. 
   - 'output-file': if output was diverted to a file, with one of the
   '--output-*' options A*Note Appendix A::, this field names
   that file. Otherwise it is 'false'. 
  
  The object supports the following methods.
  
  
   - 'find(file)': returns a Target object for the given file. Raises a
   'RuntimeException' if the specified target is not part of the
   project. 
   - 'find-optional(file)': returns a 'Target' object for the given
   file, or 'false' if the file is not part of the project. 
  
  NOTE: the information for a target is constructed dynamically, so it
is possible that the 'Target' object for a node will contain different
values in different contexts. The easiest way to make sure that the
'Target' information is complete is to compute it within a rule body,
where the rule depends on the target file, or the dependencies of the
target file. 

Node: Subsection 12-1-12,	Next: Subsection 12-1-13,	Prev: Subsection 12-1-11,	Up: Section 12-1
  

12.1.12   Node
==============

  Parent objects: 'Object'.
  The 'Node' object is the parent object for files and directories. It
supports the following operations. 
  
   - '$(node.stat)': returns a 'stat' object for the file. If the file
   is a symbolic link, the 'stat' information is for the destination of
   the link, not the link itself.
 
   - '$(node.lstat)': returns a 'stat' object for the file or symbolic
   link. 
   - '$(node.unlink)': removes the file. 
   - '$(node.rename <file>)': renames the file. 
   - '$(node.link <file>)': creates a hard link '<dst>' to this file. 
   - '$(node.symlink <file>)': create a symbolic link '<dst>' to this
   file. 
   - '$(node.chmod <perm>)': change the permission of this file. 
   - '$(node.chown <uid>, <gid>)': change the owner and group id of this
   file. 
   

Node: Subsection 12-1-13,	Next: Subsection 12-1-14,	Prev: Subsection 12-1-12,	Up: Section 12-1
  

12.1.13   File
==============

  Parent objects: 'Node'.
  The file object represents the name of a file. 

Node: Subsection 12-1-14,	Next: Subsection 12-1-15,	Prev: Subsection 12-1-13,	Up: Section 12-1
  

12.1.14   Dir
=============

  Parent objects: 'Node'.
  The 'Dir' object represents the name of a directory. 

Node: Subsection 12-1-15,	Next: Subsection 12-1-16,	Prev: Subsection 12-1-14,	Up: Section 12-1
  

12.1.15   Channel
=================

  Parent objects: 'Object'.
  A 'Channel' is a generic IO channel. It provides the following
methods. 
  
   - '$(o.close)': close the channel. 
   - '$(o.name)': returns the file name associated with the channel. 
   

Node: Subsection 12-1-16,	Next: Subsection 12-1-17,	Prev: Subsection 12-1-15,	Up: Section 12-1
  

12.1.16   InChannel
===================

  Parent objects: 'Channel'.
  A 'InChannel' is an input channel. The variable 'stdin' is the
standard input channel.
  It provides the following methods. 
  
   - '$(InChannel.fopen <file>)': open a new input channel. 
   - '$(InChannel.of-string <string>)': open a new input channel, using
   a string as input. 
   - '$(o.read <number>)': reads the given number of characters from the
   channel 
   - '$(o.readln)': reads a line from the channel 
   

Node: Subsection 12-1-17,	Next: Subsection 12-1-18,	Prev: Subsection 12-1-16,	Up: Section 12-1
  

12.1.17   OutChannel
====================

  Parent object: 'Channel'.
  A 'OutChannel' is an output channel. The variables 'stdout' and
'stderr' are the standard output and error channels.
  It provides the following methods. 
  
   - '$(OutChannel.fopen <file>)': open a new output channel. 
   - '$(OutChannel.string)': open a new output channel, writing to a
   string. 
   - '$(OutChannel.to-string)': get the current string of output, for an
   output channel created as 'OutChannel.open-string'. 
   - '$(OutChannel.append <file>)': opens a new output channel,
   appending to the file. 
   - '$(c.flush)': flush the output channel. 
   - '$(c.print <string>)': print a string to the channel. 
   - '$(c.println <string>)': print a string to the channel, followed by
   a line terminator. 
   

Node: Subsection 12-1-18,	Next: Subsection 12-1-19,	Prev: Subsection 12-1-17,	Up: Section 12-1
  

12.1.18   Location
==================

  Parent objects: 'Location'.
  The 'Location' object represents a location in a file. 

Node: Subsection 12-1-19,	Next: Subsection 12-1-20,	Prev: Subsection 12-1-18,	Up: Section 12-1
  

12.1.19   Exception
===================

  Parent objects: 'Object'.
  The 'Exception' object is used as the base object for exceptions. It
has no fields. 

Node: Subsection 12-1-20,	Next: Subsection 12-1-21,	Prev: Subsection 12-1-19,	Up: Section 12-1
  

12.1.20   RuntimeException
==========================

  Parent objects: 'Exception'.
  The 'RuntimeException' object represents an exception from the runtime
system. It has the following fields.
  
  
   - 'position': a string representing the location where the exception
   was raised. 
   - 'message': a string containing the exception message. 
   

Node: Subsection 12-1-21,	Next: Subsection 12-1-22,	Prev: Subsection 12-1-20,	Up: Section 12-1
  

12.1.21   UnbuildableException
==============================

  Parent objects: 'Exception'.
  The 'UnbuildableException' object should be used to signal that a
target is not buildable. It will be caught by functions such as
'target-exists'. This exception has the following fields:
  
  
   - 'target': indicates which target is not buildable. 
   - 'message': a string containing the exception message. 
   

Node: Subsection 12-1-22,	Next: Chapter 13,	Prev: Subsection 12-1-21,	Up: Section 12-1
  

12.1.22   Shell
===============

  Parent objects: 'Object'.
  The 'Shell' object contains the collection of builtin functions
available as shell commands.
  You can define aliases by extending this object with additional
methods. All methods in this class are called with one argument: a
single array containing an argument list.
  
  
   - 'echo'
 The 'echo' function prints its arguments to the standard output
   channel. 
   - 'jobs'
 The 'jobs' method prints the status of currently running commands. 
   - 'cd'
 The 'cd' function changes the current directory. Note that the current
   directory follows the usual scoping rules. For example, the following
   program lists the files in the 'foo' directory, but the current
   directory is not changed.
   <<   section
           echo Listing files in the foo directory...
           cd foo
           ls
     
        echo Listing files in the current directory...
        ls
   >>
 
   - 'bg'
 The 'bg' method places a job in the background. The job is resumed if
   it has been suspended. 
   - 'fg'
 The 'fg' method brings a job to the foreground. The job is resumed if
   it has been suspended. 
   - 'stop'
 The 'stop' method suspends a running job. 
   - 'wait'
 The 'wait' function waits for a running job to terminate. It is not
   possible to wait for a suspended job.
 The job is not brought to the foreground. If the 'wait' is interrupted,
   the job continues to run in the background. 
   - 'kill'
 The 'kill' function signal a job.
 'kill [signal] <pid...>'.
 The signals are either numeric, or symbolic. The symbolic signals are
   named as follows.
 ABRT, ALRM, HUP, ILL, KILL, QUIT, SEGV, TERM, USR1, USR2, CHLD, STOP,
   TSTP, TTIN, TTOU, VTALRM, PROF. 
   - 'exit'
 The 'exit' function terminates the current session. 
   - 'which', 'where'
 See the documentation for the corresponding functions. 
   - 'rehash'
 Reset the search path. 
   - 'ln-or-cp' src dst
 Links or copies src to dst, overwriting dst. Namely, 'ln-or-cp' would
   first delete the dst file (unless it is a directory), if it exists.
   Next it would try to create a symbolic link dst poiting to src (it
   will make all the necessary adjustmnents of relative paths). If
   symbolic link can not be created (e.g. the OS or the filesystem does
   not support symbolic links), it will try to create a hard link. If
   that fails too, it will try to forcibly copy src to dst. 
   - 'history'
 Print the current command-line history. 
   - 'digest'
 Print the digests of the given files. 
   - Win32 functions.
 Win32 doesn't provide very many programs for scripting, except for the
   functions that are builtin to the DOS 'cmd.exe'. The following
   functions are defined on Win32 and only on Win32. On other systems,
   it is expected that these programs already exist.
 
     
      - 'grep'
      <<   grep [-q] [-n] [-v] [-h] pattern files...
      >>
    
    The 'grep' alias calls the omake's internal 'grep' function. 
 
 By default, omake uses internal versions of the following commands:
   'cp', 'mv', 'cat', 'rm', 'mkdir', 'chmod', 'test', 'find'. If you
   really want to use the standard system versions of these commands,
   set the 'USE_SYSTEM_COMMANDS' as one of the first definitions in your
   'OMakeroot' file.
 
     
      - 'pwd'
      <<    pwd
      >>
    
    The 'pwd' alias would print the absolute path to current directory. 
      - 'mkdir'
      <<    mkdir [-m <mode>] [-p] files
      >>
    
    The 'mkdir' function is used to create directories. The -verb+-m+
      option can be used to specify the permission mode of the created
      directory. If the '-p' option is specified, the full path is
      created. 
      - 'cp', 'mv'
      <<    cp [-f] [-i] [-v] src dst
            cp [-f] [-i] [-v] files dst
            mv [-f] [-i] [-v] src dst
            mv [-f] [-i] [-v] files dst
      >>
    
    The 'cp' function copies a 'src' file to a 'dst' file, overwriting
      it if it already exists. If more than one source file is
      specified, the final file must be a directory, and the source
      files are copied into the directory.
    
        
       -f  Copy files forcibly, do not prompt. 
       -i  Prompt before removing destination files. 
       -v  Explain what is happening. 
     
      - 'rm'
      <<   rm [-f] [-i] [-v] [-r] files
           rmdir [-f] [-i] [-v] [-r] dirs
      >>
    
    The 'rm' function removes a set of files. No warnings are issued if
      the files do not exist, or if they cannot be removed.
    Options: 
        
       -f  Forcibly remove files, do not prompt. 
       -i  Prompt before removal. 
       -v  Explain what is happening. 
       -r  Remove contents of directories recursively. 
     
      - 'chmod'
      <<    chmod [-r] [-v] [-f] mode files
      >>
    
    The 'chmod' function changes the permissions on a set of files or
      directories. This function does nothing on Win32. The 'mode' may
      be specified as an octal number, or in symbolic form
      '[ugoa]*['-=][rwxXstugo]+. See the man page for 'chmod' for
      details.
    Options: 
        
       -r  Change permissions of all files in a directory recursively. 
       -v  Explain what is happening. 
       -f  Continue on errors. 
     
      - 'cat'
      <<   cat files...
      >>
    
    The 'cat' function prints the contents of the files to stdout 
      - 'test'
    'test' expression
     '[' expression +]+
     '[ --help'
     '[ --version'
     See the documentation for the 'test' function.
    
      - 'find'
    'find' expression
    See the documentation for the 'find' function.
  
   

Node: Chapter 13,	Next: Section 13-1,	Prev: Section 12-1,	Up: Top
  

Chapter 13     Build functions and utilities
********************************************
     
* Menu:

* Section 13-1::	Builtin .PHONY targets
* Section 13-2::	Options and versioning
* Section 13-3::	Examining the dependency graph
* Section 13-4::	The OMakeroot file
* Section 13-5::	Building C and C++ code
* Section 13-6::	Building OCaml code
* Section 13-7::	Building LaTeX files


Node: Section 13-1,	Next: Section 13-2,	Prev: Chapter 13,	Up: Chapter 13
  

13.1   Builtin .PHONY targets
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

  
  The complete set of builtin '.PHONY' targets include the following.
  
  
 .PHONY  Declares new phony targets
   (Section 8.10*Note Section 8-10::). 
 .DEFAULT  Declare the default build targets
   (Section 8.7*Note Section 8-7::). 
 .SUBDIRS  Include a directory as part of the project
   (Section 8.8*Note Section 8-8::). 
 .SCANNER  Define a dependency scanner
   (Section 8.8*Note Section 8-8::). 
 .INCLUDE  Include a file (Section 8.9*Note Section 8-9::). 
 .ORDER  Define a file-dependency ordering rule
   (Section 10.3.6*Note Subsection 10-3-6::). 
 .BUILD_BEGIN  Commands to be executed at the beginning of a build. 
 .BUILD_SUCCESS  Commands to be executed if the build is successful. 
 .BUILD_FAILURE  Commands to be executed if the build fails. 
  



  The '.BUILD' targets can be used to specify commands to be executed at
the beginning and end of the build. The '.BUILD_BEGIN' target is built
at the beginning of a project build, and one of '.BUILD_FAILURE' or
'.BUILD_SUCCESS' is executed when the build terminates.
  For example, the following set of rules simply print additional
messages about the status of the build.
<<   .BUILD_BEGIN:
         echo Build starting
  
     .BUILD_SUCCESS:
         echo The build was successful
  
     .BUILD_FAILURE:
         println($"The build failed: $(length $(find-build-targets
Failed)) targets could not be built")
>>
  
  Another common use is to define notifications to be performed when the
build completes. For example, the following rule will create a new X
terminal displaying the summary of the build (using the 'BUILD_SUMMARY'
variable).
<<    .BUILD_FAILURE:
          xterm -e vi $(BUILD_SUMMARY)
>>
  
  If you do not wish to add these rules directly to your project (which
is probably a good idea if you work with others), you can define them in
your '.omakerc' (see Section A.8*Note Section A-8::).
  The 'find-build-targets' function is useful for obtaining a firther
summary of the build. Note that when output diversions are in effect
(with the '--output-*' options --- see
Chapter A*Note Appendix A::), any output produced by the
commands is copied to a file. The name of the file is specified by the
'output-file' field of the 'Target' object. You may find this useful in
defining custom build summaries. 

Node: Section 13-2,	Next: Subsection 13-2-1,	Prev: Section 13-1,	Up: Chapter 13
  

13.2   Options and versioning
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 13-2-1::	OMakeFlags
* Subsection 13-2-2::	OMakeVersion
* Subsection 13-2-3::	cmp-versions
* Subsection 13-2-4::	DefineCommandVars


Node: Subsection 13-2-1,	Next: Subsection 13-2-2,	Prev: Section 13-2,	Up: Section 13-2
  

13.2.1   OMakeFlags
===================

<<   OMakeFlags(options)
        options : String
>>
  
  The 'OMakeFlags' function is used to set 'omake' options from within
OMakefiles. The options have exactly the same format as options on the
command line.
  For example, the following code displays the progress bar unless the
'VERBOSE' environment variable is defined.
<<    if $(not $(defined-env VERBOSE))
          OMakeFlags(-S --progress)
          export
>>

Node: Subsection 13-2-2,	Next: Subsection 13-2-3,	Prev: Subsection 13-2-1,	Up: Section 13-2
  

13.2.2   OMakeVersion
=====================

<<   OMakeVersion(version1)
     OMakeVersion(version1, version2)
        version1, version2 : String
>>
  
  The 'OMakeVersion' function is used for version checking in
OMakefiles. It takes one or two arguments.
  In the one argument form, if the omake version number is less than
'<version1>', then an exception is raised. In the two argument form, the
version must lie between 'version1' and 'version2'.

Node: Subsection 13-2-3,	Next: Subsection 13-2-4,	Prev: Subsection 13-2-2,	Up: Section 13-2
  

13.2.3   cmp-versions
=====================
 
<<   $(cmp-versions version1, version2)
        version1, version2 : String
>>
  
  The 'cmp-versions\' functions can be used to compare arbitrary version
strings. It returns 0 when the two version strings are equal, a negative
number when the first string represents an earlier version, and a
positive number otherwise. 

Node: Subsection 13-2-4,	Next: Section 13-3,	Prev: Subsection 13-2-3,	Up: Section 13-2
  

13.2.4   DefineCommandVars
==========================

<<   DefineCommandVars()
>>
  
  The 'DefineCommandVars' function redefines the variables passed on the
commandline. Variables definitions are passed on the command line in the
form 'name=value'. This function is primarily for internal use by omake
to define these variables for the first time. 

Node: Section 13-3,	Next: Subsection 13-3-1,	Prev: Section 13-2,	Up: Chapter 13
  

13.3   Examining the dependency graph
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*

   
* Menu:

* Subsection 13-3-1::	dependencies, dependencies-all, dependencies-proper
* Subsection 13-3-2::	target
* Subsection 13-3-3::	find-build-targets
* Subsection 13-3-4::	project-directories
* Subsection 13-3-5::	rule
* Subsection 13-3-6::	build


Node: Subsection 13-3-1,	Next: Subsection 13-3-2,	Prev: Section 13-3,	Up: Section 13-3
  

13.3.1   dependencies, dependencies-all, dependencies-proper
============================================================

<<   $(dependencies targets) : File Array
     $(dependencies-all targets) : File Array
     $(dependencies-proper targets) : File Array
        targets : File Array
     raises RuntimeException
>>
  
  The 'dependencies' function returns the set of immediate dependencies
of the given targets. This function can only be used within a rule body
and all the arguments to the 'dependency' function must also be
dependencies of this rule. This restriction ensures that all the
dependencies are known when this function is executed.
  The 'dependencies-all' function is similar, but it expands the
dependencies recursively, returning all of the dependencies of a target,
not just the immediate ones.
  The 'dependencies-proper' function returns all recursive dependencies,
except the dependencies that are leaf targets. A leaf target is a target
that has no dependencies and no build commands; a leaf target
corresponds to a source file in the current project.
  In all three functions, files that are not part of the current project
are silently discarded. All three functions will return phony and
scanner targets along with the "real" ones.
  One purpose of the 'dependencies-proper' function is for "clean"
targets. For example, one way to delete all intermediate files in a
build is with a rule that uses the 'dependencies-proper'. Note however,
that the rule requires building the project before it can be deleted.
<<    .PHONY: clean
  
      APP = ...     # the name of the target application
      clean: $(APP)
         rm -f $(dependencies-proper $(APP))
>>
  
  Also note that the 'dependencies-proper' function will return the
phony and scanner targets in addition to real one.
  For other (possibly better) alternatives, see
Section 10.3.3*Note Subsection 10-3-3:: and 'filter-proper-targets'
function. 

Node: Subsection 13-3-2,	Next: Subsection 13-3-3,	Prev: Subsection 13-3-1,	Up: Section 13-3
  

13.3.2   target
===============
 
<<   $(target targets) : Target Array
        targets : File Sequence
     raises RuntimeException
>>
  
  The 'target' function returns the Target object associated with each
of the targets. See the 'Target' object for more information. 

Node: Subsection 13-3-3,	Next: Subsection 13-3-4,	Prev: Subsection 13-3-2,	Up: Section 13-3
  

13.3.3   find-build-targets
===========================

<<    $(find-build-targets tag) : Target Array
         tag : Succeeded | Failed
>>
  
  The 'find-build-targets' allow the results of the build to be
examined. The 'tag' must specifies which targets are to be returned; the
comparison is case-insensitive.
  
  
 Succeeded  The list of targets that were built successfully. 
 Failed  The list of targets that could not be built. 
  
  These are used mainly in conjuction with the '.BUILD_SUCCESS'
(Section 13.1*Note Section 13-1::) and '.BUILD_FAILURE'
(Section 13.1*Note Section 13-1::) phony targets. For
example, adding the following to your project 'OMakefile' will print the
number of targets that failed (if the build failed).
<<    .BUILD_FAILURE:
          echo "Failed target count: $(length $(find-build-targets
Failed))"
>>

Node: Subsection 13-3-4,	Next: Subsection 13-3-5,	Prev: Subsection 13-3-3,	Up: Section 13-3
  

13.3.4   project-directories
============================

<<   $(project-directories) : Dir Array
>>
  
  The 'project-directories' function returns the list of all directories
that are considered to be part of the project.
  To get the complete directory list, this function should be called
from within a rule body. 

Node: Subsection 13-3-5,	Next: Subsection 13-3-6,	Prev: Subsection 13-3-4,	Up: Section 13-3
  

13.3.5   rule
=============

  The 'rule' function is called whenever a build rule is defined. It is
unlikely that you will need to redefine this function, except in very
exceptional cases.
<<   rule(multiple, target, pattern, sources, options, body) : Rule
        multiple : String
        target   : Sequence
        pattern  : Sequence
        sources  : Sequence
        options  : Array
        body     : Body
>>
  
  The 'rule' function is called when a rule is evaluated.
  
  
 multiple  A Boolean value indicating whether the rule was defined with
   a double colon '::'. 
 target  The sequence of target names. 
 pattern  The sequence of patterns. This sequence will be empty for
   two-part rules. 
 sources  The sequence of dependencies. 
 options  An array of options. Each option is represented as a 'Map'
   object associating each specified option with a value. 
 body  The body expression of the rule. 
  
  Consider the following rule.
<<   target: pattern: sources :name1: option1 :name2: option2
        expr1
        expr2
>>
  
  This expression represents the following function call, where square
brackets are used to indicate arrays, and the curly brackets represent a
'Map' object.
<<   rule(false, target, pattern, sources,
          { $|:name1:| = option1; $|:name2:| = option2 }
          [expr1; expr2])
>>

Node: Subsection 13-3-6,	Next: Section 13-4,	Prev: Subsection 13-3-5,	Up: Section 13-3
  

13.3.6   build
==============

<<    build(targets : File Array) : bool
>>
  
  Build the given targets. The value is true iff the build was
successful. This function can be used only in 'osh'.  

Node: Section 13-4,	Next: Subsection 13-4-1,	Prev: Section 13-3,	Up: Chapter 13
  

13.4   The OMakeroot file
*=*=*=*=*=*=*=*=*=*=*=*=*

   
  The standard OMakeroot file defines the functions are rules for
building standard projects.
* Menu:

* Subsection 13-4-1::	Variables
* Subsection 13-4-2::	System variables


Node: Subsection 13-4-1,	Next: Subsection 13-4-2,	Prev: Section 13-4,	Up: Section 13-4
  

13.4.1   Variables
==================
   
 ROOT
 The root directory of the current
project. 
 CWD
 The current working directory (the
directory is set for each OMakefile in the project). 
 EMPTY
 The empty string. 
 STDROOT
 The name of the standard installed
OMakeroot file. 
 ABORT_ON_COMMAND_ERROR
 If set to true, the construction of a
target should be aborted whenever one of the commands to build it fail.
This defaults to true, and should normally be left that way.
 SCANNER_MODE
 This variable should be defined as one
of four values (defaults to 'enabled'). 
  
 enabled  Allow the use of default '.SCANNER' rules. Whenever a rule
   does not specify a ':scanner:' dependency explicitly, try to find a
   '.SCANNER' with the same target name. 
 disabled  Never use default '.SCANNER' rules. 
 warning  Allow the use of default '.SCANNER' rules, but print a warning
   whenever one is selected. 
 error  Do not allow the use of default '.SCANNER' rules. If a rule does
   not specify a ':scanner:' dependency, and there is a default
   '.SCANNER' rule, the build will terminate abnormally. 
   

Node: Subsection 13-4-2,	Next: Section 13-5,	Prev: Subsection 13-4-1,	Up: Section 13-4
  

13.4.2   System variables
=========================
  
 INSTALL
 The command to install a program
('install' on 'Unix', 'cp' on 'Win32'). 
 PATHSEP
 The normal path separator (':' on
'Unix', ';' on 'Win32'). 
 DIRSEP
 The normal directory separator ('/' on
'Unix', '\' on 'Win32'). 
 EXT_OBJ
 File suffix for an object file
(default is '.o' on 'Unix', and '.obj' on 'Win32'). 
 EXT_LIB
 File suffix for a static library
(default is '.a' on 'Unix', and '.lib' on 'Win32'). 
 EXT_DLL
 File suffix for a shared library
(default is '.so' on 'Unix', and '.dll' on 'Win32'). 
 EXT_ASM
 File suffix for an assembly file
(default is '.s' on 'Unix', and '.asm' on 'Win32'). 
 EXE
 File suffix for executables (default
is empty for 'Unix', and '.exe' on 'Win32' and 'Cygwin'). 

Node: Section 13-5,	Next: Subsection 13-5-1,	Prev: Section 13-4,	Up: Chapter 13
  

13.5   Building C and C++ code
*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

  
  OMake provides extensive support for building C and C++ programs. In
order to use the functions defined in this section, you need to make
sure the line 
<<open build/C
>>
  is present in your 'OMakeroot' file.
* Menu:

* Subsection 13-5-1::	Autoconfiguration variables
* Subsection 13-5-2::	C and C++ configuration variables
* Subsection 13-5-3::	Generated C files
* Subsection 13-5-4::	Building C programs and Libraries


Node: Subsection 13-5-1,	Next: Subsection 13-5-2,	Prev: Section 13-5,	Up: Section 13-5
  

13.5.1   Autoconfiguration variables
====================================
   These variables will get defined based on the "autoconf-style"
'static.' tests executed when you run OMake for the first time. You can
use them to configure your project accordingly, and you should not
redefine them.
  You can use the '--configure' command line option
(Section A.3.9*Note Subsection A-3-9::) to force re-execution of
all the tests.
  A different set of autoconfiguration tests is performed depending on
the build environment involved --- one set of tests would be performed
in a 'Win32' environment, and another --- in a Unix-like environment
(including Linux, OS X and Cygwin).
  

13.5.1.1   Unix-like systems
----------------------------
   
 GCC_FOUND
 A boolean flag specifying whether the
'gcc' binary was found in your path. 
 GXX_FOUND
 A boolean flag specifying whether the
'g++' binary was found in your path.
  

13.5.1.2   Win32
----------------
   
 CL_FOUND
 A boolean flag specifying whether the
'cl' binary was found in your path. 
 LIB_FOUND
 A boolean flag specifying whether the
'lib' binary was found in your path.

Node: Subsection 13-5-2,	Next: Subsection 13-5-3,	Prev: Subsection 13-5-1,	Up: Section 13-5
  

13.5.2   C and C++ configuration variables
==========================================
  
  The following variables can be redefined in your project.
 CC
 The name of the C compiler (on 'Unix'
it defaults to 'gcc' when 'gcc' is present and to 'cc' otherwise; on
'Win32' defaults to 'cl /nologo'). 
 CXX
 The name of the C++ compiler (on
'Unix' it defaults to 'gcc' when 'gcc' is present and to 'c'++
otherwise; on 'Win32' defaults to 'cl /nologo'). 
 CPP
 The name of the C preprocessor
(defaults to 'cpp' on 'Unix', and 'cl /E' on 'Win32'). 
 CFLAGS
 Compilation flags to pass to the C
compiler (default empty on 'Unix', and '/DWIN32' on 'Win32'). 
 CXXFLAGS
 Compilation flags to pass to the C++
compiler (default empty on 'Unix', and '/DWIN32' on 'Win32'). 
 INCLUDES
 Additional directories that specify
the search path to the C and C++ compilers (default is '.'). The
directories are passed to the C and C++ compilers with the '-I' option.
The include path with '-I' prefixes is defined in the
'PREFIXED_INCLUDES' variable. 
 LIBS
 Additional libraries needed when
building a program (default is empty). 
 CCOUT
 The option to use for specifying the
output file in C and C++ compilers (defaults to '-o' on 'Unix' and '/Fo'
on 'Win32'). 
 AS
 The name of the assembler (defaults to
'as' on 'Unix', and 'ml' on 'Win32'). 
 ASFLAGS
 Flags to pass to the assembler
(default is empty on 'Unix', and '/c /coff' on 'Win32'). 
 ASOUT
 The option string that specifies the
output file for 'AS' (defaults to '-o' on 'Unix' and '/Fo' on 'Win32'). 
 AR
 The name of the program to create
static libraries (defaults to 'ar cq' on 'Unix', and 'lib' on 'Win32'). 
 LD
 The name of the linker (defaults to
'ld' on 'Unix', and 'cl' on 'Win32'). 
 LDFLAGS
 Options to pass to the linker (default
is empty). 
 LDFLAGS_DLL
 Options to pass to the linker when
compiling a shared library (defaults to '-shared' on 'Unix' and '/DLL'
on 'Win32'). 
 LDOUT
 The option to use for specifying the
output file in C and C++ linkers (defaults to '-o' on 'Unix' and '/Fe'
on 'Win32'). 
 YACC
 The name of the 'yacc' parser
generator (default is 'yacc' on 'Unix', empty on 'Win32'). 
 LEX
 The name of the 'lex' lexer generator
(default is 'lex' on 'Unix', empty on 'Win32'). 
