This file has been translated from LaTeX by HeVeA.  Node: Subsection 13-3-3, Next: Chapter 14, Prev: Subsection 13-3-2, Up: Section 13-3 13.3.3 Snprintf configuration =============================== Add `open configure/snprintf' line to your `OMakefile' to get access to the following autoconfiguration variables. SNPRINTF_AVAILABLE A boolean flag telling whether the snprintf function is available in the standard C library.  Node: Chapter 14, Next: Section 14-1, Prev: Section 13-3, Up: Top Chapter 14 The OSH shell **************************** OMake also includes a standalone command-line interpreter osh that can be used as an interactive shell. The shell uses the same syntax, and provides the same features on all platforms omake supports, including Win32. * Menu: * Section 14-1:: Startup * Section 14-2:: Aliases * Section 14-3:: Interactive syntax  Node: Section 14-1, Next: Section 14-2, Prev: Chapter 14, Up: Chapter 14 14.1 Startup *=*=*=*=*=*=*= On startup, osh reads the file `~/.oshrc' if it exists. The syntax of this file is the same as an OMakefile. The following additional variables are significant. prompt The `prompt' variable specifies the command-line prompt. It can be a simple string. << prompt = osh> >> Or you may choose to define it as a function of no arguments. << prompt() = return $"<$(USER):$(HOST) $(homename $(CWD))>" >> An example of the latter prompt is as follows. << cd links/omake >> If you include any "invisible" text in the prompt (such as various terminal escape sequences), they must be wrapped using the 'prompt-invisible' function. For example, to create a bold prompt on terminals that support it, you can use the following. << prompt = bold-begin = $(prompt-invisible $(tgetstr bold)) bold-end = $(prompt-invisible $(tgetstr sgr0)) value $(bold-begin)$"osh>"$(bold-end) >> ignoreeof If the `ignoreeof' is `true', then `osh' will not exit on a terminal end-of-file (usually `^D' on Unix systems).  Node: Section 14-2, Next: Section 14-3, Prev: Section 14-1, Up: Chapter 14 14.2 Aliases *=*=*=*=*=*=*= Command aliases are defined by adding functions to the `Shell.' object. The following alias adds the `-AF' option to the `ls' command. << Shell. += ls(argv) = "ls" -AF $(argv) >> Quoted commands do not undergo alias expansion. The quotation `"ls"' prevents the alias from being recursive.  Node: Section 14-3, Next: Appendix A, Prev: Section 14-2, Up: Chapter 14 14.3 Interactive syntax *=*=*=*=*=*=*=*=*=*=*=*=* The interactive syntax in `osh' is the same as the syntax of an `OMakefile', with one exception in regard to indentation. The line before an indented block must have a colon at the end of the line. A block is terminated with a `.' on a line by itself, or `^D'. In the following example, the first line `if true' has no body, because there is no colon. << # The following if has no body osh>if true # The following if has a body osh>if true: if> if true: if> println(Hello world) if> . Hello world >> Note that `osh' makes some effort to modify the prompt while in an indented body, and it auto-indents the text. The colon signifier is also allowed in files, although it is not required.  Node: Appendix A, Next: Section A-1, Prev: Chapter 14, Up: Top Appendix A Synopsis *********************** omake [-j ] [-k] [-p] [-P] [-n] [-s] [-S] [-w] [-t] [-u] [-U] [-R] [--verbose] [--project] [--depend] [--progress] [--print-status] [--print-exit] [--print-dependencies] [--show-dependencies ] [--all-dependencies] [--verbose-dependencies] [--force-dotomake] [--dotomake ] [--flush-includes] [--configure] [--save-interval ] [--install] [--install-all] [--install-force] [--version] [--absname] [--output-normal] [--output-postpone] [--output-only-errors] [--output-at-end] filename... [var-definition...] * Menu: * Section A-1:: General usage * Section A-2:: Output control * Section A-3:: Build options * Section A-4:: Additional options * Section A-5:: Environment variables * Section A-6:: Functions * Section A-7:: Option processing * Section A-8:: .omakerc  Node: Section A-1, Next: Section A-2, Prev: Appendix A, Up: Appendix A A.1 General usage *=*=*=*=*=*=*=*=*=* For Boolean options (for example, `-s', `--progress', etc.) the option can include a prefix `--no', which inverts the usual sense of the option. For example, the option `--progress' means "print a progress bar," while the option `--no--progress' means "do not print a progress bar." If multiple instances of an option are specified, the final option determines the behavior of OMake. In the following command line, the final `--no-S' cancels the earlier `-S'. << % omake -S --progress --no-S >>  Node: Section A-2, Next: Subsection A-2-1, Prev: Section A-1, Up: Appendix A A.2 Output control *=*=*=*=*=*=*=*=*=*= * Menu: * Subsection A-2-1:: -s * Subsection A-2-2:: -S * Subsection A-2-3:: -w * Subsection A-2-4:: --progress * Subsection A-2-5:: --print-status * Subsection A-2-6:: --print-exit * Subsection A-2-7:: --verbose * Subsection A-2-8:: --output-normal * Subsection A-2-9:: --output-postpone * Subsection A-2-10:: --output-only-errors * Subsection A-2-11:: --output-at-end * Subsection A-2-12:: -o  Node: Subsection A-2-1, Next: Subsection A-2-2, Prev: Section A-2, Up: Section A-2 A.2.1 -s ========== `-s' Never not print commands as they are executed (be "silent").  Node: Subsection A-2-2, Next: Subsection A-2-3, Prev: Subsection A-2-1, Up: Section A-2 A.2.2 -S ========== `-S' Do not print commands as they are executed unless they produce output and/or fail. This is the default.  Node: Subsection A-2-3, Next: Subsection A-2-4, Prev: Subsection A-2-2, Up: Section A-2 A.2.3 -w ========== `-w' Print directory information in make format as commands are executed. This is mainly useful for editors that expect make-style directory information for determining the location of errors.  Node: Subsection A-2-4, Next: Subsection A-2-5, Prev: Subsection A-2-3, Up: Section A-2 A.2.4 --progress ================== `--progress' Print a progress indicator. This option is enabled by default when the OMake's output (`stdout') is on a terminal and disabled by default (except on Windows) when the OMake's output is redirected.  Node: Subsection A-2-5, Next: Subsection A-2-6, Prev: Subsection A-2-4, Up: Section A-2 A.2.5 --print-status ====================== `--print-status' Print status lines (the `+' and `-' lines).  Node: Subsection A-2-6, Next: Subsection A-2-7, Prev: Subsection A-2-5, Up: Section A-2 A.2.6 --print-exit ==================== `--print-exit' Print termination codes when commands complete.  Node: Subsection A-2-7, Next: Subsection A-2-8, Prev: Subsection A-2-6, Up: Section A-2 A.2.7 --verbose ================= `--verbose' Make OMake very verbose. This option is equivalent to `--no-S --print-status --print-exit VERBOSE=true'  Node: Subsection A-2-8, Next: Subsection A-2-9, Prev: Subsection A-2-7, Up: Section A-2 A.2.8 --output-normal ======================= `--output-normal' As rule commands are executed, relay their output to the OMake output right away. This is enabled by default, unless `--output-postpone' or `--output-only-errors' is enabled.  Node: Subsection A-2-9, Next: Subsection A-2-10, Prev: Subsection A-2-8, Up: Section A-2 A.2.9 --output-postpone ========================= `--output-postpone' When a rule finishes, print the output as a single block. This is useful in combination `-j' option (see Section A.3.12*Note Subsection A-3-12::), where the output of multiple subprocesses can be garbled. The diversion is printed as a single coherent unit. Note that enabling `--output-postpone' will by default disable the `--output-normal' option. This might be problematic if you have a command that decides to ask for interactive input. If the `--output-postpone' is enabled, but the `--output-normal' is not, the prompt of such a command will not be visible and it may be hard to figure out why the build appears "stuck". You might also consider using the `--progress' flag (see Section A.2.4*Note Subsection A-2-4::) so that you can see when the build is active.  Node: Subsection A-2-10, Next: Subsection A-2-11, Prev: Subsection A-2-9, Up: Section A-2 A.2.10 --output-only-errors ============================= `--output-only-errors' Similar to `--output-postpone', except that the postponed output from commands that were successful will be discarded. This can be useful in reducing unwanted output so that you can concentrate on any errors.  Node: Subsection A-2-11, Next: Subsection A-2-12, Prev: Subsection A-2-10, Up: Section A-2 A.2.11 --output-at-end ======================== `--output-at-end' If any rules/commands fail, re-print the output of the failed commands when OMake finishes the build. This is especially useful when any of the `-k', `-p', or `-P' options are enabled. This option is off by default. However, when `-k' is enabled --- either explicitly or via one of the `-p'/`-P' options --- `--output-at-end' will be enabled by default.  Node: Subsection A-2-12, Next: Section A-3, Prev: Subsection A-2-11, Up: Section A-2 A.2.12 -o =========== `-o [01jwWpPxXsS]' For brevity, the `-o' option is also provided to duplicate the above output options. The `-o' option takes a argument consisting of a sequence of characters. The characters are read from left-to-right; each specifies a set of output options. In general, an uppercase character turns the option on; a lowercase character turns the option off. 0 Equivalent to `-s --output-only-errors' This option specifies that `omake' should be as quiet as possible. If any errors occur during the build, the output is delayed until the build terminates. Output from successful commands is discarded. 1 Equivalent to `-S --progress --output-only-errors' This is a slightly more relaxed version of "quiet" output. The output from successful commands is discarded. The output from failed commands is printed immediately after the command complete. The output from failed commands is displayed twice: once immediately after the command completes, and again when the build completes. A progress bar is displayed so that you know when the build is active. Include the ``p'' option if you want to turn off the progress bar (for example `omake -o 1p'). 2 Equivalent to `--progress --output-postpone' The is even more relaxed, output from successful commands is printed. This is often useful for deinterleaving the output when using `-j'. W Equivalent to `-w' w Equivalent to `--no-w' P Equivalent to `--progress' p Equivalent to `--no--progress' X Equivalent to `--print-exit' x Equivalent to `--no-print-exit' S Equivalent to `-S' s Equivalent to `--no-S'  Node: Section A-3, Next: Subsection A-3-1, Prev: Section A-2, Up: Appendix A A.3 Build options *=*=*=*=*=*=*=*=*=* * Menu: * Subsection A-3-1:: -k * Subsection A-3-2:: -n * Subsection A-3-3:: -p * Subsection A-3-4:: -P * Subsection A-3-5:: -R * Subsection A-3-6:: -t * Subsection A-3-7:: -U * Subsection A-3-8:: --depend * Subsection A-3-9:: --configure * Subsection A-3-10:: --force-dotomake * Subsection A-3-11:: --dotomake * Subsection A-3-12:: -j * Subsection A-3-13:: --print-dependencies * Subsection A-3-14:: --show-dependencies * Subsection A-3-15:: --all-dependencies * Subsection A-3-16:: --verbose-dependencies * Subsection A-3-17:: --install * Subsection A-3-18:: --install-all * Subsection A-3-19:: --install-force * Subsection A-3-20:: --absname * Subsection A-3-21:: variable definition  Node: Subsection A-3-1, Next: Subsection A-3-2, Prev: Section A-3, Up: Section A-3 A.3.1 -k ========== `-k' Do not abort when a build command fails; continue to build as much of the project as possible. This option is implied by both `-p' and `-P' options. In turn, this option would imply the `--output-at-end' option.  Node: Subsection A-3-2, Next: Subsection A-3-3, Prev: Subsection A-3-1, Up: Section A-3 A.3.2 -n ========== `-n' This can be used to see what would happen if the project were to be built.  Node: Subsection A-3-3, Next: Subsection A-3-4, Prev: Subsection A-3-2, Up: Section A-3 A.3.3 -p ========== `-p' Watch the filesystem for changes, and continue the build until it succeeds. If this option is specified, omake will restart the build whenever source files are modified. Implies -k.  Node: Subsection A-3-4, Next: Subsection A-3-5, Prev: Subsection A-3-3, Up: Section A-3 A.3.4 -P ========== `-P' Watch the filesystem for changes forever. If this option is specified, omake will restart the build whenever source files are modified. Implies -k.  Node: Subsection A-3-5, Next: Subsection A-3-6, Prev: Subsection A-3-4, Up: Section A-3 A.3.5 -R ========== `-R' Ignore the current directory and build the project from its root directory. When omake is run in a subdirectory of a project and no explicit targets are given on the command line, it would normally only build files within the current directory and its subdirectories (more precisely, it builds all the `.DEFAULT' targets in the current directory and its subdirectories). If the -R option is specified, the build is performed as if omake were run in the project root. In other words, with the `-R' option, all the relative targets specified on the command line will be taken relative to the project root (instead of relative to the current directory). When no targets are given on the command line, all the `.DEFAULT' targets in the project will be built (regardless of the current directory).  Node: Subsection A-3-6, Next: Subsection A-3-7, Prev: Subsection A-3-5, Up: Section A-3 A.3.6 -t ========== `-t' Update the omake database to force the project to be considered up-to-date.  Node: Subsection A-3-7, Next: Subsection A-3-8, Prev: Subsection A-3-6, Up: Section A-3 A.3.7 -U ========== `-U' Do not trust cached build information. This will force the entire project to be rebuilt.  Node: Subsection A-3-8, Next: Subsection A-3-9, Prev: Subsection A-3-7, Up: Section A-3 A.3.8 --depend ================ `--depend' Do not trust cached dependency information. This will force files to be rescanned for dependency information.  Node: Subsection A-3-9, Next: Subsection A-3-10, Prev: Subsection A-3-8, Up: Section A-3 A.3.9 --configure =================== `--configure' Re-run `static.' sections of the included omake files, instead of trusting the cached results.  Node: Subsection A-3-10, Next: Subsection A-3-11, Prev: Subsection A-3-9, Up: Section A-3 A.3.10 --force-dotomake ========================= `--force-dotomake' Always use the `$HOME/.omake' for the `.omc' cache files.  Node: Subsection A-3-11, Next: Subsection A-3-12, Prev: Subsection A-3-10, Up: Section A-3 A.3.11 --dotomake =================== `--dotomake ' Use the specified directory instead of the `$HOME/.omake' for the placement of the `.omc' cache files.  Node: Subsection A-3-12, Next: Subsection A-3-13, Prev: Subsection A-3-11, Up: Section A-3 A.3.12 -j =========== `-j ' Run multiple build commands in parallel. The count specifies a bound on the number of commands to run simultaneously. In addition, the count may specify servers for remote execution of commands in the form `server=count'. For example, the option `-j 2:small.host.org=1:large.host.org=4' would specify that up to 2 jobs can be executed locally, 1 on the server `small.host.org' and 4 on `large.host.org'. Each remote server must use the same filesystem location for the project. Remote execution is currently an experimental feature. Remote filesystems like NFS do not provide adequate file consistency for this to work.  Node: Subsection A-3-13, Next: Subsection A-3-14, Prev: Subsection A-3-12, Up: Section A-3 A.3.13 --print-dependencies ============================= `--print-dependencies' Print dependency information for the targets on the command line.  Node: Subsection A-3-14, Next: Subsection A-3-15, Prev: Subsection A-3-13, Up: Section A-3 A.3.14 --show-dependencies ============================ `--show-dependencies ' Print dependency information if the `target' is built.  Node: Subsection A-3-15, Next: Subsection A-3-16, Prev: Subsection A-3-14, Up: Section A-3 A.3.15 --all-dependencies =========================== `--all-dependencies' If either of the options --print-dependencies or --show-dependencies is in effect, print transitive dependencies. That is, print all dependencies recursively. If neither option --print-dependencies, --show-dependencies is specified, this option has no effect.  Node: Subsection A-3-16, Next: Subsection A-3-17, Prev: Subsection A-3-15, Up: Section A-3 A.3.16 --verbose-dependencies =============================== `--verbose-dependencies' If either of the options --print-dependencies or --show-dependencies is in effect, also print listings for each dependency. The output is very verbose, consider redirecting to a file. If neither option --print-dependencies, --show-dependencies is specified, this option has no effect.  Node: Subsection A-3-17, Next: Subsection A-3-18, Prev: Subsection A-3-16, Up: Section A-3 A.3.17 --install ================== `--install' Install default files OMakefile and OMakeroot into the current directory. You would typically do this to start a project in the current directory.  Node: Subsection A-3-18, Next: Subsection A-3-19, Prev: Subsection A-3-17, Up: Section A-3 A.3.18 --install-all ====================== `--install-all' In addition to installing files OMakefile and OMakeroot, install default OMakefiles into each subdirectory of the current directory. cvs(1) rules are used for filtering the subdirectory list. For example, OMakefiles are not copied into directories called `CVS', `RCCS', etc.  Node: Subsection A-3-19, Next: Subsection A-3-20, Prev: Subsection A-3-18, Up: Section A-3 A.3.19 --install-force ======================== `--install-force' Normally, omake will prompt before it overwrites any existing OMakefile. If this option is given, all files are forcibly overwritten without prompting.  Node: Subsection A-3-20, Next: Subsection A-3-21, Prev: Subsection A-3-19, Up: Section A-3 A.3.20 --absname ================== `--absname' Filenames should expand to absolute pathnames. N.B. This is an experimental option. It may become deprecated.  Node: Subsection A-3-21, Next: Section A-4, Prev: Subsection A-3-20, Up: Section A-3 A.3.21 variable definition ============================ `name=[value]' omake variables can also be defined on the command line in the form `name=value'. For example, the `CFLAGS' variable might be defined on the command line with the argument `CFLAGS="-Wall -g"'.  Node: Section A-4, Next: Section A-5, Prev: Section A-3, Up: Appendix A A.4 Additional options *=*=*=*=*=*=*=*=*=*=*=*= In addition, omake supports a number of debugging flags on the command line. Run `omake --help' to get a summary of these flags.  Node: Section A-5, Next: Subsection A-5-1, Prev: Section A-4, Up: Appendix A A.5 Environment variables *=*=*=*=*=*=*=*=*=*=*=*=*=* * Menu: * Subsection A-5-1:: OMAKEFLAGS * Subsection A-5-2:: OMAKELIB  Node: Subsection A-5-1, Next: Subsection A-5-2, Prev: Section A-5, Up: Section A-5 A.5.1 OMAKEFLAGS ================== If defines, the `OMAKEFLAGS' should specify a set of options exactly as they are specified on the command line.  Node: Subsection A-5-2, Next: Section A-6, Prev: Subsection A-5-1, Up: Section A-5 A.5.2 OMAKELIB ================ If defined, the `OMAKELIB' environment variable should refer to the installed location of the OMake standard library. This is the directory that contains `Pervasives.om' etc. On a Unix system, this is often `/usr/lib/omake' or `/usr/local/lib/omake', and on Win32 systems it is often `c:\Program Files\OMake\lib'. If not defined, `omake' uses the default configured location. You should normally leave this unset.  Node: Section A-6, Next: Subsection A-6-1, Prev: Section A-5, Up: Appendix A A.6 Functions *=*=*=*=*=*=*=* * Menu: * Subsection A-6-1:: OMakeFlags  Node: Subsection A-6-1, Next: Section A-7, Prev: Section A-6, Up: Section A-6 A.6.1 OMakeFlags ================== The `OMakeFlags' function can be used within an `OMakefile' to modify the set of options. The options should be specified exactly as they are on the command line. For example, if you want some specific project to be silent and display a progress bar, you can add the following line to your `OMakefile'. << OMakeFlags(-S --progress) >> For options where it makes sense, the options are scoped like variables. For example, if you want OMake to be silent for a single rule (instead of for the entire project), you can use scoping the restrict the range of the option. << section # Do not display command output when foo is constructed OMakeFlags(-S) foo: fee echo "This is a generated file" > foo cat fee >> foo chmod 555 foo >>  Node: Section A-7, Next: Section A-8, Prev: Section A-6, Up: Appendix A A.7 Option processing *=*=*=*=*=*=*=*=*=*=*=* When `omake' is invoked, the options are processed in the following order. 1. All options specified by the `OMAKEFLAGS' environment variable are defined globally. 2. All options from the command line are defined globally. 3. Any individual calls the the `OMakeFlags' function modify the options locally.  Node: Section A-8, Next: Appendix B, Prev: Section A-7, Up: Appendix A A.8 .omakerc *=*=*=*=*=*=*= If the `$(HOME)/.omakerc' exists, it is read before any of the `OMakefiles' in your project. The `.omakerc' file is frequently used for user-specific customization. For example, instead of defining the `OMAKEFLAGS' environment variable, you could add a line to your `.omakerc'. << $(HOME)/.omakerc: # My private options OMakeFlags(-S --progress) >>  Node: Appendix B, Next: Section B-1, Prev: Appendix A, Up: Top Appendix B OMake grammar **************************** * Menu: * Section B-1:: OMake lexical conventions * Section B-2:: The OMake grammar * Section B-3:: Dollar modifiers  Node: Section B-1, Next: Subsection B-1-1, Prev: Appendix B, Up: Appendix B B.1 OMake lexical conventions *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* The OMake language is based on the language for GNU/BSD make, where there are few lexical conventions. Strictly speaking, there are no keywords, and few special symbols. * Menu: * Subsection B-1-1:: Comments * Subsection B-1-2:: Special characters * Subsection B-1-3:: Identifiers * Subsection B-1-4:: Command identifiers * Subsection B-1-5:: Variable references * Subsection B-1-6:: String constants  Node: Subsection B-1-1, Next: Subsection B-1-2, Prev: Section B-1, Up: Section B-1 B.1.1 Comments ================ Comments begin with the `#' character and continue to the end-of-line. Text within a comment is unrestricted. Examples. << # This is a comment # This $comment contains a quote " character >>  Node: Subsection B-1-2, Next: Subsection B-1-3, Prev: Subsection B-1-1, Up: Section B-1 B.1.2 Special characters ========================== The following characters are special in some contexts. << $ ( ) , . = : " ' ` \ # >> - `$' is used to denote a variable reference, or function application. - Parentheses `)', `(' are argument deliminters. - The command `,' is an argument separator. - The period symbol `.' is a name separator. - The equality symbol `=' denotes a definition. - The colon symbol `:' is used to denote rules, and (optionally) to indicate that an expression is followed by an indented body. - The quotation symbols `"' and `'' delimit character strings. - The symbol `#' is the first character of a constant. - The escape symbol `\' is special only when followed by another special character. In this case, the special status of the second character is removed, and the sequence denotes the second character. Otherwise, the `\' is not special. Examples: - `\$': the `$' character (as a normal character). - `\#': the `#' character (as a normal character). - `\\': the `\' character (as a normal character). - `c\:\Windows\moo\#boo': the string `c:\Windows\moo#boo'.  Node: Subsection B-1-3, Next: Subsection B-1-4, Prev: Subsection B-1-2, Up: Section B-1 B.1.3 Identifiers =================== Identifiers (variable names) are drawn from the ASCII alphanumeric characters as well as `_', `-', `~', `@'. Case is significant; the following identifiers are distinct: `FOO', `Foo', `foo'. The identifier may begin with any of the valid characters, including digits. Using `egrep' notation, the regular expression for identifiers is defined as follows. << identifier ::= [-@~_A-Za-z0-9]+ >> The following are legal identifiers. << Xyz hello_world seventy@nine 79-32 Gnus~Gnats CFLAGS >> The following are not legal identifiers. << x+y hello&world >>  Node: Subsection B-1-4, Next: Subsection B-1-5, Prev: Subsection B-1-3, Up: Section B-1 B.1.4 Command identifiers =========================== The following words have special significance when they occur as the first word of a program line. They are not otherwise special. << case catch class declare default do else elseif export extends finally if import include match open raise return section switch try value when while >>  Node: Subsection B-1-5, Next: Subsection B-1-6, Prev: Subsection B-1-4, Up: Section B-1 B.1.5 Variable references =========================== A variable reference is denoted with the `$' special character followed by an identifier. If the identifier name has more than one character, it must be enclosed in parentheses. The parenthesized version is most common. The following are legal variable references. << $(Xyz) $(hello_world) $(seventy@nine) $(79-32) $(Gnus~Gnats) $(CFLAGS) >> Single-character references also include several additional identifiers, including `&*<^?]['. The following are legal single-character references. << $@ $& $* $< $^ $+ $? $[ $] $A $_ $a $b $x $1 $2 $3 >> Note that a non-parenthesized variable reference is limited to a single character, even if it is followed by additional legal identifier charqcters. Suppose the value of the `$x' variable is 17. The following examples illustrate evaluation. << $x evaluates to 17 foo$xbar evaluates to foo17bar foo$(x)bar evaluates to foo17bar >> The special sequence `$$' represents the character literal `$'. That is, the two-character sequences `\$' and `$$' are normally equalivalent.  Node: Subsection B-1-6, Next: Section B-2, Prev: Subsection B-1-5, Up: Section B-1 B.1.6 String constants ======================== Literal strings are defined with matching string delimiters. A left string delimiter begins with the dollar-sign `$', and a non-zero number of single-quote or double-quote characters. The string is terminated with a matching sequence of quotation symbols. The delimiter quotation may not be mixed; it must contain only single-quote characters, or double-quote characters. The following are legal strings. << $'Hello world' $"""printf("Hello world\n")""" $'''' Large "block" of text # spanning ''multiple'' lines'''' >> The string delimiters are not included in the string constant. In the single-quote form, the contents of the string are interpreted verbatim--there are no special characters. The double-quote form permits expression evaluation within the string, denoted with the `$' symbol. The following are some examples. << X = Hello Y = $""$X world"" # Hello world Z = $'''$X world''' # $X world I = 3 W = $"6 > $(add $I, 2)" # 6 > 5 >> Note that quotation symbols without a leading `$' are not treated specially by OMake. The quotation symbols is included in the sequence. << osh>println('Hello world') 'Hello world' osh>println($'Hello world') Hello world osh>X = Hello - : "Hello" : Sequence osh>println('$X world') Hello world >>  Node: Section B-2, Next: Subsection B-2-1, Prev: Section B-1, Up: Appendix B B.2 The OMake grammar *=*=*=*=*=*=*=*=*=*=*=* OMake programs are constructed from expressions and statements. Generally, an input program consists of a sequence of statements, each of which consists of one or more lines. Indentation is significant--if a statement consists of more than one line, the second and remaining lines (called the body) are usually indented relative to the first line. * Menu: * Subsection B-2-1:: Expressions * Subsection B-2-2:: Statements and programs  Node: Subsection B-2-1, Next: Subsection B-2-2, Prev: Section B-2, Up: Section B-2 B.2.1 Expressions =================== The following table lists the syntax for expressions. expr ::= (empty) -- Text (see note) | text | string-literal -- Applications | dollar `' | dollar `(' pathid args `)' -- Concatenation | expr expr dollar ::= `$' | `$`' | `$,' pathid ::= id | pathid `.' id arg ::= expr -- excluding special characters `)(,') args ::= (empty) | arg, ..., arg An expression is a sequence composed of text, string-literals, variables references and function applications. Text is any sequence of non-special characters. B.2.1.1 Inline applications ----------------------------- An application is the application of a function to zero-or-more arguments. Inline applications begin with one of the "dollar" sequences `$', `$`', or `$,'. The application itself is specified as a single character (in which case it is a variable reference), or it is a parenthesized list including a function identifier pathid, and zero-or-more comma-separated arguments args. The arguments are themselves a variant of the expressions where the special character `)(,' are not allowed (though any of these may be made non-special with the `\' escape character). The following are some examples of valid expressions. - `xyz abc' The text sequence "`xyz abc'" - `xyz$wabc' A text sequence containing a reference to the variable `w'. - `$(addsuffix .c, $(FILES))' An application of the function `addsuffix', with first argument `.c', and second argument `$(FILES)'. - `$(a.b.c 12)' This is a method call. The variable `a' must evaluate to an object with a field `b', which must be an object with a method `c'. This method is called with argument `12'. The additional dollar sequences specify evaluation order, `$`' (lazy) and `$,' (eager), as discussed in the section on dollar modifiers (Section B.3*Note Section B-3::).  Node: Subsection B-2-2, Next: Section B-3, Prev: Subsection B-2-1, Up: Section B-2 B.2.2 Statements and programs =============================== The following table lists the syntax of statements and programs. params ::= (empty) | id, ..., id target ::= expr -- excluding special character `:' program ::= stmt `' ... `' stmt stmt ::= -- Special forms | command expr optcolon-body | command ( args ) optcolon-body | catch id ( id ) optcolon-body | class id ... id -- Variable definitions | pathid {+}= expr | pathid {+}= `' indented-body | pathid`[]' {+}= expr | pathid`[]' {+}= `' indented-exprs -- Functions | pathid(args) optcolon-body | pathid(params) = `' indented-body -- Objects | pathid `.' {+}= `' indented-body -- Rules | target : target rule-options `' indented-body | target :: target rule-options `' indented-body | target : target : target rule-options `' indented-body | target :: target : target rule-options `' indented-body -- Shell commands | expr indented-body ::= (empty) | indented-stmt `' ... `' indented-stmt indented-exprs ::= (empty) | indented-expr `' ... `' indented-expr optcolon-body ::= (empty) | `' indented-body | : `' indented-body rule-option ::= :id: target rule-options ::= (empty) | rule-options rule-option B.2.2.1 Special forms ----------------------- The special forms include the following. Conditionals (see the section on conditionals --- Section 4.9*Note Section 4-9::). The `if' command should be followed by an expression that represents the condition, and an indented body. The conditional may be followed by `elseif' and `else' blocks. << if expr indented-body elseif expr indented-body ... else indented-body >> matching (see the section on matching --- Section 4.10*Note Section 4-10::). The `switch' and `match' commands perform pattern-matching. All cases are optional. Each case may include `when' clauses that specify additional matching conditions. << match(expr) case expr indented-body when expr indented-body ... case expr indented-body default indented-body >> Exceptions (see also the 'try' function documentation). The `try' command introduces an exception handler. Each `name' is the name of a class. All cases, including `catch', `default', and `finally' are optional. The `catch' and `default' clauses contain optional `when' clauses. << try indented-body catch name1(id1) indented-body when expr indented-body ... catch nameN(idN) indented-body default indented-body finally indented-body >> The `raise' command is used to raise an exception. << raise expr >> section (see the `section' description in Section 4.8*Note Section 4-8::). The `section' command introduces a new scope. << section indented-body >> include, open (see also Section 4.7*Note Section 4-7::). The `include' command performs file inclusion. The expression should evaluate to a file name. The `open' form is like include, but it performs the inclusion only if the inclusion has not already been performed. The `open' form is usually used to include library files. [jyh-- this behavior will change in subsequent revisions.] << include expr open expr >> return (see the description of functions in Section 4.5*Note Section 4-5::). The `return' command terminates execution and returns a value from a function. << return expr >> value (see the description of functions in Section 4.5*Note Section 4-5::). The `value' command is an identity. Syntactically, it is used to coerce a n expression to a statement. << value expr >> export (see the section on scoping --- Section 5.3*Note Section 5-3::). The `export' command exports a environment from a nested block. If no arguments are given, the entire environment is exported. Otherwise, the export is limited to the specified identifiers. << export expr >> while (see also the 'while' function description). The `while' command introduces a `while' loop. << while expr indented-body >> class, extends (see the section on objects --- Section 4.11*Note Section 4-11::). The `class' command specifies an identifier for an object. The `extends' command specifies a parent object. << class id extends expr >> B.2.2.2 Variable definitions ------------------------------ See the section on variables (Section 4.1*Note Section 4-1::). The simplest variable definition has the following syntax. The `=' form is a new definition. The += form appends the value to an existing definition. << id = expr id += expr osh> X = 1 - : "1" : Sequence osh> X += 7 - : "1" " " "7" : Sequence >> A multi-line form is allowed, where the value is computed by an indented body. << id {+}= indented-body osh> X = Y = HOME println(Y is $Y) getenv($Y) Y is HOME - : "/home/jyh" : Sequence >> The name may be qualified qith one of the `public', `prtected', or `private' modifiers. Public variables are dynamically scoped. Protected variables are fields in the current object. Private variables are statically scoped. [jyh: revision 0.9.9 introduces modular namespaces; the meaning of these qualifiers is slightly changed.] << public.X = $(addsuffix .c, 1 2 3) protected.Y = $(getenv HOME) private.Z = $"Hello world" >> B.2.2.3 Applications and function definitions ----------------------------------------------- See the section on functions (Section 4.5*Note Section 4-5::). A function-application statement is specified as a function name, followed a parenthesized list of comma-separated arguments. << osh> println($"Hello world") osh> FILES = 1 2 3 - : 1 2 3 osh> addsuffix(.c, $(FILES)) - : 1.c 2.c 3.c # The following forms are equivalent osh> value $(println $"Hello world") osh> value $(addsuffix .c, $(FILES)) - : 1.c 2.c 3.c >> If the function application has a body, the body is passed (lazily) to the function as its first argument. [jyh: in revision 0.9.8 support is incomplete.] When using `osh', the application must be followed by a colon `:' to indicate that the application has a body. << # In its 3-argument form, the foreach function takes # a body, a variable, and an array. The body is evaluated # for each element of the array, with the variable bound to # the element value. # # The colon is required only for interactive sessions. osh> foreach(x, 1 2 3): add($x, 1) - : 2 3 4 >> Functions are defined in a similar form, where the parameter list is specified as a comma-separated list of identifiers, and the body of the function is indented. << osh> f(i, j) = add($i, $j) - : osh> f(3, 7) - : 10 : Int >> B.2.2.4 Objects ----------------- See the section on objects (Section 4.11*Note Section 4-11::). Objects are defined as an identifier with a terminal period. The body of the object is indented. << Obj. = class Obj X = 1 Y = $(sub $X, 12) new(i, j) = X = $i Y = $j value $(this) F() = add($X, $Y) println($Y) >> The body of the object has the usual form of an indented body, but new variable definitions are added to the object, not the global environment. The object definition above defines an object with (at least) the fields `X' and `Y', and methods `new' and `F'. The name of the object is defined with the `class' command as `Obj'. The `Obj' itself has fields `X = 1' and `Y = -11'. The `new' method has the typical form of a constructor-style method, where the fields of the object are initialized to new values, and the new object returned (`$(this)' refers to the current object). The `F' method returns the sum of the two fields `X' and `Y'. When used in an object definition, the += form adds the new definitions to an existing object. << pair. = x = 1 y = 2 pair. += y = $(add $y, 3) # pair now has fields (x = 1, and y = 5) >> The `extends' form specifies inheritance. Multiple inheritance is allowed. At evaluation time, the `extends' directive performs inclusion of the entire parent object. << pair. = x = 1 y = 2 depth. = z = 3 zoom(dz) = z = $(add $z, $(dz)) return $(this) triple. = extends $(pair) extends $(depth) crazy() = zoom($(mul $x, $y)) >> In this example, the `triple' object has three fields x, y, and z; and two methods `zoom' and `crazy'. B.2.2.5 Rules --------------- See the chapter on rules (Chapter 7*Note Chapter 7::). A rule has the following parts. 1. A sequence of targets; 2. one or two colons; 3. a sequence of dependencies and rule options; 4. and an indented body. The targets are the files to be built, and the dependencies are the files it depends on. If two colons are specified, it indicates that there may be multiple rules to build the given targets; otherwise only one rule is allowed. If the target contains a `%' character, the rule is called implicit, and is considered whenever a file matching that pattern is to be built. For example, the following rule specifies a default rule for compiling OCaml files. << %.cmo: %.ml %.mli $(OCAMLC) -c $< >> This rule would be consulted as a default way of building any file with a `.cmo' suffix. The dependencies list is also constructed based on the pattern match. For example, if this rule were used to build a file `foo.cmo', then the dependency list would be `foo.ml foo.mli'. There is also a three-part version of a rule, where the rule specification has three parts. << targets : pattern : dependencies rule-options indented-body >> In this case, the pattern must contain a single `%' character. However this is considered to be a sequence of explicit rules, where each target is matched against the pattern, and a new rule is computed based on the pattern match. For example, the following rule specifies how to build the explicit targets `a.cmo' and `b.cmo'. << a.cmo b.cmo: %.cmo: %.ml %.mli $(OCAMLC) -c $< >> This example is equivalent to the following two-rule sequence. << a.cmo: a.ml a.mli $(OCAMLC) -c $< b.cmo: b.ml b.mli $(OCAMLC) -c $< >> There are several special targets, including the following. - `.PHONY' : declare a "phony" target. That is, the target does not correspond to a file. - `.ORDER' : declare a rule for dependency ordering. - `.INCLUDE' : define a rule to generate a file for textual inclusion. - `.SUBDIRS' : specify subdirectories that are part of the project. - `.SCANNER' : define a rule for dependency scanning. There are several rule options. - `:optional: dependencies' the subsequent dependencies are optional, it is acceptable if they do not exist. - `:exists: dependencies' the subsequent dependencies must exist, but changes to not affect whether this rule is considered out-of-date. - `:effects: targets' the subsequent files are side-effects of the rule. That is, they may be created and/or modified while the rule is executing. Rules with overlapping side-effects are never executed in parallel. - `:scanner: name' the subsequent name is the name of the `.SCANNER' rule for the target to be built. - `:value: expr' the `expr' is a "value" dependency. The rule is considered out-of-date whenever the value of the `expr' changes. Several variables are defined during rule evaluation. - `$*' : the name of the target with the outermost suffix removed. - `$>' : the name of the target with all suffixes removed. - `$@' : the name of the target. - `$^' : the explicit file dependencies, sorted alphabetically, with duplicates removed. - `$+' : all explicit file dependencies, with order preserved. - `$<' : the first explicit file dependency. - `$&' : the free values of the rule (often used in `:value:' dependencies). B.2.2.6 Shell commands ------------------------ See the chapter on shell commands (Chapter 10*Note Chapter 10::). While it is possible to give a precise specification of shell commands, the informal description is simpler. Any non-empty statement where each prefix is not one of the other statements, is considered to be a shell command. Here are some examples. << ls -- shell command echo Hello world > /dev/null -- shell command echo(Hello world) -- function application echo(Hello world) > /dev/null -- syntax error echo Hello: world -- rule X=1 getenv X -- variable definition env X=1 getenv X -- shell command if true -- special form \if true -- shell command "if" true -- shell command >>  Node: Section B-3, Next: Appendix C, Prev: Section B-2, Up: Appendix B B.3 Dollar modifiers *=*=*=*=*=*=*=*=*=*=*= Inline applications have a function and zero-or-more arguments. Evaluation is normally strict: when an application is evaluated, the function identifier is evaluated to a function, the arguments are then evaluated and the function is called with the evaluated arguments. The additional "dollar" sequences specify additional control over evaluation. The token `$`' defines a "lazy" application, where evaluation is delayed until a value is required. The `$,' sequence performs an "eager" application within a lazy context. To illustrate, consider the expression `$(addsuffix .c, $(FILES))'. The `addsuffix' function appends its first argument to each value in its second argument. The following `osh' interaction demonstrates the normal bahavior. < FILES[] = a b c - : osh> X = $(addsuffix .c, $(FILES)) - : osh> FILES[] = 1 2 3 # redefine FILES - : osh> println($"$X") # force the evaluation and print a.c b.c c.c >> When the lazy operator `$`' is used instead, evaluation is delayed until it is printed. In the following sample, the value for `X' has changed to the `$(apply ..)' form, but otherwise the result is unchanged because it it printed immediately. < FILES[] = a b c - : osh> SUF = .c - : ".c" osh> X = $`(addsuffix $(SUF), $(FILES)) - : $(apply global.addsuffix ...) osh> println($"$X") # force the evaluation and print a.c b.c c.c >> However, consider what happens if we redefine the `FILES' variable after the definition for `X'. In the following sample, the result changes because evaluation occurs after the values for `FILES' has been redefined. < FILES[] = a b c - : osh> SUF = .c - : ".c" osh> X = $`(addsuffix $(SUF), $(FILES)) - : $(apply global.addsuffix ...) osh> SUF = .x osh> FILES[] = 1 2 3 osh> println($"$X") # force the evaluation and print 1.x 2.x 3.x >> In some cases, more explicit control is desired over evaluation. For example, we may wish to evaluate `SUF' early, but allow for changes to the `FILES' variable. The `$,(SUF)' expression forces early evaluation. < FILES[] = a b c - : osh> SUF = .c - : ".c" osh> X = $`(addsuffix $,(SUF), $(FILES)) - : $(apply global.addsuffix ...) osh> SUF = .x osh> FILES[] = 1 2 3 osh> println($"$X") # force the evaluation and print 1.c 2.c 3.c >>