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

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.1  OMAKEFLAGS

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

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.

A.6  Functions

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

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)