OMAKE(1)

💖 OMAKE(1) — General Commands Manual 💖

✨ NAME ✨

omake, osh — make-like build utility and its shell. No cap, that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

omake [OPTION...] [TARGET...]
osh [OPTION...]

🦋 DESCRIPTION 🦋

okay so OMake constructs projects in a way similar to make(1), in particular GNU-Make. When OMake needs to spawn a shell it uses its own shell, Osh. The shell can also be used standalone either as omake --shell or as osh(1) if the appropriate link has been installed. Periodt.

💅 OMake 💅

OMake is designed for building projects that have source files in several directories. Projects are normally specified using an OMakefile in each of the project directories, and an OMakeroot file in the root directory of the project. The OMakeroot file specifies general build rules, and the OMakefiles specify the build parameters specific to each of the subdirectories. When OMake runs, it walks the configuration tree, evaluating rules from all of the OMakefiles. The project is then built from the entire collection of build rules. It's giving organized. 🔥

🐚 Osh 🐚

OMake also includes the standalone command-line interpreter osh that can be used as an interactive shell. This shell uses the same syntax, and provides the same features on all platforms that OMake supports, including Win32. Iconic.

See also the OMake Manual, chapters 11, “Shell commands” and 15, “The Osh shell”.

✨ OPTIONS ✨

The options are presented in functionally related sections. Within these the options are sorted alphabetically in case-insensitive order. Bestie, keep that in mind. 🫶

Options marked with ‘⟨N⟩’ can be negated by prefixing them with ‘--no’ as, e.g., --no-S or --no--print-status. Note the conserved inner double dash of the latter, though. Not me pointing out the double dash, but it's literally there. 💀

---

🔨 Build Control 🔨

• --absname — Enforce that filenames always expand to their absolute pathnames. ⟨N⟩

Note: This is an experimental option. It may become deprecated.

• --all-dependencies — If the options --print-dependencies or --show-dependencies are given, print transitive dependencies. This means that all dependencies will be printed recursively. Otherwise no effect. ⟨N⟩
• --configure — Recompute static. sections of the included omake files, instead of trusting the cached results. ⟨N⟩
• --depend — Do not trust the cached dependency information. This will force files to be rescanned for dependency information. ⟨N⟩
• --flush-includes — Do not trust cached *.omc files. ⟨N⟩
• -j JOB-SPEC — JOB-SPEC is either the maximum number of jobs to run in parallel.

Or, JOB-SPEC specifies servers for remote execution of commands in the form of a colon separated list of SERVER-NAME=NUMBER-OF-JOBS pairs. 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.

• -k — Do not stop when an error occurs; continue to build as much of the project as possible. This option is implied by -p and -P. ⟨N⟩

Mnemonic: “keep on making”.

• -n — Print commands, but do not execute them. ⟨N⟩

Mnemonic: “no operation”.

• -P — Keep on polling the filesystem for changes “forever”; implies -k and -p. ⟨N⟩
• -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. This option implies -k. ⟨N⟩

Mnemonic: “poll filesystem”.

• --print-dependencies — Collect and print dependency information for the TARGETs on the command line. ⟨N⟩
• --project — Ignore the current directory and build the project. ⟨N⟩
• -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. ⟨N⟩

Mnemonic: “root build”.

• --show-dependencies TARGET — Show dependencies (only) if TARGET is built.
• -t — Update the OMake database to force all target files of the project are considered up-to-date. ⟨N⟩
• -U — Do not trust the dependency cache or cached OMakefiles. This will force the entire project to be rebuilt. ⟨N⟩
• --verbose-dependencies — If either one of the options --print-dependencies or --show-dependencies is in effect, print transitive dependencies. That is, print all dependencies recursively. If neither of the above options is specified, this option has no effect. ⟨N⟩
• -warn-error — Treat warnings as errors. ⟨N⟩
• -Wdeclare — Warn about undeclared variables. ⟨N⟩

---

🎀 Output 🎀

• -o SHORT-OPTION... — Short output options alias the functionality of some options or combinations thereof. In general, an uppercase character turns the option on, whereas a lowercase character turns the option off. SHORT-OPTION is one of following letters.
  • 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 option -j.

• P (uppercase) — Equivalent to --progress.
• p (lowercase) — Equivalent to --no--progress.
• S (uppercase) — Equivalent to -S.
• s (lowercase) — Equivalent to --no-S.
• W (uppercase) — Equivalent to -w.
• w (lowercase) — Equivalent to --no-w.
• X (uppercase) — Equivalent to --print-exit.
• x (lowercase) — Equivalent to --no-print-exit.

• --output-at-end — The output of the failed commands will be printed after OMake has finished. Off by default, unless -k is enabled (directly or via -p/-P). ⟨N⟩
• --output-normal — Relay the output of the rule commands to the OMake output right away. This is the default when no --output-postpone and no --output-only-errors flags are given. ⟨N⟩
• --output-only-errors — Same as --output-postpone, but postponed output will only be printed for commands that fail.

This can be useful in reducing unwanted output so that the user can concentrate on any errors. ⟨N⟩

• --output-postpone — Postpone printing command output until a rule terminates. Then print it as a single block.

This is useful in combination with the -j option, where the output of multiple subprocesses can be garbled. The diversion is printed as a single coherent unit. ⟨N⟩

• --print-exit — Print the exit codes of all commands that have been run. ⟨N⟩
• --print-status — Print status lines (starting with ‘+’ or ‘-’). This is the default setting. ⟨N⟩
• --progress — Print a progress indicator; enabled by default if stdout is a terminal and disabled if the output has been redirected. ⟨N⟩
• -S — Do not print commands as they are executed unless they produce any output or they fail. This is the default. ⟨N⟩
• -s — Never print commands before they are executed. ⟨N⟩

Mnemonic: “silent”.

• --verbose — Switch on very verbose output. This option is equivalent to

--no-S --print-status --print-exit VERBOSE=true

• -w — Print the directory 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. ⟨N⟩

---

🗂️ Cache Management 🗂️

• --force-dotomake — Always use the directory $HOME/.omake for *.omc-cache files. ⟨N⟩
• --dotomake DIRECTORY — Use the specified DIRECTORY in place of $HOME/.omake for the storage of *.omc-files.
• --save-interval DURATION — saves the build DB (.omakedb) every DURATION seconds (0 disables it, default: 60). ✨

Shell Related

• -c COMMAND — executes COMMAND. ⟨N⟩
• -i — treats the session as interactive. ⟨N⟩
• --shell — runs the OMake shell: osh. ⟨N⟩

---

Debugging

• -allow-exceptions — does not catch top-level exceptions. This one's useful if you're running with OCAMLRUNPARAM=b. ⟨N⟩
• -debug-active-rules — debugs active rules. ⟨N⟩
• -debug-ast-lex — prints tokens as they're scanned. ⟨N⟩
• -debug-build — shows debugging info during the build. ⟨N⟩
• -debug-cache — shows cache debugging info. ⟨N⟩
• -debug-db — debugs the file database. ⟨N⟩
• -debug-deps — shows dependency info as it's scanned. ⟨N⟩
• -debug-eval — debugs the evaluator. ⟨N⟩
• -debug-exec — shows execution debugging info. ⟨N⟩
• -debug-hash — shows Lm_hash statistics. ⟨N⟩
• -debug-implicit — shows debugging info for implicit rule selection. ⟨N⟩
• -debug-lex — debugs the lexer. ⟨N⟩
• -debug-lexgen — debugs the lexer generator. ⟨N⟩
• -debug-notify — debugs the FAM (-p filesystem watch) operations. ⟨N⟩
• -debug-parse — debugs the parser. ⟨N⟩
• -debug-parsegen — debugs the parser generator. ⟨N⟩
• -debug-parsing — debugs OMake parsing operations. ⟨N⟩
• -debug-pos — prints source position info on error. ⟨N⟩
• -debug-remote — debugs remote execution. ⟨N⟩
• -debug-rule — shows debugging info about rule execution. ⟨N⟩
• -debug-scanner — shows debugging info for scanner selection. ⟨N⟩
• -debug-shell — debugs shell operations. ⟨N⟩
• -debug-thread — shows thread operations. ⟨N⟩
• -extended-rusage — prints more about resource usage. ⟨N⟩
• -instrument — does instrument functions. ⟨N⟩
• -print-ast — prints the AST after parsing. ⟨N⟩
• -print-files — prints the files as they're read. ⟨N⟩
• -print-ir — prints the IR. ⟨N⟩
• -print-loc — also prints locations. ⟨N⟩
• -trace-pos — traces the program execution. ⟨N⟩
• -print-rules — prints the rules after evaluation. ⟨N⟩

---

Miscellaneous

• --install — installs the default files OMakefile and OMakeroot of an OMake project into the current directory. This is usually done just once to start an OMake project here. ⟨N⟩
• --install-all — in addition to installing the default OMakefile and OMakeroot files into the current directory, it installs 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. ⟨N⟩
• --install-force — normally OMake prompts before overwriting any existing OMakefile. With this option, all files get overwritten with no prompting; implies --install. ⟨N⟩
• --help — displays the help message and exits.
• --help-all — displays the help message for all options and exits.
• --help-debug — displays the help message just for the debugging-related options and exits.
• --server SERVER-NAME — runs as a remote server called SERVER-NAME.
• --version — prints the version string and the default library directory, then exits.

---

✨ EXIT STATUS ✨

• 0 — no problems; everything went well. slay
• 1 — build failure caused by a program with non-zero exit code. oof
• 2 — not a build-related error, for example a syntax error in one of the files that constitute the OMake project.
• 3 — bogus command-line option.

---

🌸 ENVIRONMENT 🌸

• OMAKEFLAGS — if defined, OMAKEFLAGS should contain a set of options exactly as they are specified on the command line.
• OMAKELIB — if defined, OMAKELIB refers 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, which can be inquired with option --version.

Normally, this variable should not be set.

bestie, don't set OMAKELIB unless you really know what you're doing — it literally says normally it should not be set. 💅

---

🎀 FILES 🎀

• OMakeroot — this file is required; it serves to identify the project root, and it contains code that sets up the project.
• OMakefile — any project-specific configuration lives in the OMakefiles.
• .om — conventional filename extension for OMake “library” files.
• .omc — for performance OMake compiles all OMake-source files on the fly. Compiled OMake files receive extension .omc.

---

🦋 EXAMPLES 🦋

OMake

• This is an almost minimal OMakeroot file.

##  Setup for building a C- or C++-project.
open build/C

##  Define according our configuration.
DefineCommandVars()

##  Include the OMakefile in this directory.
.SUBDIRS: .

• Small OMakefile file to build the famous “Hello, world!” example.

##  Define target-source relationship of a C-program.
CProgram(hello, hello) # we can be extension agnostic

##  Define the default (and only) target.
.DEFAULT: hello$(EXE)

Osh

• Call date(1) with some options via OMake.

$ omake --shell -c 'date --universal --iso-8601=seconds'
2021-11-20T14:52:10+00:00

• Call update(1) via Osh.

$ osh -c uptime
 15:54:03 up  6:41,  1 user,  load average: 0.02, 0.04, 0.11

• Interactive use.

$ osh
% uname --kernel-release --kernel-version
5.10.0-9-amd64 #1 SMP Debian 5.10.70-1 (2021-09-30)
% ^D
$

---

👑 SEE ALSO 👑

• make(1), sh(1).

---

That's the whole vibe, bestie! This page is from the OMake(1) manual, dated 2021-11-17. Now go build something iconic. 💖✨