This file has been translated from LaTeX by HeVeA.

File: omake-doc, Node: Subsection 10-11-22,	Next: Subsection 10-11-23,	Prev: Subsection 10-11-21,	Up: Section 10-11
  

10.11.22   tgetstr
==================

<<   $(tgetstr id) : String
        id : String
>>
  
  The tgetstr function looks up the terminal capability with the
indicated id. This assumes the terminfo to lookup is given in the TERM
environment variable. This function returns an empty value if the given
terminal capability is not defined.
  Note: if you intend to use the value returned by tgetstr inside the
shell 'prompt', you need to wrap it using the 'prompt-invisible'
function. 

File: omake-doc, Node: Subsection 10-11-23,	Next: Subsection 10-11-24,	Prev: Subsection 10-11-22,	Up: Section 10-11
  

10.11.23   xterm-escape-begin, xterm-escape-end
===============================================

<<   $(xterm-escape-begin) : String
     $(xterm-escape-end) : String
>>
  
  The xterm-escape-begin and xterm-escape-end functions return the
escape sequences that can be used to set the XTerm window title. Will
return empty values if this capability is not available.
  Note: if you intend to use these strings inside the shell 'prompt',
you need to use $(prompt_invisible_begin)$(xterm-escape-begin) and
$(xterm-escape-end)$(prompt_invisible_end). 

File: omake-doc, Node: Subsection 10-11-24,	Next: Subsection 10-11-25,	Prev: Subsection 10-11-23,	Up: Section 10-11
  

10.11.24   xterm-escape
=======================

<<   $(xterm-escape s) : Sequence
>>
  
  When the TERM environment variable indicates that the XTerm title
setting capability is available, $(xterm-escape s) is equivalent to
$(xterm-escape-begin)s$(xterm-escape-end). Otherwise, it returns an
empty value.
  Note: if you intend to use the value returned by xterm-escape inside
the shell 'prompt', you need to wrap it using the 'prompt-invisible'
function. 

File: omake-doc, 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). 

File: omake-doc, 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. 

File: omake-doc, 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.

File: omake-doc, 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. 
  

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

10.11.29   gmtime, localtime
============================
\@nam
e{function: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. 

File: omake-doc, Node: Subsection 10-11-30,	Prev: Subsection 10-11-29,	Up: Section 10-11
  

10.11.30   mktime, normalize-time
=================================
\@nam
e{function: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). 

File: omake-doc, Node: Chapter 11,	Next: Chapter 12,	Prev: Chapter 10,	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


File: omake-doc, Node: Section 11-1,	Next: Section 11-2,	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
>>
  

File: omake-doc, 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::.

File: omake-doc, 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 &
>>
  

File: omake-doc, 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
>>
  

File: omake-doc, 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
>>
  

File: omake-doc, 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"
>>
  

File: omake-doc, 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"
>>
  

File: omake-doc, 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.

File: omake-doc, Node: Section 11-9,	Next: Section 11-10,	Prev: Section 11-8,	Up: Chapter 11
  

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

   
* Menu:

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


File: omake-doc, Node: Subsection 11-9-1,	Next: Subsection 11-9-2,	Up: Section 11-9
  

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

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

File: omake-doc, Node: Subsection 11-9-2,	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
>>
  

File: omake-doc, Node: Section 11-10,	Next: Section 11-11,	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


File: omake-doc, Node: Subsection 11-10-1,	Next: Subsection 11-10-2,	Up: Section 11-10
  

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

  The jobs function prints a list of jobs.
  jobs 

File: omake-doc, 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...> 

File: omake-doc, 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...> 

File: omake-doc, 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...> 

File: omake-doc, 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...> 

File: omake-doc, Node: Subsection 11-10-6,	Prev: Subsection 11-10-5,	Up: Section 11-10
  

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

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

File: omake-doc, Node: Section 11-11,	Prev: Section 11-10,	Up: Chapter 11
  

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

   
* Menu:

* Subsection 11-11-1::	history


File: omake-doc, Node: Subsection 11-11-1,	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.   

File: omake-doc, Node: Chapter 12,	Next: Chapter 13,	Prev: Chapter 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


File: omake-doc, Node: Section 12-1,	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


File: omake-doc, Node: Subsection 12-1-1,	Next: Subsection 12-1-2,	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)
        >>
  

File: omake-doc, 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.

File: omake-doc, 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. 

File: omake-doc, 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. 

File: omake-doc, 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. 

File: omake-doc, 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
       >>
 
   

File: omake-doc, 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. 
  

File: omake-doc, 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. 

File: omake-doc, 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. 
   

File: omake-doc, 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. 

File: omake-doc, 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. 

File: omake-doc, 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. 
   

File: omake-doc, 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. 

File: omake-doc, 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. 

File: omake-doc, 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. 
   

File: omake-doc, 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 
   

File: omake-doc, 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. 
   

File: omake-doc, 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. 

File: omake-doc, 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. 

File: omake-doc, 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. 
   

File: omake-doc, 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. 
   

File: omake-doc, Node: Subsection 12-1-22,	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.
  
   

File: omake-doc, Node: Chapter 13,	Next: Chapter 14,	Prev: Chapter 12,	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


File: omake-doc, Node: Section 13-1,	Next: Section 13-2,	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. 

File: omake-doc, Node: Section 13-2,	Next: Section 13-3,	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


File: omake-doc, Node: Subsection 13-2-1,	Next: Subsection 13-2-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
>>

File: omake-doc, 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.

File: omake-doc, 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. 

File: omake-doc, Node: Subsection 13-2-4,	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. 

File: omake-doc, Node: Section 13-3,	Next: Section 13-4,	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


File: omake-doc, Node: Subsection 13-3-1,	Next: Subsection 13-3-2,	Up: Section 13-3
  

13.3.1   dependencies, dependencies-all, dependencies-proper
============================================================
\@name
{hevea_fun255}
<<   $(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. 

File: omake-doc, 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. 

File: omake-doc, 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))"
>>

File: omake-doc, 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. 

File: omake-doc, 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])
>>

File: omake-doc, Node: Subsection 13-3-6,	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.  

File: omake-doc, Node: Section 13-4,	Next: Section 13-5,	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


File: omake-doc, Node: Subsection 13-4-1,	Next: Subsection 13-4-2,	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. 
   

File: omake-doc, Node: Subsection 13-4-2,	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). 

File: omake-doc, Node: Section 13-5,	Next: Section 13-6,	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


File: omake-doc, Node: Subsection 13-5-1,	Next: Subsection 13-5-2,	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.
