Synopsis

Jump to: | ‍ ‍ | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: | ‍ ‍ | All • Variables • Functions • Objects • Targets • Options

# Appendix ‍A Synopsis

- General usage
- Output control
- Build options
- Additional options
- Environment variables
- Functions
- Option processing
- .omakerc

omake [-j <count>] [-k] [-p] [-P] [-n] [-s] [-S] [-w] [-t] [-u] [-U] [-R] [--verbose] [--project] [--depend] [--progress] [--print-status] [--print-exit] [--print-dependencies] [--show-dependencies <target>] [--all-dependencies] [--verbose-dependencies] [--force-dotomake] [--dotomake <dir>] [--flush-includes] [--configure] [--save-interval <seconds>] [--install] [--install-all] [--install-force] [--version] [--absname] [--output-normal] [--output-postpone] [--output-only-errors] [--output-at-end] filename... [var-definition...]

## 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

## A.2 Output control

### A.2.1-s

`-s`

Never not print commands as they are executed (be “silent”).

### A.2.2-S

`-S`

Do not print commands as they are executed unless they produce output and/or fail. This is the default.

### 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.

### 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.

### A.2.5--print-status

`--print-status`

Print status lines (the `+` and `-` lines).

### A.2.6--print-exit

`--print-exit`

Print termination codes when commands complete.

### A.2.7--verbose

`--verbose`

Make OMake very verbose. This option is equivalent to `--no-S --print-status --print-exit VERBOSE=true`

### 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.

### 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), 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) so that you can see when the build is active.

### 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.

### 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.

### 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 --no-progress`

  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`

## A.3 Build options

### 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.

### A.3.2-n

`-n`

This can be used to see what would happen if the project were to be built.

### 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.

### 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.

### 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).

### A.3.6-t

`-t`

Update the omake database to force the project to be considered up-to-date.

### A.3.7-U

`-U`

Do not trust cached build information. This will force the entire project to be rebuilt.

### A.3.8--depend

`--depend`

Do not trust cached dependency information. This will force files to be rescanned for dependency information.

### A.3.9--configure

`--configure`

Re-run `static.` sections of the included omake files, instead of trusting the cached results.

### A.3.10--force-dotomake

`--force-dotomake`

Always use the `$HOME/.omake` for the `.omc` cache files.

### A.3.11--dotomake

`--dotomake <dir>`

Use the specified directory instead of the `$HOME/.omake` for the placement of the `.omc` cache files.

### A.3.12-j

`-j <count>`

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.

### A.3.13--print-dependencies

`--print-dependencies`

Print dependency information for the targets on the command line.

### A.3.14--show-dependencies

`--show-dependencies <target>`

Print dependency information if the `target` is built.

### 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.

### 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.

### 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.

### 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.

### 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.

### A.3.20--absname

`--absname`

Filenames should expand to absolute pathnames.

N.B. This is an experimental option. It may become deprecated.

### A.3.21variable 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"`.

## 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.

## A.5 Environment variables

### A.5.1OMAKEFLAGS

If defines, the `OMAKEFLAGS` should specify a set of options exactly as they are specified on the command line.

### A.5.2OMAKELIB

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.

## A.6 Functions

### A.6.1OMakeFlags

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

## 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.

## 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)

Jump to: | ‍ ‍ | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: | ‍ ‍ | All • Variables • Functions • Objects • Targets • Options