OMAKE-BASE(1)                    Build Tools                     OMAKE-BASE(1)



NAME
       omake  is  a flexible build system designed for building a wide variety
       of projects.  This document describes the basic built-in functions. For
       an overview of omake, see the omake(1) man page.


BUILTIN VARIABLES
   OSTYPE
       Set  to  the  machine architecture omake is running on. Possible values
       are Unix (for all Unix versions, including Linux and Mac OS  X),  Win32
       (for  MS-Windows, OMake compiled with MSVC++ or Mingw), and Cygwin (for
       MS-Windows, OMake compiled with Cygwin).

   SYSNAME
       The name of the operating system for the current machine.

   NODENAME
       The hostname of the current machine.

   OS_VERSION
       The operating system release.

   MACHINE
       The machine architecture, e.g.  i386, sparc, etc.

   HOST
       Same as NODENAME.

   OMAKE_VERSION
       Version of OMake.

   USER
       The login name of the user executing the process.

   HOME
       The home directory of the user executing the process.

   PID
       The OMake process id.

BOOLEAN FUNCTIONS AND CONTROL FLOW
   NOT
          $(not e) : String
             e : String


       Boolean values in omake are represented  by  case-insensitive  strings.
       The false value can be represented by the strings false, no, nil, unde-
       fined or 0, and everything else is true. The  not  function  negates  a
       Boolean value.

       For  example,  $(not false) expands to the string true, and $(not hello
       world) expands to false.

   EQUAL
          $(equal e1, e2) : String
             e1 : String
             e2 : String


       The equal function tests for equality of two values.

       For example $(equal a, b) expands to false, and  $(equal  hello  world,
       hello world) expands to true.

   AND
           $(and e1, ..., en) : String
              e1, ..., en: Sequence


       The and function evaluates to the conjunction of its arguments.

       For example, in the following code, X is true, and Y is false.

           A = a
           B = b
           X = $(and $(equal $(A), a) true $(equal $(B), b))
           Y = $(and $(equal $(A), a) true $(equal $(A), $(B)))


   OR
          $(or e1, ..., en) : String
             e1, ..., en: String Sequence


       The or function evaluates to the disjunction of its arguments.

       For example, in the following code, X is true, and Y is false.

           A = a
           B = b
           X = $(or $(equal $(A), a) false $(equal $(A), $(B)))
           Y = $(or $(equal $(A), $(B)) $(equal $(A), b))


   IF
           $(if e1, e2[, e3]) : value
              e1 : String
              e2, e3 : value


       The if function represents a conditional based on a Boolean value.  For
       example $(if $(equal a, b), c, d) evaluates to d.

       Conditionals may also be declared with an alternate syntax.

          if e1
             body1
          elseif e2
             body2
          ...
          else
             bodyn


       If the expression e1 is not false, then the expressions  in  body1  are
       evaluated  and  the result is returned as the value of the conditional.
       Otherwise, if e1 evaluates to false, the evaluation continues with  the
       e2 expression. If none of the conditional expressions is true, then the
       expressions in bodyn are evaluated and the result is  returned  as  the
       value of the conditional.

       There can be any number of elseif clauses; the else clause is optional.

       Note that each branch of the conditional  defines  its  own  scope,  so
       variables  defined in the branches are normally not visible outside the
       conditional.  The export command may be used to  export  the  variables
       defined  in a scope. For example, the following expression represents a
       common idiom for defining the C compiler configuration.

          if $(equal $(OSTYPE), Win32)
             CC = cl
             CFLAGS += /DWIN32
             export
          else
             CC = gcc
             CFLAGS += -g -O2
             export


   SWITCH, MATCH
       The switch and match functions perform pattern matching.

       $(switch <arg>, <pattern_1>, <value_1>,  ...,  <pattern_n>,  <value_n>)
       $(match <arg>, <pattern_1>, <value_1>, ..., <pattern_n>, <value_n>)

       The  number  of  <pattern>/<value>  pairs  is  arbitrary. They strictly
       alternate; the total number of arguments to <match> must be odd.

       The <arg> is evaluated to a string, and compared with <pattern_1>.   If
       it matches, the result of the expression is <value_1>. Otherwise evalu-
       ation continues with the remaining patterns until a match is found.  If
       no pattern matches, the value is the empty string.

       The switch function uses string comparison to compare the argument with
       the patterns. For example, the following expression  defines  the  FILE
       variable  to  be either foo, bar, or the empty string, depending on the
       value of the OSTYPE variable.

           FILE = $(switch $(OSTYPE), Win32, foo, Unix, bar)


       The match function uses regular expression patterns (see the grep func-
       tion).  If a match is found, the variables $1, $2, ... are bound to the
       substrings matched between \( and \) delimiters.  The $0 variable  con-
       tains  the  entire match, and $* is an array of the matched substrings.
       to the matched substrings.

           FILE = $(match foo_xyz/bar.a, foo_\\\(.*\\\)/\\\(.*\\\)\.a, foo_$2/$1.o)


       The switch and match functions also have  an  alternate  (more  usable)
       form.

          match e
          case pattern1
             body1
          case pattern2
             body2
          ...
          default
             bodyd


       If the value of expression e matches pattern_i and no previous pattern,
       then body_i is evaluated and returned as the result of the match.   The
       switch function uses string comparison; the match function uses regular
       expression matching.

          match $(FILE)
          case $".*\(\.[^\/.]*\)"
             println(The string $(FILE) has suffix $1)
          default
             println(The string $(FILE) has no suffix)


   TRY
          try
             try-body
          catch class1(v1)
             catch-body
          when expr
             when-body
          ...
          finally
             finally-body


       The try form is used for exception handling.  First, the expressions in
       the try-body are evaluated.

       If  evaluation  results in a value v without raising an exception, then
       the expressions in the finally-body are evaluated and the  value  v  is
       returned as the result.

       If  evaluation  of  the try-body results in a exception object obj, the
       catch clauses are examined in order. When examining catch clause  catch
       class(v),  if the exception object obj is an instance of the class name
       class, the variable v is bound to the exception object, and the expres-
       sions in the catch-body are evaluated.

       If  a when clause is encountered while a catch body is being evaluated,
       the predicate expr is evaluated. If the result is true, evaluation con-
       tinues with the expressions in the when-body. Otherwise, the next catch
       clause is considered for evaluation.

       If evaluation of a  catch-body  or  when-body  completes  successfully,
       returning a value v, without encountering another when clause, then the
       expressions in the finally-body  are  evaluated  and  the  value  v  is
       returned as the result.

       There  can  be  any  number  of  catch  clauses;  the finally clause is
       optional.

   RAISE
          raise exn
             exn : Exception


       The raise function raises an exception.  The  exn  object  can  be  any
       object. However, the normal convention is to raise an Exception object.

   EXIT
          exit(code)
             code : Int


       The exit function terminates omake abnormally.

       $(exit <code>)

       The exit function takes one  integer  argument,  which  is  exit  code.
       Non-zero values indicate abnormal termination.

   DEFINED
          $(defined sequence) : String
             sequence : Sequence


       The defined function test whether all the variables in the sequence are
       currently defined. For example, the following code defines the X  vari-
       able if it is not already defined.

           if $(not $(defined X))
              X = a b c
              export


   DEFINED-ENV
          $(defined-env sequence) : String
             sequence : String


       The defined-env function tests whether a variable is defined as part of
       the process environment.

       For example, the following code adds the -g compile option if the envi-
       ronment variable DEBUG is defined.

       if $(defined-env DEBUG)
           CFLAGS += -g
           export


   GETENV
          $(getenv name) : String
          $(getenv name, default) : String


       The getenv function gets the value of a variable from the process envi-
       ronment. The function takes one or two arguments.

       In the single argument form, an exception is  raised  if  the  variable
       variable  is  not defined in the environment. In the two-argument form,
       the second argument is returned as the  result  if  the  value  is  not
       defined.

       For  example,  the  following  code  defines  the  variable  X  to be a
       space-separated list of elements of the PATH environment variable if it
       is defined, and to /bin /usr/bin otherwise.

           X = $(split $(PATHSEP), $(getenv PATH, /bin:/usr/bin))


       You may also use the alternate form.
            getenv(NAME)
                default


   SETENV
          setenv(name, value)
             name : String
             value : String


       The  setenv  function sets the value of a variable in the process envi-
       ronment. Environment variables are scoped like normal variables.


   GET-REGISTRY
          get-registry(hkey, key, field) : String
          get-registry(hkey, key, field, default) : String
              hkey : String
              key : String
              field : String


       The get-registry function retrieves a string value from the system reg-
       istry on Win32. On other architectures, there is no registry.

       The  hive (I think that is the right word), indicates which part of the
       registry to use. It should be one of the following values.


       *      HKEY_CLASSES_ROOT

       *      HKEY_CURRENT_CONFIG

       *      HKEY_CURRENT_USER

       *      HKEY_LOCAL_MACHINE

       *      HKEY_USERS

       Refer to the Microsoft documentation if you want  to  know  what  these
       mean.

       The key is the field you want to get from the registry.  It should have
       a form like A\B\C (if you use forward slashes, they will  be  converted
       to backslashes). The field is the sub-field of the key.

       In  the  4-argument  form, the default is returned on failure.  You may
       also use the alternate form.

           get-registry(hkey, key, field)
              default



   GETVAR
          $(getvar name) : String


       The getvar function gets the value of a variable.

       An exception is raised if the variable variable is not defined.

       For example, the following code defines X to be the string abc.

           NAME = foo
           foo_1 = abc
           X = $(getvar $(NAME)_1)


   SETVAR
          setvar(name, value)
             name : String
             value : String


       The setvar function defines a new variable. For example, the  following
       code defines the variable X to be the string abc.

          NAME = X
          setvar($(NAME), abc)


ARRAYS AND SEQUENCES
   ARRAY
           $(array elements) : Array
              elements : Sequence


       The array function creates an array from a sequence.  If the <arg> is a
       string, the elements of the array are the whitespace-separated elements
       of the string, respecting quotes.

       In addition, array variables can be declared as follows.

           A[] =
              <val1>
              ...
              <valn>


       In  this  case,  the  elements  of  the  array are exactly <val1>, ...,
       <valn>, and whitespace is preserved literally.

   SPLIT
          $(split sep, elements) : Array
             sep : String
             elements : Sequence


       The split function takes two arguments, a string of separators,  and  a
       string  argument.  The  result  is  an  array of elements determined by
       splitting the elements by all occurrence of the separator in  the  ele-
       ments sequence.

       For example, in the following code, the X variable is defined to be the
       array /bin /usr/bin /usr/local/bin.

           PATH = /bin:/usr/bin:/usr/local/bin
           X = $(split :, $(PATH))


       The sep argument may be omitted. In this case split  breaks  its  argu-
       ments along the white space. Quotations are not split.

   CONCAT
          $(concat sep, elements) : String
             sep : String
             elements : Sequence


       The  concat  function  takes  two  arguments, a separator string, and a
       sequence of elements. The result is a string  formed  by  concatenating
       the elements, placing the separator between adjacent elements.

       For example, in the following code, the X variable is defined to be the
       string foo_x_bar_x_baz.

           X = foo  bar     baz
           Y = $(concat _x_, $(X))


   LENGTH
          $(length sequence) : Int
             sequence : Sequence


       The length function returns the number of elements in its argument.

       For example, the expression $(length a b "c d") evaluates to 3.

   NTH
          $(nth i, sequence) : value
             i : Int
             sequence : Sequence
          raises RuntimeException


       The nth function returns the nth element of its argument, treated as  a
       list.  Counting starts at 0. An exception is raised if the index is not
       in bounds.

       For example, the expression $(nth 1, a "b c" d) evaluates to "b c".

   NTH-HD
          $(nth-hd i, sequence) : value
             i : Int
             sequence : Sequence
          raises RuntimeException


       The nth-hd function returns the first i elements of  the  sequence.  An
       exception is raised if the sequence is not at least i elements long.

       For  example,  the  expression $(nth-hd 2, a "b c" d) evaluates to a "b
       c".


   NTH-TL
          $(nth-tl i, sequence) : value
             i : Int
             sequence : Sequence
          raises RuntimeException


       The nth-tl function skips i elements of the sequence  and  returns  the
       rest. An exception is raised if the sequence is not at least i elements
       long.

       For example, the expression $(nth-tl 1, a "b c" d) evaluates to  "b  c"
       d.


   SUB
          $(sub off, len, sequent) : value
             off : Int
             len : Int
             sequence : Sequence
          raises RuntimeException


       The  sub  function returns a subrange of the sequence.  Counting starts
       at 0. An exception is raised if the specified range is not in bounds.

       For example, the expression $(sub 1, 2, a "b c" d e) evaluates to "b c"
       d.

   REV
           $(rev sequence) : Sequence
              sequence : Sequence


       The  rev  function returns the elements of a sequence in reverse order.
       For example, the expression $(rev a "b c" d) evaluates to d "b c" a.

   STRING
          $(string sequence) : String
             sequence : Sequence


       The string function flattens a sequence into a single string.  This  is
       similar  to  the  concat  function,  but  the elements are separated by
       whitespace. The result is treated as a unit; whitespace is significant.

   QUOTE
          $(quote sequence) : String
             sequence : Sequence


       The  quote  function  flattens a sequence into a single string and adds
       quotes around the string. Inner quotation symbols are escaped.

       For example, the expression $(quote a "b c" d) evaluates to "a \"b  c\"
       d", and $(quote abc) evaluates to "abc".

   QUOTE-ARGV
          $(quote-argv sequence) : String
             sequence : Sequence


       The  quote-argv  function flattens a sequence into a single string, and
       adds quotes around the string. The quotation is formed so that  a  com-
       mand-line parse can separate the string back into its components.

   HTML-STRING
          $(html-string sequence) : String
             sequence : Sequence


       The  html-string function flattens a sequence into a single string, and
       escaped special HTML characters.  This is similar to the  concat  func-
       tion,  but  the  elements  are  separated  by whitespace. The result is
       treated as a unit; whitespace is significant.

   ADDSUFFIX
          $(addsuffix suffix, sequence) : Array
             suffix : String
             sequence : Sequence


       The addsuffix function adds a suffix to  each  component  of  sequence.
       The  number  of elements in the array is exactly the same as the number
       of elements in the sequence.

       For example, $(addsuffix .c, a b "c d") evaluates to a.c b.c "c d".c.

   MAPSUFFIX
          $(mapsuffix suffix, sequence) : Array
             suffix : value
             sequence : Sequence


       The mapsuffix function adds a suffix to each component of sequence.  It
       is similar to addsuffix, but uses array concatenation instead of string
       concatenation. The number of elements in the array is twice the  number
       of elements in the sequence.

       For  example,  $(mapsuffix  .c, a b "c d") evaluates to a .c b .c "c d"
       .c.

   ADDSUFFIXES
          $(addsuffixes suffixes, sequence) : Array
             suffixes : Sequence
             sequence : Sequence


       The addsuffixes function adds all suffixes in  its  first  argument  to
       each  component of a sequence. If suffixes has n elements, and sequence
       has m elements, the the result has n * m elements.

       For example, the $(addsuffixes .c .o, a b c) expressions  evaluates  to
       a.c a.o b.c b.o c.o c.a.

   REMOVEPREFIX
          $(removeprefix prefix, sequence) : Array
             prefix : String
             sequence : Array


       The  removeprefix  function  removes  a prefix from each component of a
       sequence.

   REMOVESUFFIX
          $(removesuffix sequence) : Array
             sequence : String


       The removesuffix function removes the suffixes from each component of a
       sequence.

       For example, $(removesuffix a.c b.foo "c d") expands to a b "c d".

   REPLACESUFFIXES
          $(replacesuffixes old-suffixes, new-suffixes, sequence) : Array
             old-suffixes : Sequence
             new-suffixes : Sequence
             sequence : Sequence


       The  replacesuffixes  function modifies the suffix of each component in
       sequence. The old-suffixes and new-suffixes sequences should  have  the
       same length.

       For  example,  $(replacesuffixes, .h .c, .o .o, a.c b.h c.z) expands to
       a.o b.o c.z.

   ADDPREFIX
          $(addprefix prefix, sequence) : Array
             prefix : String
             sequence : Sequence


       The addprefix function adds a prefix to each component of  a  sequence.
       The  number  of  element in the result array is exactly the same as the
       number of elements in the argument sequence.

       For example, $(addprefix foo/, a b "c  d")  evaluates  to  foo/a  foo/b
       foo/"c d".

   MAPPREFIX
          $(mapprefix prefix, sequence) : Array
             prefix : String
             sequence : Sequence


       The  mapprefix  function adds a prefix to each component of a sequence.
       It is similar to addprefix, but array concatenation is used instead  of
       string  concatenation. The result array contains twice as many elements
       as the argument sequence.

       For example, $(mapprefix foo, a b "c d") expands to foo a foo b foo  "c
       d".

   ADD-WRAPPER
          $(add-wrapper prefix, suffix, sequence) : Array
             prefix : String
             suffix : String
             sequence : Sequence


       The  add-wrapper functions adds both a prefix and a suffix to each com-
       ponent of a sequence.  For example, the expression $(add-wrapper  dir/,
       .c,  a  b)  evaluates to dir/a.c dir/b.c. String concatenation is used.
       The array result has the  same  number  of  elements  as  the  argument
       sequence.

   SET
          $(set sequence) : Array
             sequence : Sequence


       The  set  function sorts a set of string components, eliminating dupli-
       cates.

       For example, $(set z y z "m n" w a) expands to "m n" a w y z.

   MEM
          $(mem elem, sequence) : Boolean
             elem : String
             sequence : Sequence


       The mem function tests for membership in a sequence.

       For example, $(mem "m n", y z "m n" w a) evaluates to true, while $(mem
       m n, y z "m n" w a) evaluates to false.

   INTERSECTION
          $(intersection sequence1, sequence2) : Array
             sequence1 : Sequence
             sequence2 : Sequence


       The  intersection  function takes two arguments, treats them as sets of
       strings, and computes their intersection. The order of  the  result  is
       undefined,  and it may contain duplicates. Use the set function to sort
       the result and eliminate duplicates in the result if desired.

       For example, the expression $(intersection c a b a, b a) evaluates to a
       b a.

   INTERSECTS
          $(intersects sequence1, sequence2) : Boolean
             sequence1 : Sequence
             sequence2 : Sequence


       The  intersects function tests whether two sets have a non-empty inter-
       section.  This is slightly more efficient than computing the  intersec-
       tion and testing whether it is empty.

       For  example,  the  expression  $(intersects a b c, d c e) evaluates to
       true, and $(intersects a b c a, d e f) evaluates to false.

   SET-DIFF
          $(set-diff sequence1, sequence2) : Array
             sequence1 : Sequence
             sequence2 : Sequence


       The set-diff function takes two  arguments,  treats  them  as  sets  of
       strings,  and  computes their difference (all the elements of the first
       set that are not present in the second one). The order of the result is
       undefined  and  it may contain duplicates. Use the set function to sort
       the result and eliminate duplicates in the result if desired.

       For example, the expression $(set-diff c a b a e, b a) evaluates  to  c
       e.

   FILTER
          $(filter patterns, sequence) : Array
             patterns : Sequence
             sequence : Sequence


       The  filter function picks elements from a sequence.  The patterns is a
       non-empty sequence of patterns, each may contain one occurrence of  the
       wildcard % character.

       For  example  $(filter %.h %.o, a.c x.o b.h y.o "hello world".c) evalu-
       ates to x.o b.h y.o.

   FILTER-OUT
          $(filter-out patterns, sequence) : Array
             patterns : Sequence
             sequence : Sequence


       The filter-out function removes elements from a sequence.  The patterns
       is a non-empty sequence of patterns, each may contain one occurrence of
       the wildcard % character.

       For example $(filter-out %.c %.h, a.c  x.o  b.h  y.o  "hello  world".c)
       evaluates to x.o y.o.

   CAPITALIZE
          $(capitalize sequence) : Array
             sequence : Sequence


       The capitalize function capitalizes each word in a sequence.  For exam-
       ple, $(capitalize through the looking Glass) evaluates to  Through  The
       Looking Glass.

   UNCAPITALIZE
          $(uncapitalize sequence) : Array
             sequence : Sequence


       The uncapitalize function uncapitalizes each word in its argument.

       For  example,  $(uncapitalize  through  the looking Glass) evaluates to
       through the looking glass.

   UPPERCASE
          $(uppercase sequence) : Array
             sequence : Sequence


       The uppercase function converts each word in a sequence  to  uppercase.
       For  example,  $(uppercase  through  the  looking  Glass)  evaluates to
       THROUGH THE LOOKING GLASS.

   LOWERCASE
          $(lowercase sequence) : Array
             sequence : Sequence


       The lowercase function reduces each word in its argument to  lowercase.

       For  example,  $(lowercase  through  tHe  looking  Glass)  evaluates to
       through the looking glass.

   SYSTEM
          system(s)
             s : Sequence


       The system function is used to evaluate a shell expression.  This func-
       tion is used internally by omake to evaluate shell commands.

       For example, the following program is equivalent to the expression sys-
       tem(ls foo).

          ls foo


   SHELL
          $(shell command) : Array
          $(shella command) : Array
          $(shell-code command) : Int
             command : Sequence


       The shell function evaluates a command using  the  command  shell,  and
       returns  the  whitespace-separated  words of the standard output as the
       result.

       The shella function acts similarly, but it returns the lines  as  sepa-
       rate items in the array.

       The  shell-code  function  returns  the  exit  code.  The output is not
       diverted.

       For example, if the current directory  contains  the  files  OMakeroot,
       OMakefile, and hello.c, then $(shell ls) evaluates to hello.c OMakefile
       OMakeroot (on a Unix system).

ARITHMETIC
   INT
       The int function can be used to create integers.   It  returns  an  Int
       object.

       $(int 17).


   FLOAT
       The  float  function  can be used to create floating-point numbers.  It
       returns a Float object.

       $(float 3.1415926).

   BASIC ARITHMETIC
       The following functions can be used to perform basic arithmetic.


       *      $(neg <numbers>): arithmetic inverse

       *      $(add <numbers>): addition.

       *      $(sub <numbers>): subtraction.

       *      $(mul <numbers>): multiplication.

       *      $(div <numbers>): division.

       *      $(mod <numbers>): remainder.

       *      $(lnot <numbers>): bitwise inverse.

       *      $(land <numbers>): bitwise and.

       *      $(lor <numbers>): bitwise or.

       *      $(lxor <numbers>): bitwise exclusive-or.

       *      $(lsl <numbers>): logical shift left.

       *      $(lsr <numbers>): logical shift right.

       *      $(asr <numbers>): arithmetic shift right.


   COMPARISONS
       The following functions can be used to perform numerical comparisons.


       *      $(lt <numbers>): less then.

       *      $(le <numbers>): no more than.

       *      $(eq <numbers>): equal.

       *      $(ge <numbers>): no less than.

       *      $(gt <numbers>): greater than.

       *      $(ult <numbers>): unsigned less than.

       *      $(ule <numbers>): unsigned greater than.

       *      $(uge <numbers>): unsigned greater than or equal.

       *      $(ugt <numbers>): unsigned greater than.


FIRST-CLASS FUNCTIONS
   FUN
       The fun form introduces anonymous functions.

       $(fun <v1>, ..., <vn>, <body>)

       The last argument is the body of the function.  The other arguments are
       the parameter names.

       The three following definitions are equivalent.

           F(X, Y) =
              return($(addsuffix $(Y), $(X)))

           F = $(fun X, Y, $(addsuffix $(Y), $(X)))

           F =
              fun(X, Y)
                 value $(addsuffix $(Y), $(X))


   APPLY
       The apply operator is used to apply a function.

       $(apply <fun>, <args>)

       Suppose we have the following function definition.

           F(X, Y) =
              return($(addsuffix $(Y), $(X)))


       The the two expressions below are equivalent.

           X = F(a b c, .c)
           X = $(apply $(F), a b c, .c)


   APPLYA
       The  applya  operator  is used to apply a function to an array of argu-
       ments.

       $(applya <fun>, <args>)

       For example, in the following program, the value of Z is file.c.

           F(X, Y) =
              return($(addsuffix $(Y), $(X)))
           args[] =
              file
              .c
           Z = $(applya $(F), $(args))


ITERATION AND MAPPING
   FOREACH
       The foreach function maps a function over a sequence.

           $(foreach <fun>, <args>)

           foreach(<var>, <args>)
              <body>


       For example, the following program defines the variable X as  an  array
       a.c b.c c.c.

           X =
              foreach(x, a b c)
                 value $(x).c

           # Equivalent expression
           X = $(foreach $(fun x, $(x).c), abc)


       There is also an abbreviated syntax.

       The  export form can also be used in a foreach body. The final value of
       X is a.c b.c c.c.

           X =
           foreach(x, a b c)
              X += $(x).c
              export


FILE OPERATIONS
   FILE, DIR
          $(file sequence) : File Sequence
             sequence : Sequence
          $(dir sequence) : Dir Sequence
             sequence : Sequence


       The file and dir functions define  location-independent  references  to
       files  and  directories.   In omake, the commands to build a target are
       executed in the target's directory. Since there may be many directories
       in  an  omake  project,  the build system provides a way to construct a
       reference to a file in one directory, and use  it  in  another  without
       explicitly  modifying  the  file name. The functions have the following
       syntax, where the name should refer to a file or directory.

       For example, we can construct a reference to a file foo in the  current
       directory.

          FOO = $(file foo)
          .SUBDIRS: bar


       If the FOO variable is expanded in the bar subdirectory, it will expand
       to ../foo.

       These commands are often used in the  top-level  OMakefile  to  provide
       location-independent references to top-level directories, so that build
       commands may refer to these directories as if they were absolute.

          ROOT = $(dir .)
          LIB  = $(dir lib)
          BIN  = $(dir bin)


       Once these variables are defined, they can be used in build commands in
       subdirectories  as follows, where $(BIN) will expand to the location of
       the bin directory relative to the command being executed.

          install: hello
            cp hello $(BIN)


   TMPFILE
           $(tmpfile prefix) : File
           $(tmpfile prefix, suffix) : File
               prefix : String
               suffix : String


       The tmpfile function returns the name of a fresh temporary file in  the
       temporary directory.

   IN
          $(in dir, exp) : String Array
             dir : Dir
             exp : expression


       The  in  function  is closely related to the dir and file functions. It
       takes a directory and an expression, and evaluates  the  expression  in
       that  effective  directory.   For  example, one common way to install a
       file is to define a symbol link, where the value of the link  is  rela-
       tive to the directory where the link is created.

       The following commands create links in the $(LIB) directory.

           FOO = $(file foo)
           install:
              ln -s $(in $(LIB), $(FOO)) $(LIB)/foo


       Note  that the in function only affects the expansion of Node (File and
       Dir) values.

   WHICH
          $(which files) : File Sequence
             files : String Sequence


       The which function searches for  executables  in  the  current  command
       search path, and returns file values for each of the commands. It is an
       error if a command is not found.

   WHERE
       The where function is similar to which, except it returns the  list  of
       all  the  locations  of the given executable (in the order in which the
       corresponding directories appear in $PATH). In case a command  is  han-
       dled  internally  by  the  Shell object, the first string in the output
       will describe the command as a built-in function.

           % where echo
           echo is a Shell object method (a built-in function)
           /bin/echo


   EXISTS-IN-PATH
          $(exists-in-path files) : String
             files : String Sequence


       The exists-in-path function tests whether all executables  are  present
       in the current search path.

   BASENAME
          $(basename files) : String Sequence
             files : String Sequence


       The  basename function returns the base names for a list of files.  The
       basename is the filename with any leading directory components removed.

       For   example,  the  expression  $(basename  dir1/dir2/a.out  /etc/mod-
       ules.conf /foo.ml) evaluates to a.out modules.conf foo.ml.

   ROOTNAME
          $(rootname files) : String Sequence
             files : String Sequence


       The rootname function returns the root name for a list of  files.   The
       rootname is the filename with the final suffix removed.

       For  example,  the  expression  $(rootname  dir1/dir2/a.out  /etc/a.b.c
       /foo.ml) evaluates to dir1/dir2/a /etc/a.b /foo.

   DIROF
          $(dirof files) : Dir Sequence
             files : File Sequence


       The dirof function returns the directory for each of the listed  files.

       For  example,  the  expression $(dirof dir/dir2/a.out /etc/modules.conf
       /foo.ml) evaluates to the directories dir1/dir2 /etc /.

   FULLNAME
          $(fullname files) : String Sequence
             files : File Sequence


       The fullname function returns the pathname relative to the project root
       for each of the files or directories.

   ABSNAME
          $(absname files) : String Sequence
             files : File Sequence


       The  absname  function  returns  the  absolute pathname for each of the
       files or directories.

   HOMENAME
          $(homename files) : String Sequence
             files : File Sequence


       The homename function returns the name of a file in tilde form, if pos-
       sible.  The unexpanded forms are computed lazily: the homename function
       will  usually  evaluate  to  an  absolute  pathname  until  the   first
       tilde-expansion for the same directory.

   SUFFIX
          $(suffix files) : String Sequence
             files : StringSequence


       The  suffix  function  returns  the suffixes for a list of files.  If a
       file has no suffix, the function returns the empty string.

       For example, the expression $(suffix  dir1/dir2/a.out  /etc/a  /foo.ml)
       evaluates to .out .ml.

   FILE-EXISTS, TARGET-EXISTS, TARGET-IS-PROPER
          $(file-exists files) : String
          $(target-exists files) : String
          $(target-is-proper files) : String
              files : File Sequence


       The  file-exists  function  checks whether the files listed exist.  The
       target-exists function is similar to the  file-exists  function.   How-
       ever,  it  returns true if the file exists or if it can be built by the
       current project. The target-is-proper returns true only if the file can
       be generated in the current project.

   FILTER-EXISTS, FILTER-TARGETS, FILTER-PROPER-TARGETS
          $(filter-exists files) : File Sequence
          $(filter-targets files) : File Sequence
          $(filter-proper-targets) : File Sequence
             files : File Sequence


       The  filter-exists, filter-targets, and filter-proper-targets functions
       remove files from a list of files.

       *      filter-exists: the result is the list of files that exist.

       *      filter-targets: the result is the list of files either exist, or
              can be built by the current project.

       *      filter-proper-targets:  the result is the list of files that can
              be built in the current project.

       One way to create a simple ``clean'' rule that removes generated  files
       from the project is by removing all files that can be built in the cur-
       rent project. CAUTION: you should be careful before you  do  this.  The
       rule  removes any file that can potentially be reconstructed.  There is
       no check to make sure that the commands to rebuild the file would actu-
       ally  succeed. Also, note that no file outside the current project will
       be deleted.

           .PHONY: clean

           clean:
               rm $(filter-proper-targets $(ls R, .))


       See the dependencies-proper function to see  an  alternate  method  for
       removing intermediate files.

       If  you  use CVS, you may wish to use the cvs_realclean program that is
       distributed with omake.


   FILE-SORT
          $(file-sort order, files) : File Sequence
             order : String
             files : File Sequence


       The file-sort function sorts a list of filenames by  build  order  aug-
       mented by a set of sort rules. Sort rules are declared using the .ORDER
       target.  The .BUILDORDER defines the default order.

       $(file-sort <order>, <files>)

       For example, suppose we have the following set of rules.

          a: b c
          b: d
          c: d

          .DEFAULT: a b c d
             echo $(file-sort .BUILDORDER, a b c d)


       In the case, the sorter produces the result d b c a.  That is, a target
       is  sorted  after  its  dependencies.  The sorter is frequently used to
       sort files that are to be linked by their dependencies  (for  languages
       where this matters).

       There are three important restrictions to the sorter:

       *      The  sorter can be used only within a rule body.  The reason for
              this is that all dependencies must be known before the  sort  is
              performed.

       *      The sorter can only sort files that are buildable in the current
              project.

       *      The sorter will fail if the dependencies are cyclic.


   SORT RULE
       It is possible to further constrain the sorter through the use of  sort
       rules.  A sort rule is declared in two steps. The target must be listed
       as an .ORDER target; and then a set of sort rules must be given. A sort
       rule defines a pattern constraint.

          .ORDER: .MYORDER

          .MYORDER: %.foo: %.bar
          .MYORDER: %.bar: %.baz

          .DEFAULT: a.foo b.bar c.baz d.baz
             echo $(sort .MYORDER, a.foo b.bar c.baz d.baz)


       In  this example, the .MYORDER sort rule specifies that any file with a
       suffix .foo should be placed after any file with suffix .bar,  and  any
       file with suffix .bar should be placed after a file with suffix .baz.

       In this example, the result of the sort is d.baz c.baz b.bar a.foo.

   FILE-CHECK-SORT
          file-check-sort(files)
             files : File Sequence
          raises RuntimeException


       The  file-check-sort function checks whether a list of files is in sort
       order. If so, the list is returned unchanged.   If  not,  the  function
       raises an exception.

       $(file-check-sort <order>, <files>)

   GLOB
          $(glob strings) : Node Array
             strings : String Sequence
          $(glob options, strings) : Node Array
             options : String
             strings : String Sequence


       The glob function performs glob-expansion.

       The . and .. entries are always ignored.

       The options are:

       b      Do not perform csh(1)-style brace expansion.

       e      The \ character does not escape special characters.

       n      If an expansion fails, return the expansion literally instead of
              aborting.

       i      If an expansion fails, it expands to nothing.

       .      Allow wildcard patterns to match files beginning with a .

       A      Return all files, including files that begin with a .

       D      Match only directory files.

       C      Ignore files according to cvs(1) rules.

       P      Include only proper subdirectories.

       In addition, the following variables may be  defined  that  affect  the
       behavior of glob.


       GLOB_OPTIONS
              A string containing default options.

       GLOB_IGNORE
              A  list of shell patterns for filenames that glob should ignore.

       GLOB_ALLOW
              A list of shell patterns. If a file does not match a pattern  in
              GLOB_ALLOW, it is ignored.

       The returned files are sorted by name.

   LS
          $(ls files) : Node Array
             files : String Sequence
          $(ls options, files) : Node Array
             files : String Sequence


       The ls function returns the filenames in a directory.

       The  . and .. entries are always ignored.  The patterns are shell-style
       patterns, and are glob-expanded.

       The options include all of the options to the glob function,  plus  the
       following.


       R      Perform a recursive listing.

       The  GLOB_ALLOW and GLOB_IGNORE variables can be defined to control the
       globbing behavior.  The returned files are sorted by name.

   SUBDIRS
          $(subdirs dirs) : Dir Array
             dirs : String Sequence
          $(subdirs options, dirs) : Dir Array
             options : String
             dirs : String Sequence


       The subdirs function returns all the subdirectories of a list of direc-
       tories, recursively.

       The possible options are the following:

       A      Return directories that begin with a .

       C      Ignore files according to .cvsignore rules.

       P      Include only proper subdirectories.


   MKDIR
          mkdir(mode, node...)
             mode : Int
             node : Node
          raises RuntimeException

          mkdir(node...)
             node : Node
          raises RuntimeException


       The  mkdir  function creates a directory, or a set of directories.  The
       following options are supported.

       -m mode
              Specify the permissions of the created directory.

       -p     Create parent directories if they do not exist.

       --     Interpret the remaining names literally.


   STAT
       The Stat object represents the result returned by the  stat  and  lstat
       functions. It contains the following fields.

       A stat object has the following fields. Not all of the fields will have
       meaning on all architectures.


       dev    : the device number.

       ino    : the inode number.

       kind   : the kind of the file,  one  of  the  following:  REG  (regular
              file),  DIR  (directory),  CHR  (character  device),  BLK (block
              device), LNK (symbolic link), FIFO (named pipe), SOCK  (socket).

       perm   : access rights, represented as an integer.

       nlink  : number of links.

       uid    : user id of the owner.

       gid    : group id of the file's group.

       rdev   : device minor number.

       size   : size in bytes.

       atime  : last access time, as a floating point number.

       mtime  : last modification time, as a floating point number.

       ctime  : last status change time, as a floating point number.


   STAT
           $(stat node...) : Stat
              node : Node or Channel
           $(lstat node...) : Stat
              node : Node or Channel
           raises RuntimeException


       The  stat functions return file information.  If the file is a symbolic
       link, the stat function refers to the  destination  of  the  link;  the
       lstat function refers to the link itself.

   UNLINK
          $(unlink file...)
             file : File
          #(rm file...)
             file : File
          $(rmdir dir...)
             dir : Dir
          raises RuntimeException


       The  unlink and rm functions remove a file.  The rmdir function removes
       a directory.

       The following options are supported for rm and rmdir.

       -f     ignore nonexistent files, never prompt.

       -i     prompt before removal.

       -r     remove the contents of directories recursively.

       -v     explain what is going on.

       --     the rest of the values are interpreted literally.


   RENAME
           rename(old, new)
              old : Node
              new : Node
           mv(nodes... dir)
              nodes : Node Sequence
              dir   : Dir
           cp(nodes... dir)
              nodes : Node Sequence
              dir   : Dir
           raises RuntimeException


       The rename function changes the name of a file or directory  named  old
       to new.

       The  mv  function is similar, but if new is a directory, and it exists,
       then the files specified by the sequence are moved into the  directory.
       If  not,  the behavior of mv is identical to rename. The cp function is
       similar, but the original file is not removed.

       The mv and cp functions take the following options.

       -f     Do not prompt before overwriting.

       -i     Prompt before overwriting.

       -v     Explain what it happening.

       -r     Copy the contents of directories recursively.

       --     Interpret the remaining arguments literally.


   LINK
          link(src, dst)
             src : Node
             dst : Node
          raises RuntimeException


       The link function creates a hard link named dst to the file  or  direc-
       tory src.

       Hard links are not supported in Win32.

       Normally, only the superuser can create hard links to directories.

   SYMLINK
          symlink(src, dst)
             src : Node
             dst : Node
          raises RuntimeException


       The symlink function creates a symbolic link dst that points to the src
       file.

       The link name is computed relative to the target directory.  For  exam-
       ple,  the  expression  $(symlink  a/b, c/d) creates a link named c/d ->
       ../a/b.

       Symbolic links are not supported in Win32.

   READLINK
          $(readlink node...) : Node
             node : Node


       The readlink function reads the value of a symbolic link.

   CHMOD
          chmod(mode, dst...)
             mode : Int
             dst : Node or Channel
          chmod(mode dst...)
             mode : String
             dst : Node Sequence
          raises RuntimeException


       The chmod function changes the permissions of the targets.   The  chmod
       function does nothing on Win32 platforms.

       Options:

       -v     Explain what is happening.

       -r     Change files and directories recursively.

       -f     Continue on errors.

       --     Interpret the remaining argument literally.


   CHOWN
          chown(uid, gid, node...)
             uid : Int
             gid : Int
             node : Node or Channel
          chown(uid, node...)
             uid : Int
             node : Node or Channel
          raises RuntimeException


       The  chown  function changes the user and group id of the file.  If the
       gid is not specified, it is not changed. If either id is -1, that id is
       not changed.

   UMASK
           $(umask mode) : Int
              mode : Int
           raises RuntimeException


       Sets the file mode creation mask.  The previous mask is returned.  This
       value is not scoped, changes have global effect.

   DIGEST
            $(digest files) : String Array
               file : File Array
            raises RuntimeException

            $(digest-optional files) : String Array
               file : File Array


       The digest and digest-optional functions compute MD5 digests of  files.
       The  digest  function  raises an exception if a file does no exist. The
       digest-optional returns false if a file does no exist. MD5 digests  are
       cached.

   FIND-IN-PATH
           $(find-in-path path, files) : File Array
              path : Dir Array
              files : String Array
           raises RuntimeException

           $(find-in-path-optional path, files) : File Array


       The find-in-path function searches for the files in a search path. Only
       the tail of the filename  is  significant.  The  find-in-path  function
       raises    an   exception   if   the   file   can't   be   found.    The
       find-in-path-optional function silently removes  files  that  can't  be
       found.

   DIGEST-PATH
           $(digest-in-path path, files) : String/File Array
              path : Dir Array
              files : String Array
           raises RuntimeException

           $(digest-in-path-optional path, files) : String/File Array


       The digest-in-path function searches for the files in a search path and
       returns the file and digest for each file. Only the tail of  the  file-
       name is significant. The digest-in-path function raises an exception if
       the file can't be found. The digest-in-path-optional function  silently
       removes elements that can't be found.

   REHASH
           rehash()


       The rehash function resets all search paths.

   VMOUNT
           vmount(src, dst)
              src, dst : Dir
           vmount(flags, src, dst)
              flags : String
              src, dst : Dir


       ``Mount''  the  src  directory  on the dst directory. This is a virtual
       mount, changing the behavior of the $(file  ...)  function.   When  the
       $(file  str)  function is used, the resulting file is taken relative to
       the src directory if the file exists. Otherwise, the file  is  relative
       to the current directory.

       The  main  purpose of the vmount function is to support multiple builds
       with separate configurations or architectures.

       The options are as follows.

       l      Create symbolic links to files in the src directory.

       c      Copy files from the src directory.

       Mount operations are scoped.

   ADD-PROJECT-DIRECTORIES
           add-project-directories(dirs)
              dirs : Dir Array


       Add the directories to the set of directories that omake  considers  to
       be  part of the project. This is mainly used to avoid omake complaining
       that the current directory is not part of the project.

   REMOVE-PROJECT-DIRECTORIES
           remove-project-directories(dirs)
              dirs : Dir Array


       Removed the directories from the set of directories that omake  consid-
       ers to be part of the project. This is mainly used to cancel a .SUBDIRS
       from including a directory if it is determined that the directory  does
       not need to be compiled.

   TEST
          test(exp) : Bool
             exp : String Sequence


       The expression grammar is as follows:


       *      ! expression : expression is not true

       *      expression1 -a expression2 : both expressions are true

       *      expression1 -o expression2 : at least one expression is true

       *      ( expression ) : expression is true

       The base expressions are:


       *      -n string : The string has nonzero length

       *      -z string : The string has zero length

       *      string = string : The strings are equal

       *      string != string : The strings are not equal


       *      int1 -eq int2 : The integers are equal

       *      int1 -ne int2 : The integers are not equal

       *      int1 -gt int2 : int1 is larger than int2

       *      int1 -ge int2 : int2 is not larger than int1

       *      int1 -lt int2 : int1 is smaller than int2

       *      int1 -le int2 : int1 is not larger than int2


       *      file1  -ef file2 : On Unix, file1 and file2 have the same device
              and inode number.  On Win32, file1 and file2 have the same name.

       *      file1 -nt file2 : file1 is newer than file2

       *      file1 -ot file2 : file1 is older than file2


       *      -b file : The file is a block special file

       *      -c file : The file is a character special file

       *      -d file : The file is a directory

       *      -e file : The file exists

       *      -f file : The file is a normal file

       *      -g file : The set -group-id bit is set on the file

       *      -G file : The file's group is the current effective group

       *      -h file : The file is a symbolic link (also -L)

       *      -k file : The file's sticky bit is set

       *      -L file : The file is a symbolic link (also -h)

       *      -O file : The file's owner is the current effective user

       *      -p file : The file is a named pipe

       *      -r file : The file is readable

       *      -s file : The file is empty

       *      -S file : The file is a socket

       *      -u file : The set -user-id bit is set on the file

       *      -w file : The file is writable

       *      -x file : The file is executable

       A  string  is  any  sequence  of  characters;  leading - characters are
       allowed.

       An int is a string that can be interpreted as an integer. Unlike tradi-
       tional versions of the test program, the leading characters may specify
       an arity. The prefix 0b means the numbers is in binary; the  prefix  0o
       means  the  number  is  in  octal; the prefix 0x means the number is in
       hexadecimal.  An int can also be specified as -l string,  which  evalu-
       ates to the length of the string.

       A file is a string that represents the name of a file.

   FIND
          find(exp) : Node Array
             exp : String Sequence


       The find function searches a directory recursively, returning the files
       for which the expression evaluates to true.

       The expression argument uses the same syntax as the test function, with
       the following exceptions.


       1.     The expression may begin with a directory. If not specified, the
              current directory is searched.

       2.     The {} string expands to the current file being examined.

       The syntax of the expression is the same as test,  with  the  following
       additions.


       *      -name  string : The current file matches the regular expression.


REFERENCES
   SEE ALSO
       omake(1),   omake-quickstart(1),    omake-options(1),    omake-root(1),
       omake-language(1),   omake-shell(1),   omake-rules(1),   omake-base(1),
       omake-system(1), omake-pervasives(1), osh(1), make(1)


   VERSION
       Version: 0.9.6.9 of April 11, 2006.


   LICENSE AND COPYRIGHT
       (C)2003-2006, Mojave Group, Caltech

       This program is free software; you can redistribute it and/or modify it
       under  the  terms of the GNU General Public License as published by the
       Free Software Foundation; either version 2 of the License, or (at  your
       option) any later version.

       This  program  is  distributed  in the hope that it will be useful, but
       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER-
       CHANTABILITY  or  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
       Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       675 Mass Ave, Cambridge, MA 02139, USA.


   AUTHOR
       Jason Hickey et. al..br Caltech 256-80
       Pasadena, CA 91125, USA
       Email: omake-devel@metaprl.org
       WWW: http://www.cs.caltech.edu/~jyh




Build Tools                     April 11, 2006                   OMAKE-BASE(1)
