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 Win32 and Unix.

   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.

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 sequence) : value
             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".

   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.

   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.7 of December 28, 2005.


   LICENSE AND COPYRIGHT
       (C)2003-2005, Jason Hickey, Caltech 256-80, Pasadena, CA 91125, USA

       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
       Caltech 256-80
       Pasadena, CA 91125, USA
       Email: jyh@cs.caltech.edu
       WWW: http://www.cs.caltech.edu/~jyh




Build Tools                    December 28, 2005                 OMAKE-BASE(1)
