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
-s
Never not print commands as they are executed (be “silent”).
-S
Do not print commands as they are executed unless they produce output and/or
fail. This is the default.
-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.
--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.
--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.
-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
A.3 Build options
-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.
-n
This can be used to see what would happen if the project were to be built.
-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.
-P
Watch the filesystem for changes forever. If this option is specified, omake
will restart the build whenever source files are modified. Implies
-k.
-R
Ignore the current directory and build the project from its root directory. When
omake is run in a subdirectory of a project, it normally builds files within 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.
-t
Update the omake database to force the project to be considered up-to-date.
-U
Do not trust cached build information. This will force the entire project to be rebuilt.
--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.
--dotomake <dir>
Use the specified directory instead of the $HOME/.omake
for the placement of the .omc cache files.
-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.
--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.
--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.
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.
-
All options specified by the
OMAKEFLAGS environment variable are defined globally.
- All options from the command line are defined globally.
- 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)