1OMAKE(1) General Commands Manual OMAKE(1)
2
6 omake, osh - make-like build utility and its shell
7
9 omake [OPTION...] [TARGET...]
10 osh [OPTION...]
11
13 OMake constructs projects in a way similar to make(1) in particular
14 GNU-Make. When OMake needs to spawn a shell it uses its own shell,
15 Osh. The shell can also be used standalone either as omake --shell or
16 as osh(1) if the appropriate link has been installed.
17 OMake
19 OMake is designed for building projects that have source files in sev‐
20 eral directories. Projects are normally specified using an OMakefile
21 in each of the project directories, and an OMakeroot file in the root
22 directory of the project. The OMakeroot file specifies general build
23 rules, and the OMakefiles specify the build parameters specific to each
24 of the subdirectories. When OMake runs, it walks the configuration
25 tree, evaluating rules from all of the OMakefiles. The project is then
26 built from the entire collection of build rules.
27 Osh
29 OMake also includes the standalone command-line interpreter osh that
30 can be used as an interactive shell. This shell uses the same syntax,
31 and provides the same features on all platforms that OMake supports,
32 including Win32.
33 See also the OMake Manual, chapters 11, “Shell commands” and 15, “The
35 Osh shell”.
36
38 The options are presented in functionally related sections. Within
39 these the options are sorted alphabetically in case-insensitive order.
40 Options marked with ‘⟨N⟩’ can be negated by prefixing them with ‘--no’
42 as, e.g., --no-S or --no--print-status. Note the conserved inner dou‐
43 ble dash of the latter, though.
44 Build Control
46 --absname
47 Enforce that filenames always expand to their absolute path‐
48 names. ⟨N⟩
49 Note: This is an experimental option. It may become depre‐
51 cated.
52 --all-dependencies
54 If the options --print-dependencies or --show-dependencies
55 are given print transitive dependencies. This means that
56 all dependencies will be printed recursively. Otherwise no
57 effect. ⟨N⟩
58 --configure
60 Recompute static. sections of the included omake files, in‐
61 stead of trusting the cached results. ⟨N⟩
62 --depend
64 Do not trust the cached dependency information. This will
65 force files to be rescanned for dependency information. ⟨N⟩
66 --flush-includes
68 Do not trust cached *.omc files. ⟨N⟩
69 -j JOB-SPEC
71 JOB-SPEC is either the maximum number of jobs to run in par‐
72 allel.
73 Or, JOB-SPEC specifies servers for remote execution of com‐
75 mands in the form of a colon separated list of SERVER-
76 NAME=NUMBER-OF-JOBS pairs. For example, the option
77 -j 2:small.host.org=1:large.host.org=4
79 would specify that up to 2 jobs can be executed locally, 1
81 on the server small.host.org and 4 on large.host.org. Each
82 remote server must use the same filesystem location for the
83 project.
84 Remote execution is currently an experimental feature. Re‐
86 mote filesystems like NFS do not provide adequate file con‐
87 sistency for this to work.
88 -k Do not stop when an error occurs; continue to build as much
90 of the project as possible. This option is implied by -p
91 and -P. ⟨N⟩
92 Mnemonic: “keep on making”.
94 -n Print commands, but do not execute them. ⟨N⟩
96 Mnemonic: “no operation”.
98 -P Keep on polling the filesystem for changes “forever”; im‐
100 plies -k and -p. ⟨N⟩
101 -p Watch the filesystem for changes, and continue the build un‐
103 til it succeeds. If this option is specified, OMake will
104 restart the build whenever source files are modified. This
105 option implies -k. ⟨N⟩
106 Mnemonic: “poll filesystem”.
108 --print-dependencies
110 Collect and print dependency information for the TARGETs on
111 the command line. ⟨N⟩
112 --project
114 Ignore the current directory and build the project. ⟨N⟩
115 -R Ignore the current directory and build the project from its
117 root directory. When OMake is run in a subdirectory of a
118 project and no explicit targets are given on the command
119 line, it would normally only build files within the current
120 directory and its subdirectories. More precisely: it builds
121 all the .DEFAULT targets in the current directory and its
122 subdirectories. If the -R option is specified, the build is
123 performed as if OMake were run in the project root.
124 In other words, with the -R option all the relative targets
126 specified on the command line will be taken relative to the
127 project root instead of relative to the current directory.
128 When no targets are given on the command line, all the .DE‐
129 FAULT targets in the project will be built regardless of the
130 current directory. ⟨N⟩
131 Mnemonic: “root build”.
133 --show-dependencies TARGET
135 Show dependencies (only) if TARGET is built.
136 -t Update the OMake database to force all target files of the
138 project are considered up-to-date. ⟨N⟩
139 -U Do not trust the dependency cache or cached OMakefiles.
141 This will force the entire project to be rebuilt. ⟨N⟩
142 --verbose-dependencies
144 If either one of the options --print-dependencies or
145 --show-dependencies is in effect, print transitive dependen‐
146 cies. That is, print all dependencies recursively. If nei‐
147 ther of the above options is specified, this option has no
148 effect. ⟨N⟩
149 -warn-error
151 Treat warnings as errors. ⟨N⟩
152 -Wdeclare
154 Warn about undeclared variables. ⟨N⟩
155 Output
157 -o SHORT-OPTION...
158 Short output options alias the functionality of some options
159 or combinations thereof. In general, an uppercase character
160 turns the option on, whereas a lowercase character turns the
161 option off. SHORT-OPTION is one of following letters.
162 0 Equivalent to
164 -s --output-only-errors --no-progress
166 This option specifies that omake should be as quiet as
168 possible. If any errors occur during the build, the
169 output is delayed until the build terminates. Output
170 from successful commands is discarded.
171 1 Equivalent to
173 -S --progress --output-only-errors
175 This is a slightly more relaxed version of “quiet” out‐
177 put. The output from successful commands is discarded.
178 The output from failed commands is printed immediately
179 after the command complete. The output from failed com‐
180 mands is displayed twice: once immediately after the
181 command completes, and again when the build completes.
182 A progress bar is displayed so that you know when the
183 build is active. Include the -p option if you want to
184 turn off the progress bar (for example omake -o 1p).
185 2 Equivalent to
187 --progress --output-postpone
189 The is even more relaxed, output from successful com‐
191 mands is printed. This is often useful for deinterleav‐
192 ing the output when using option -j.
193 P (uppercase)
195 Equivalent to --progress.
196 p (lowercase)
198 Equivalent to --no--progress.
199 S (uppercase)
201 Equivalent to -S.
202 s (lowercase)
204 Equivalent to --no-S.
205 W (uppercase)
207 Equivalent to -w.
208 w (lowercase)
210 Equivalent to --no-w.
211 X (uppercase)
213 Equivalent to --print-exit.
214 x (lowercase)
216 Equivalent to --no-print-exit.
217 --output-at-end
219 The output of the failed commands will be printed after
220 OMake has finished. Off by default, unless -k is enabled
221 (directly or via -p/-P). ⟨N⟩
222 --output-normal
224 Relay the output of the rule commands to the OMake output
225 right away. This is the default when no --output-postpone
226 and no --output-only-errors flags are given. ⟨N⟩
227 --output-only-errors
229 Same as --output-postpone, but postponed output will only be
230 printed for commands that fail.
231 This can be useful in reducing unwanted output so that the
233 user can concentrate on any errors. ⟨N⟩
234 --output-postpone
236 Postpone printing command output until a rule terminates.
237 Then print it as a single block.
238 This is useful in combination with the -j option, where the
240 output of multiple subprocesses can be garbled. The diver‐
241 sion is printed as a single coherent unit. ⟨N⟩
242 --print-exit
244 Print the exit codes of all commands that have been run.
245 ⟨N⟩
246 --print-status
248 Print status lines (starting with ‘+’ or ‘-’). This is the
249 default setting. ⟨N⟩
250 --progress
252 Print a progress indicator; enabled by default if stdout is
253 a terminal and disabled if the output has been redirected.
254 ⟨N⟩
255 -S Do not print commands as they are executed unless they pro‐
257 duce any output or they fail. This is the default. ⟨N⟩
258 -s Never print commands before they are executed. ⟨N⟩
260 Mnemonic: “silent”.
262 --verbose
264 Switch on very verbose output. This option is equivalent to
265 --no-S --print-status --print-exit VERBOSE=true
267 -w Print the directory in “make format” as commands are exe‐
269 cuted. This is mainly useful for editors that expect make-
270 style directory information for determining the location of
271 errors. ⟨N⟩
272 Cache Management
274 --force-dotomake
275 Always use the directory $HOME/.omake for *.omc-cache files.
276 ⟨N⟩
277 --dotomake DIRECTORY
279 Use the specified DIRECTORY in place of $HOME/.omake for the
280 storage of *.omc-files.
281 --save-interval DURATION
283 Save the build DB (.omakedb) every DURATION seconds (0 dis‐
284 ables, default: 60).
285 Shell Related
287 -c COMMAND
288 Execute COMMAND.
289 -i Treat the session as interactive. ⟨N⟩
291 --shell
293 Run the OMake shell: osh. ⟨N⟩
294 Debugging
296 -allow-exceptions
297 Do not catch top-level exceptions. This option is useful if
298 running with OCAMLRUNPARAM=b. ⟨N⟩
299 -debug-active-rules
301 Debug active rules. ⟨N⟩
302 -debug-ast-lex
304 Print tokens as they are scanned. ⟨N⟩
305 -debug-build
307 Display debugging information during the build. ⟨N⟩
308 -debug-cache
310 Display cache debugging information. ⟨N⟩
311 -debug-db
313 Debug the file database. ⟨N⟩
314 -debug-deps
316 Display dependency information as scanned. ⟨N⟩
317 -debug-eval
319 Debug the evaluator. ⟨N⟩
320 -debug-exec
322 Display execution debugging information. ⟨N⟩
323 -debug-hash
325 Show Lm_hash statistics. ⟨N⟩
326 -debug-implicit
328 Display debugging information for implicit rule selection.
329 ⟨N⟩
330 -debug-lex
332 Debug the lexer. ⟨N⟩
333 -debug-lexgen
335 Debug the lexer generator. ⟨N⟩
336 -debug-notify
338 Debug the FAM (-p filesystem watch) operations. ⟨N⟩
339 -debug-parse
341 Debug the parser. ⟨N⟩
342 -debug-parsegen
344 Debug the parser generator. ⟨N⟩
345 -debug-parsing
347 Debug OMake parsing operations. ⟨N⟩
348 -debug-pos
350 Print source position information on error. ⟨N⟩
351 -debug-remote
353 Debug remote execution. ⟨N⟩
354 -debug-rule
356 Display debugging information about rule execution. ⟨N⟩
357 -debug-scanner
359 Display debugging information for scanner selection. ⟨N⟩
360 -debug-shell
362 Debug shell operations. ⟨N⟩
363 -debug-thread
365 Show thread operations. ⟨N⟩
366 -extended-rusage
368 Print more about resource usage. ⟨N⟩
369 -instrument
371 Do instrument functions. ⟨N⟩
372 -print-ast
374 Print the AST after parsing. ⟨N⟩
375 -print-files
377 Print the files as they are read. ⟨N⟩
378 -print-ir
380 Print the IR. ⟨N⟩
381 -print-loc
383 Also print locations. ⟨N⟩
384 -trace-pos
386 Trace the program execution. ⟨N⟩
387 -print-rules
389 Print the rules after evaluation. ⟨N⟩
390 Miscellaneous
392 --install
393 Install default files OMakefile and OMakeroot of an OMake
394 project into the current directory. This is typically done
395 only once to start an OMake project in the current direc‐
396 tory. ⟨N⟩
397 --install-all
399 In addition to installing the default files OMakefile and
400 OMakeroot of an OMake project into the current directory in‐
401 stall default OMakefiles into each subdirectory of the cur‐
402 rent directory. cvs(1) rules are used for filtering the
403 subdirectory list. For example, OMakefiles are not copied
404 into directories called CVS, RCCS, etc. ⟨N⟩
405 --install-force
407 Normally, OMake will prompt before it overwrites any exist‐
408 ing OMakefile. If this option is given, all files are over‐
409 written without prompting; implies --install. ⟨N⟩
410 --help Display help message and exit.
412 --help-all
414 Display help message for all options and exit.
415 --help-debug
417 Display help message just for the debugging-related options
418 and exit.
419 --server SERVER-NAME
421 Run as a remote server called SERVER-NAME.
422 --version
424 Print the version string and the default library directory
425 then exit.
426
428 0 No problems; everything went well.
429 1 Build failure caused by a program with non-zero exit code.
431 2 Not a build-related error, for example a syntax error in one of the
433 files that constitute the OMake project.
434 3 Bogus command-line option.
436
438 OMAKEFLAGS
439 If defined, OMAKEFLAGS should contain a set of options exactly
440 as they are specified on the command line.
441 OMAKELIB
443 If defined, OMAKELIB refers to the installed location of the
444 OMake standard library. This is the directory that contains
445 Pervasives.om etc. On a Unix system, this is often
446 /usr/lib/omake or /usr/local/lib/omake, and on Win32 systems it
447 is often c:\Program Files\OMake\lib.
448 If not defined, OMake uses the default configured location,
450 which can be inquired with option --version.
451 Normally, this variable should not be set.
453
455 OMakeroot
456 This file is required; it serves to identify the project root,
457 and it contains code that sets up the project.
458 OMakefile
460 Any project-specific configuration lives in the OMakefiles.
461 .om Conventional filename extension for OMake “library” files.
463 .omc For performance OMake compiles all OMake-source files on the
465 fly. Compiled OMake files receive extension .omc.
466
468 OMake
469 • This is an almost minimal OMakeroot file.
470 ## Setup for building a C- or C++-project.
471 open build/C
472 ## Define according our configuration.
474 DefineCommandVars()
475 ## Include the OMakefile in this directory.
477 .SUBDIRS: .
478 • Small OMakefile file to build the famous “Hello, world!” example.
480 ## Define target-source relationship of a C-program.
481 CProgram(hello, hello) # we can be extension agnostic
482 ## Define the default (and only) target.
484 .DEFAULT: hello$(EXE)
485 Osh
487 • Call date(1) with some options via OMake.
488 $ omake --shell -c 'date --universal --iso-8601=seconds'
489 2021-11-20T14:52:10+00:00
490 • Call update(1) via Osh.
492 $ osh -c uptime
493 15:54:03 up 6:41, 1 user, load average: 0.02, 0.04, 0.11
494 • Interactive use.
496 $ osh
497 % uname --kernel-release --kernel-version
498 5.10.0-9-amd64 #1 SMP Debian 5.10.70-1 (2021-09-30)
499 % ^D
500 $
501
503 make(1), sh(1).
504 2021-11-17 OMAKE(1)