This file has been translated from LaTeX by HeVeA.
File: omake-doc, Node: Subsection 9-3-44, Next: Subsection 9-3-45, Prev: Subsection 9-3-43, Up: Section 9-3
9.3.44 while
==============
<< while <test>
<body>
>>
--or--
<< while <test>
case <test1>
<body1>
...
case <testn>
<bodyn>
default
<bodyd>
>>
The loop is executed while the test is true. In the first form, the
<body> is executed on every loop iteration. In the second form, the body
<bodyI> is selected, as the first case where the test <testI> is true.
If none apply, the optional default case is evaluated. If no cases are
true, the loop exits. The environment is automatically exported.
Examples.
Iterate for i from 0 to 9.
<< i = 0
while $(lt $i, 10)
echo $i
i = $(add $i, 1)
>>
The following example is equivalent.
<< i = 0
while true
case $(lt $i, 10)
echo $i
i = $(add $i, 1)
>>
The following example is similar, but some special cases are printed.
value is printed.
<< i = 0
while $(lt $i, 10)
case $(equal $i, 0)
echo zero
i = $(add $i, 1)
case $(equal $i, 1)
echo one
i = $(add $i, 1)
default
echo $i
i = $(add $i, 1)
>>
The 'break' function can be used to break out of the while loop early.
File: omake-doc, Node: Subsection 9-3-45, Next: Subsection 9-3-46, Prev: Subsection 9-3-44, Up: Section 9-3
9.3.45 break
==============
<< break
>>
Terminate execution of the innermost loop, returning the current
state.
File: omake-doc, Node: Subsection 9-3-46, Prev: Subsection 9-3-45, Up: Section 9-3
9.3.46 random, random-init
============================
\@name
{function:random-init}
<< random-init(i)
i : Int
random() : Int
>>
Produce a random number. The numbers are pseudo-random, and are not
cryptographically secure.
The generator is initialized from semi-random system data. Subsequent
runs should produce different results. The rando-init function can be
used to return the generator to a known state.
File: omake-doc, Node: Section 9-4, Next: Section 9-5, Prev: Section 9-3, Up: Chapter 9
9.4 Arithmetic
****************
* Menu:
* Subsection 9-4-1:: int
* Subsection 9-4-2:: float
* Subsection 9-4-3:: Basic arithmetic
* Subsection 9-4-4:: Comparisons
File: omake-doc, Node: Subsection 9-4-1, Next: Subsection 9-4-2, Up: Section 9-4
9.4.1 int
===========
The int function can be used to create integers. It returns an Int
object.
$(int 17).
File: omake-doc, Node: Subsection 9-4-2, Next: Subsection 9-4-3, Prev: Subsection 9-4-1, Up: Section 9-4
9.4.2 float
=============
The
float function can be used to create floating-point numbers. It returns
a Float object.
$(float 3.1415926).
File: omake-doc, Node: Subsection 9-4-3, Next: Subsection 9-4-4, Prev: Subsection 9-4-2, Up: Section 9-4
9.4.3 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.
- $(min <numbers>): smallest element.
- $(max <numbers>): largest element.
File: omake-doc, Node: Subsection 9-4-4, Prev: Subsection 9-4-3, Up: Section 9-4
9.4.4 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.
File: omake-doc, Node: Section 9-5, Next: Section 9-6, Prev: Section 9-4, Up: Chapter 9
9.5 First-class functions
***************************
* Menu:
* Subsection 9-5-1:: fun
* Subsection 9-5-2:: apply
* Subsection 9-5-3:: applya
* Subsection 9-5-4:: create-map, create-lazy-map
File: omake-doc, Node: Subsection 9-5-1, Next: Subsection 9-5-2, Up: Section 9-5
9.5.1 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))
>>
File: omake-doc, Node: Subsection 9-5-2, Next: Subsection 9-5-3, Prev: Subsection 9-5-1, Up: Section 9-5
9.5.2 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)
>>
The apply form can also be used for partial applications, where a
function is passed fewer arguments than it expects. The result is a
function that takes the remaining arguments, and calls the function with
the full set of arguments.
<< add2(i, j) =
add($i, $j)
succ = $(apply $(add2), 1)
i = $(succ 5) # Computes 1+5
>>
File: omake-doc, Node: Subsection 9-5-3, Next: Subsection 9-5-4, Prev: Subsection 9-5-2, Up: Section 9-5
9.5.3 applya
==============
The applya operator is used to apply a function to an array of
arguments.
$(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))
>>
The applya form can also be used for partial applications.
File: omake-doc, Node: Subsection 9-5-4, Prev: Subsection 9-5-3, Up: Section 9-5
9.5.4 create-map, create-lazy-map
===================================
\
@name{function:create-lazy-map}
The create-map is a simplified form for creating Map objects. The
create-map function takes an even number of arguments that specify
key/value pairs. For example, the following values are equivalent.
<< X = $(create-map name1, xxx, name2, yyy)
X. =
extends $(Map)
$|name1| = xxx
$|name2| = yyy
>>
The create-lazy-map function is similar, but the values are computed
lazily. The following two definitions are equivalent.
<< Y = $(create-lazy-map name1, $(xxx), name2, $(yyy))
Y. =
extends $(Map)
$|name1| = $`(xxx)
$|name2| = $`(yyy)
>>
The 'create-lazy-map' function is used in rule construction.
File: omake-doc, Node: Section 9-6, Next: Section 9-7, Prev: Section 9-5, Up: Chapter 9
9.6 Iteration and mapping
***************************
* Menu:
* Subsection 9-6-1:: foreach
File: omake-doc, Node: Subsection 9-6-1, Up: Section 9-6
9.6.1 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), a b c)
>>
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
>>
The 'break' function can be used to break out of the loop early.
File: omake-doc, Node: Section 9-7, Prev: Section 9-6, Up: Chapter 9
9.7 Boolean tests
*******************
* Menu:
* Subsection 9-7-1:: sequence-forall
* Subsection 9-7-2:: sequence-exists
* Subsection 9-7-3:: sequence-sort
* Subsection 9-7-4:: compare
File: omake-doc, Node: Subsection 9-7-1, Next: Subsection 9-7-2, Up: Section 9-7
9.7.1 sequence-forall
=======================
The forall function tests whether a predicate holds for each element
of a sequence.
<< $(sequence-forall <fun>, <args>)
sequence-forall(<var> => ..., <args>)
<body>
>>
File: omake-doc, Node: Subsection 9-7-2, Next: Subsection 9-7-3, Prev: Subsection 9-7-1, Up: Section 9-7
9.7.2 sequence-exists
=======================
The exists function tests whether a predicate holds for some element
of a sequence.
<< $(sequence-exists <fun>, <args>)
sequence-exists(<var> => ..., <args>)
<body>
>>
File: omake-doc, Node: Subsection 9-7-3, Next: Subsection 9-7-4, Prev: Subsection 9-7-2, Up: Section 9-7
9.7.3 sequence-sort
=====================
The sort function sorts the elements in an array, given a comparison
function. Given two elements (x, y), the comparison should return a
negative number if x < y; a positive number if x > y; and 0 if x = y.
<< $(sequence-sort <fun>, <args>)
sort(<var>, <var> => ..., <args>)
<body>
>>
File: omake-doc, Node: Subsection 9-7-4, Prev: Subsection 9-7-3, Up: Section 9-7
9.7.4 compare
===============
The compare function compares two values (x, y) generically returning
a negative number if x < y; a positive number if x > y; and 0 if x = y.
<< $(compare x, y) : Int
>>
File: omake-doc, Node: Chapter 10, Next: Chapter 11, Prev: Chapter 9, Up: Top
Chapter 10 File, I/O and system operations
**********************************************
* Menu:
* Section 10-1:: File names
* Section 10-2:: Path search
* Section 10-3:: File stats
* Section 10-4:: Globbing and file listings
* Section 10-5:: Filesystem operations
* Section 10-6:: vmount
* Section 10-7:: File predicates
* Section 10-8:: IO functions
* Section 10-9:: Printing functions
* Section 10-10:: Value printing functions
* Section 10-11:: Higher-level IO functions
File: omake-doc, Node: Section 10-1, Next: Section 10-2, Up: Chapter 10
10.1 File names
*****************
* Menu:
* Subsection 10-1-1:: file, dir
* Subsection 10-1-2:: tmpfile
* Subsection 10-1-3:: in
* Subsection 10-1-4:: basename
* Subsection 10-1-5:: dirname
* Subsection 10-1-6:: rootname
* Subsection 10-1-7:: dirof
* Subsection 10-1-8:: fullname
* Subsection 10-1-9:: absname
* Subsection 10-1-10:: homename
* Subsection 10-1-11:: suffix
File: omake-doc, Node: Subsection 10-1-1, Next: Subsection 10-1-2, Up: Section 10-1
10.1.1 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)
>>
File: omake-doc, Node: Subsection 10-1-2, Next: Subsection 10-1-3, Prev: Subsection 10-1-1, Up: Section 10-1
10.1.2 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.
File: omake-doc, Node: Subsection 10-1-3, Next: Subsection 10-1-4, Prev: Subsection 10-1-2, Up: Section 10-1
10.1.3 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 relative 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.
File: omake-doc, Node: Subsection 10-1-4, Next: Subsection 10-1-5, Prev: Subsection 10-1-3, Up: Section 10-1
10.1.4 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/modules.conf /foo.ml) evaluates to a.out modules.conf foo.ml.
File: omake-doc, Node: Subsection 10-1-5, Next: Subsection 10-1-6, Prev: Subsection 10-1-4, Up: Section 10-1
10.1.5 dirname
================
<< $(dirname files) : String Sequence
files : String Sequence
>>
The dirname function returns the directory name for a list of files.
The directory name is the filename with the basename removed. If a name
does not have a directory part, the directory is "."
For example, the expression $(dirname dir1\dir2\a.out
/etc/modules.conf /foo.ml bar.ml) evaluates to dir1/dir2 /etc / ..
Note: this function is different from the dirof function. The function
dirname is simple a function over strings, while dirof is a function on
filenames.
File: omake-doc, Node: Subsection 10-1-6, Next: Subsection 10-1-7, Prev: Subsection 10-1-5, Up: Section 10-1
10.1.6 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.
File: omake-doc, Node: Subsection 10-1-7, Next: Subsection 10-1-8, Prev: Subsection 10-1-6, Up: Section 10-1
10.1.7 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 /.
File: omake-doc, Node: Subsection 10-1-8, Next: Subsection 10-1-9, Prev: Subsection 10-1-7, Up: Section 10-1
10.1.8 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.
File: omake-doc, Node: Subsection 10-1-9, Next: Subsection 10-1-10, Prev: Subsection 10-1-8, Up: Section 10-1
10.1.9 absname
================
<< $(absname files) : String Sequence
files : File Sequence
>>
The absname function returns the absolute pathname for each of the
files or directories.
File: omake-doc, Node: Subsection 10-1-10, Next: Subsection 10-1-11, Prev: Subsection 10-1-9, Up: Section 10-1
10.1.10 homename
==================
<< $(homename files) : String Sequence
files : File Sequence
>>
The homename function returns the name of a file in tilde form, if
possible. 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.
File: omake-doc, Node: Subsection 10-1-11, Prev: Subsection 10-1-10, Up: Section 10-1
10.1.11 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: omake-doc, Node: Section 10-2, Next: Section 10-3, Prev: Section 10-1, Up: Chapter 10
10.2 Path search
******************
* Menu:
* Subsection 10-2-1:: which
* Subsection 10-2-2:: where
* Subsection 10-2-3:: rehash
* Subsection 10-2-4:: exists-in-path
* Subsection 10-2-5:: digest, digest-optional, digest-string
* Subsection 10-2-6:: find-in-path, find-in-path-optional
* Subsection 10-2-7:: digest-in-path, digest-in-path-optional
File: omake-doc, Node: Subsection 10-2-1, Next: Subsection 10-2-2, Up: Section 10-2
10.2.1 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.
File: omake-doc, Node: Subsection 10-2-2, Next: Subsection 10-2-3, Prev: Subsection 10-2-1, Up: Section 10-2
10.2.2 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 handled
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
>>
File: omake-doc, Node: Subsection 10-2-3, Next: Subsection 10-2-4, Prev: Subsection 10-2-2, Up: Section 10-2
10.2.3 rehash
===============
<< rehash()
>>
The rehash function resets all search paths.
File: omake-doc, Node: Subsection 10-2-4, Next: Subsection 10-2-5, Prev: Subsection 10-2-3, Up: Section 10-2
10.2.4 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.
File: omake-doc, Node: Subsection 10-2-5, Next: Subsection 10-2-6, Prev: Subsection 10-2-4, Up: Section 10-2
10.2.5 digest, digest-optional, digest-string
===============================================
\@nam
e{function:digest-optional}\
@name{function:digest-string}
<< $(digest files) : String Array
file : File Array
raises RuntimeException
$(digest-optional files) : String Array
file : File Array
$(digest-string s) : String
s : String
>>
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.
File: omake-doc, Node: Subsection 10-2-6, Next: Subsection 10-2-7, Prev: Subsection 10-2-5, Up: Section 10-2
10.2.6 find-in-path, find-in-path-optional
============================================
<< $(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.
File: omake-doc, Node: Subsection 10-2-7, Prev: Subsection 10-2-6, Up: Section 10-2
10.2.7 digest-in-path, digest-in-path-optional
================================================
\@nam
e{hevea_fun136}
<< $(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
filename 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.
File: omake-doc, Node: Section 10-3, Next: Section 10-4, Prev: Section 10-2, Up: Chapter 10
10.3 File stats
*****************
* Menu:
* Subsection 10-3-1:: file-exists, target-exists, target-is-proper
* Subsection 10-3-2:: stat-reset
* Subsection 10-3-3:: filter-exists, filter-targets, filter-proper-targets
* Subsection 10-3-4:: find-targets-in-path, find-targets-in-path-optional
* Subsection 10-3-5:: find-ocaml-targets-in-path-optional
* Subsection 10-3-6:: file-sort
* Subsection 10-3-7:: file-check-sort
File: omake-doc, Node: Subsection 10-3-1, Next: Subsection 10-3-2, Up: Section 10-3
10.3.1 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. However,
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.
File: omake-doc, Node: Subsection 10-3-2, Next: Subsection 10-3-3, Prev: Subsection 10-3-1, Up: Section 10-3
10.3.2 stat-reset
===================
<< $(stat-reset files) : String
files : File Sequence
>>
OMake uses a stat-cache. The stat-reset function reset the stat
information for the given files, forcing the stat information to be
recomputed the next time it is requested.
File: omake-doc, Node: Subsection 10-3-3, Next: Subsection 10-3-4, Prev: Subsection 10-3-2, Up: Section 10-3
10.3.3 filter-exists, filter-targets, filter-proper-targets
=============================================================
\@nam
e{hevea_fun143}
<< $(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.
Creating a "distclean" target
One way to create a simple "distclean" rule that removes generated
files from the project is by removing all files that can be built in the
current 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 actually succeed.
Also, note that no file outside the current project will be deleted.
<< .PHONY: distclean
distclean:
rm $(filter-proper-targets $(ls R, .))
>>
If you use CVS, you may wish to utilize the cvs_realclean program that
is distributed with OMake in order to create a "distclean" rule that
would delete all the files thare are not known to CVS. For example, if
you already have a more traditional "clean" target defined in your
project, and if you want the "distclean" rule to be interactive by
default, you can write the following:
<< if $(not $(defined FORCE_REALCLEAN))
FORCE_REALCLEAN = false
export
distclean: clean
cvs_realclean $(if $(FORCE_REALCLEAN), -f) -i .omakedb -i
.omakedb.lock
>>
You can add more files that you want to always keep (such as
configuration files) with the -i option.
Similarly, if you use Subversion, you utilize the
build/svn_realclean.om script that comes with OMake:
<< if $(not $(defined FORCE_REALCLEAN))
FORCE_REALCLEAN = false
export
open build/svn_realclean
distclean: clean
svn_realclean $(if $(FORCE_REALCLEAN), -f) -i .omakedb -i
.omakedb.lock
>>
See also the 'dependencies-proper' function for an alternate method
for removing intermediate files.
File: omake-doc, Node: Subsection 10-3-4, Next: Subsection 10-3-5, Prev: Subsection 10-3-3, Up: Section 10-3
10.3.4 find-targets-in-path, find-targets-in-path-optional
============================================================
<< $(find-targets-in-path path files) : File Array
$(find-targets-in-path-optional path, files) : File Array
path : Dir Array
files : File Sequence
>>
The find-target-in-path function searches for targets in the search
path. For each file file in the file list, the path is searched
sequentially for a directory dir such that the target dir/file exists.
If so, the file dir/file is returned.
For example, suppose you are building a C project, and project
contains a subdirectory src/ containing only the files fee.c and foo.c.
The following expression evaluates to the files src/fee.o src/foo.o even
if the files have not already been built.
<< $(find-targets-in-path lib src, fee.o foo.o)
# Evaluates to
src/fee.o src/foo.o
>>
The find-targets-in-path function raises an exception if the file
can't be found. The find-targets-in-path-optional function silently
removes targets that can't be found.
<< $(find-targets-in-path-optional lib src, fee.o foo.o fum.o)
# Evaluates to
src/fee.o src/foo.o
>>
File: omake-doc, Node: Subsection 10-3-5, Next: Subsection 10-3-6, Prev: Subsection 10-3-4, Up: Section 10-3
10.3.5 find-ocaml-targets-in-path-optional
============================================
The find-ocaml-targets-in-path-optional
function is very similar to the 'find-targets-in-path-optional' one,
except an OCaml-style search is used, where for every element of the
search path and for every name being searched for, first the
uncapitalized version is tried and if it is not buildable, then the
capitalized version is tried next.
File: omake-doc, Node: Subsection 10-3-6, Next: Subsection 10-3-7, Prev: Subsection 10-3-5, Up: Section 10-3
10.3.6 file-sort
==================
<< $(file-sort order, files) : File Sequence
order : String
files : File Sequence
>>
\@nam
e{hevea_default233}The
file-sort function sorts a list of filenames by build order augmented 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.
10.3.6.1 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: omake-doc, Node: Subsection 10-3-7, Prev: Subsection 10-3-6, Up: Section 10-3
10.3.7 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>)
File: omake-doc, Node: Section 10-4, Next: Section 10-5, Prev: Section 10-3, Up: Chapter 10
10.4 Globbing and file listings
*********************************
OMake commands are "glob-expanded" before being executed. That is,
names may contain patterns that are expanded to sequences of file and
directory names. The syntax follows the standard bash(1), csh(1),
syntax, with the following rules.
- A pathname is a sequence of directory and file names separated by
one of the / or \ characters. For example, the following pathnames
refer to the same file: /home/jyh/OMakefile and /home\jyh/OMakefile.
- Glob-expansion is performed on the components of a path. If a path
contains occurrences of special characters (listed below), the path
is viewed as a pattern to be matched against the actual files in the
system. The expansion produces a sequence of all file/directory names
that match.
For the following examples, suppose that a directory /dir contains
files named a, -a, a.b, and b.c.
* Matches any sequence of zero-or-more characters. For example, the
pattern /dir/a* expands to /dir/a /dir/aa /dir/a.b.
? Matches exactly one character. The pattern /dir/?a expands the
filename /dir/-a.
[...] Square brackets denote character sets and ranges in the ASCII
character set. The pattern may contain individual characters c or
character ranges c_1-c_2. The pattern matches any of the
individual characters specified, or any characters in the range. A
leading "hat" inverts the send of the pattern. To specify a
pattern that contains the literal characters -, the - should occur
as the first character in the range.
Pattern Expansion
-----------------------------------------------
/dir/[a-b]* /dir/a /dir/a.b /dir/b.c
/dir/[-a-b]* /dir/a /dir/-a /dir/a.b /dir/b.c
/dir/[-a]* /dir/a /dir/-a /dir/a.b
{s1,...,sN} Braces indicate brace-expansion. The braces delimit a
sequence of strings separated by commas. Given N strings, the
result produces N copies of the pattern, one for each of the
strings s_i.
Pattern Expansion
---------------------------------
a{b,c,d} ab ac ad
a{b{c,d},e} abc abd ae
a{?{[A-Z],d},*} a?[A-Z] a?d a*
The tilde is used to specify home directories. Depending on your
system, these might be possible expansions.
Pattern Expansion
-----------------------------------------------
~jyh /home/jyh
~bob/*.c c:\Documents and Settings\users\bob
The \ character is both a pathname separator and an escape
character. If followed by a special glob character, the \ changes
the sense of the following character to non-special status.
Otherwise, \ is viewed as a pathname separator.
Pattern Expansion
------------------------------------------------------------------
-
~jyh/\* ~jyh/* (* is literal)
/dir/\[a-z? /dir/[a-z? ([ is literal, ? is a pattern).
c:\Program Files\[A-z] c:\Program Files[A-z]*
Note that the final case might be considered to be ambiguous (where
\ should be viewed as a pathname separator, not as an escape for
the subsequent [ character. If you want to avoid this ambiguity on
Win32, you should use the forward slash / even for Win32 pathnames
(the / is translated to \ in the output).
Pattern Expansion
-------------------------------------------------------------
c:/Program Files/[A-z]* c:\Program Files\WindowsUpdate ...
* Menu:
* Subsection 10-4-1:: glob
* Subsection 10-4-2:: ls
* Subsection 10-4-3:: subdirs
File: omake-doc, Node: Subsection 10-4-1, Next: Subsection 10-4-2, Up: Section 10-4
10.4.1 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 .
F Match only normal files (any file that is not a directory).
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.
File: omake-doc, Node: Subsection 10-4-2, Next: Subsection 10-4-3, Prev: Subsection 10-4-1, Up: Section 10-4
10.4.2 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.
File: omake-doc, Node: Subsection 10-4-3, Prev: Subsection 10-4-2, Up: Section 10-4
10.4.3 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
directories, 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.
File: omake-doc, Node: Section 10-5, Next: Section 10-6, Prev: Section 10-4, Up: Chapter 10
10.5 Filesystem operations
****************************
* Menu:
* Subsection 10-5-1:: mkdir
* Subsection 10-5-2:: Stat
* Subsection 10-5-3:: stat, lstat
* Subsection 10-5-4:: unlink
* Subsection 10-5-5:: rename
* Subsection 10-5-6:: link
* Subsection 10-5-7:: symlink, symlink-raw
* Subsection 10-5-8:: readlink, readlink-raw
* Subsection 10-5-9:: chmod
* Subsection 10-5-10:: chown
* Subsection 10-5-11:: utimes
* Subsection 10-5-12:: truncate
* Subsection 10-5-13:: umask
File: omake-doc, Node: Subsection 10-5-1, Next: Subsection 10-5-2, Up: Section 10-5
10.5.1 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.
File: omake-doc, Node: Subsection 10-5-2, Next: Subsection 10-5-3, Prev: Subsection 10-5-1, Up: Section 10-5
10.5.2 Stat
=============
The Stat object represents an information about a filesystem node, as
returned by the stat and lstat functions. It contains the following
fields.
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.
Not all of the fields will have meaning on all operating systems.
File: omake-doc, Node: Subsection 10-5-3, Next: Subsection 10-5-4, Prev: Subsection 10-5-2, Up: Section 10-5
10.5.3 stat, lstat
====================
<< $(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.
File: omake-doc, Node: Subsection 10-5-4, Next: Subsection 10-5-5, Prev: Subsection 10-5-3, Up: Section 10-5
10.5.4 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.
File: omake-doc, Node: Subsection 10-5-5, Next: Subsection 10-5-6, Prev: Subsection 10-5-4, Up: Section 10-5
10.5.5 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.
File: omake-doc, Node: Subsection 10-5-6, Next: Subsection 10-5-7, Prev: Subsection 10-5-5, Up: Section 10-5
10.5.6 link
=============
<< link(src, dst)
src : Node
dst : Node
raises RuntimeException
>>
The link function creates a hard link named dst to the file or
directory src.
Hard links may work under Win32 when NTFS is used.
Normally, only the superuser can create hard links to directories.
File: omake-doc, Node: Subsection 10-5-7, Next: Subsection 10-5-8, Prev: Subsection 10-5-6, Up: Section 10-5
10.5.7 symlink, symlink-raw
=============================
\@na
me{function:symlink-raw}
<< symlink(src, dst)
src : Node
dst : Node
symlink-raw(src, dst)
src : String
dst : Node
raises RuntimeException
>>
The symlink function creates a symbolic link dst that points to the
src file.
For symlink, the link name is computed relative to the target
directory. For example, the expression $(symlink a/b, c/d) creates a
link named c/d -> ../a/b.
The function symlink-raw performs no translation. The symbolic link is
set to the src string.
Symbolic links are not supported in Win32. Consider using the ln-or-cp
Shell alias for cross-platform portable linking/copying.
File: omake-doc, Node: Subsection 10-5-8, Next: Subsection 10-5-9, Prev: Subsection 10-5-7, Up: Section 10-5
10.5.8 readlink, readlink-raw
===============================
\@n
ame{function:readlink-raw}
<< $(readlink node...) : Node
node : Node
$(readlink-raw node...) : String
node : Node
>>
The readlink function reads the value of a symbolic link.
File: omake-doc, Node: Subsection 10-5-9, Next: Subsection 10-5-10, Prev: Subsection 10-5-8, Up: Section 10-5
10.5.9 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.
Options:
-v Explain what is happening.
-r Change files and directories recursively.
-f Continue on errors.
-- Interpret the remaining argument literally.
File: omake-doc, Node: Subsection 10-5-10, Next: Subsection 10-5-11, Prev: Subsection 10-5-9, Up: Section 10-5
10.5.10 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.
File: omake-doc, Node: Subsection 10-5-11, Next: Subsection 10-5-12, Prev: Subsection 10-5-10, Up: Section 10-5
10.5.11 utimes
================
<< utimes(atime, mtime, node...)
atime : Float
mtime : Float
node : Node
raises RuntimeException
>>
The utimes function changes the access and modification times of the
files.
File: omake-doc, Node: Subsection 10-5-12, Next: Subsection 10-5-13, Prev: Subsection 10-5-11, Up: Section 10-5
10.5.12 truncate
==================
<< truncate(length, node...)
length : Int
node : Node or Channel
raises RuntimeException
>>
The truncate function truncates a file to the given length.
File: omake-doc, Node: Subsection 10-5-13, Prev: Subsection 10-5-12, Up: Section 10-5
10.5.13 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.
File: omake-doc, Node: Section 10-6, Next: Section 10-7, Prev: Section 10-5, Up: Chapter 10
10.6 vmount
*************
* Menu:
* Subsection 10-6-1:: vmount
* Subsection 10-6-2:: add-project-directories
* Subsection 10-6-3:: remove-project-directories
File: omake-doc, Node: Subsection 10-6-1, Next: Subsection 10-6-2, Up: Section 10-6
10.6.1 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.
File: omake-doc, Node: Subsection 10-6-2, Next: Subsection 10-6-3, Prev: Subsection 10-6-1, Up: Section 10-6
10.6.2 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.
File: omake-doc, Node: Subsection 10-6-3, Prev: Subsection 10-6-2, Up: Section 10-6
10.6.3 remove-project-directories
===================================
\@nam
e{hevea_fun169}
<< remove-project-directories(dirs)
dirs : Dir Array
>>
Removed the directories from the set of directories that omake
considers 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.
File: omake-doc, Node: Section 10-7, Next: Section 10-8, Prev: Section 10-6, Up: Chapter 10
10.7 File predicates
**********************
* Menu:
* Subsection 10-7-1:: test
* Subsection 10-7-2:: find
File: omake-doc, Node: Subsection 10-7-1, Next: Subsection 10-7-2, Up: Section 10-7
10.7.1 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 has a non-zero size
- -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
traditional 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
evaluates to the length of the string.
A file is a string that represents the name of a file.
The syntax mirrors that of the test(1) program. If you are on a Unix
system, the man page explains more. Here are some examples.
<< # Create an empty file
osh> touch foo
# Is the file empty?
osh> test(-e foo)
- : true
osh> test(! -e foo)
- : false
# Create another file
osh> touch boo
# Is the newer file newer?
osh> test(boo -nt foo)
- : true
# A more complex query
# boo is newer than foo, and foo is empty
osh> test(\( boo -nt foo \) -a -e foo)
- : true
>>
