Provided by: omake_0.10.6-1_amd64 bug

NAME

       omake, osh - make-like build utility and its shell

SYNOPSIS

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

DESCRIPTION

       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.

   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.

   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.

       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.

       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.

   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
                  Save the build DB (.omakedb) every DURATION seconds (0 disables, default: 60).

   Shell Related
           -c COMMAND
                  Execute COMMAND.

           -i     Treat the session as interactive.  ⟨N⟩

           --shell
                  Run the OMake shell: osh.  ⟨N⟩

   Debugging
           -allow-exceptions
                  Do  not  catch  top-level  exceptions.   This  option is useful if running with
                  OCAMLRUNPARAM=b.  ⟨N⟩

           -debug-active-rules
                  Debug active rules.  ⟨N⟩

           -debug-ast-lex
                  Print tokens as they are scanned.  ⟨N⟩

           -debug-build
                  Display debugging information during the build.  ⟨N⟩

           -debug-cache
                  Display cache debugging information.  ⟨N⟩

           -debug-db
                  Debug the file database.  ⟨N⟩

           -debug-deps
                  Display dependency information as scanned.  ⟨N⟩

           -debug-eval
                  Debug the evaluator.  ⟨N⟩

           -debug-exec
                  Display execution debugging information.  ⟨N⟩

           -debug-hash
                  Show Lm_hash statistics.  ⟨N⟩

           -debug-implicit
                  Display debugging information for implicit rule selection.  ⟨N⟩

           -debug-lex
                  Debug the lexer.  ⟨N⟩

           -debug-lexgen
                  Debug the lexer generator.  ⟨N⟩

           -debug-notify
                  Debug the FAM (-p filesystem watch) operations.  ⟨N⟩

           -debug-parse
                  Debug the parser.  ⟨N⟩

           -debug-parsegen
                  Debug the parser generator.  ⟨N⟩

           -debug-parsing
                  Debug OMake parsing operations.  ⟨N⟩

           -debug-pos
                  Print source position information on error.  ⟨N⟩

           -debug-remote
                  Debug remote execution.  ⟨N⟩

           -debug-rule
                  Display debugging information about rule execution.  ⟨N⟩

           -debug-scanner
                  Display debugging information for scanner selection.  ⟨N⟩

           -debug-shell
                  Debug shell operations.  ⟨N⟩

           -debug-thread
                  Show thread operations.  ⟨N⟩

           -extended-rusage
                  Print more about resource usage.  ⟨N⟩

           -instrument
                  Do instrument functions.  ⟨N⟩

           -print-ast
                  Print the AST after parsing.  ⟨N⟩

           -print-files
                  Print the files as they are read.  ⟨N⟩

           -print-ir
                  Print the IR.  ⟨N⟩

           -print-loc
                  Also print locations.  ⟨N⟩

           -trace-pos
                  Trace the program execution.  ⟨N⟩

           -print-rules
                  Print the rules after evaluation.  ⟨N⟩

   Miscellaneous
           --install
                  Install default files OMakefile and OMakeroot of  an  OMake  project  into  the
                  current  directory.  This is typically done only once to start an OMake project
                  in the current directory.  ⟨N⟩

           --install-all
                  In addition to installing the default files OMakefile and OMakeroot of an OMake
                  project  into  the  current  directory  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.  ⟨N⟩

           --install-force
                  Normally, OMake will prompt before it overwrites any  existing  OMakefile.   If
                  this  option  is  given,  all  files are overwritten without prompting; implies
                  --install.  ⟨N⟩

           --help Display help message and exit.

           --help-all
                  Display help message for all options and exit.

           --help-debug
                  Display help message just for the debugging-related options and exit.

           --server SERVER-NAME
                  Run as a remote server called SERVER-NAME.

           --version
                  Print the version string and the default library directory then exit.

EXIT STATUS

       0   No problems; everything went well.

       1   Build failure caused by a program with non-zero exit code.

       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.

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

                                            2021-11-17                                   OMAKE(1)