Build functions and utilities

Jump to: | ‍ ‍ | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: | ‍ ‍ | All • Variables • Functions • Objects • Targets • Options

# Chapter ‍13 Build functions and utilities

- Builtin .PHONY targets
- Options and versioning
- Examining the dependency graph
- The OMakeroot file
- Building C and C++ code
- Building OCaml code
- Building LATEX files

## 13.1 Builtin .PHONY targets

The complete set of builtin `.PHONY` targets include the following.

.PHONY
  Declares new phony targets (Section ‍8.10).
.DEFAULT
  Declare the default build targets (Section ‍8.7).
.SUBDIRS
  Include a directory as part of the project (Section ‍8.8).
.SCANNER
  Define a dependency scanner (Section ‍8.8).
.INCLUDE
  Include a file (Section ‍8.9).
.ORDER
  Define a file-dependency ordering rule (Section ‍10.3.6).
.BUILD_BEGIN
  Commands to be executed at the beginning of a build.
.BUILD_SUCCESS
  Commands to be executed if the build is successful.
.BUILD_FAILURE
  Commands to be executed if the build fails.

The `.BUILD` targets can be used to specify commands to be executed at the beginning and end of the build. The `.BUILD_BEGIN` target is built at the beginning of a project build, and one of `.BUILD_FAILURE` or `.BUILD_SUCCESS` is executed when the build terminates.

For example, the following set of rules simply print additional messages about the status of the build.

       .BUILD_BEGIN:
           echo Build starting

       .BUILD_SUCCESS:
           echo The build was successful

       .BUILD_FAILURE:
           println($"The build failed: $(length $(find-build-targets Failed)) targets could not be built")

Another common use is to define notifications to be performed when the build completes. For example, the following rule will create a new X terminal displaying the summary of the build (using the `BUILD_SUMMARY` variable).

        .BUILD_FAILURE:
            xterm -e vi $(BUILD_SUMMARY)

If you do not wish to add these rules directly to your project (which is probably a good idea if you work with others), you can define them in your `.omakerc` (see Section ‍A.8).

The `find-build-targets` function is useful for obtaining a firther summary of the build. Note that when output diversions are in effect (with the `--output-*` options — see Chapter ‍A), any output produced by the commands is copied to a file. The name of the file is specified by the `output-file` field of the `Target` object. You may find this useful in defining custom build summaries.

## 13.2 Options and versioning

### 13.2.1 OMakeFlags

       OMakeFlags(options)
          options : String

The `OMakeFlags` function is used to set `omake` options from within OMakefiles. The options have exactly the same format as options on the command line.

For example, the following code displays the progress bar unless the `VERBOSE` environment variable is defined.

        if $(not $(defined-env VERBOSE))
            OMakeFlags(-S --progress)
            export

### 13.2.2 OMakeVersion

       OMakeVersion(version1)
       OMakeVersion(version1, version2)
          version1, version2 : String

The `OMakeVersion` function is used for version checking in OMakefiles. It takes one or two arguments.

In the one argument form, if the omake version number is less than `<version1>`, then an exception is raised. In the two argument form, the version must lie between `version1` and `version2`.

### 13.2.3 cmp-versions

       $(cmp-versions version1, version2)
          version1, version2 : String

The `cmp-versions\` functions can be used to compare arbitrary version strings. It returns 0 when the two version strings are equal, a negative number when the first string represents an earlier version, and a positive number otherwise.

### 13.2.4 DefineCommandVars

       DefineCommandVars()

The `DefineCommandVars` function redefines the variables passed on the commandline. Variables definitions are passed on the command line in the form `name=value`. This function is primarily for internal use by omake to define these variables for the first time.

## 13.3 Examining the dependency graph

### 13.3.1 dependencies, dependencies-all, dependencies-proper

       $(dependencies targets) : File Array
       $(dependencies-all targets) : File Array
       $(dependencies-proper targets) : File Array
          targets : File Array
       raises RuntimeException

The `dependencies` function returns the set of immediate dependencies of the given targets. This function can only be used within a rule body and all the arguments to the `dependency` function must also be dependencies of this rule. This restriction ensures that all the dependencies are known when this function is executed.

The `dependencies-all` function is similar, but it expands the dependencies recursively, returning all of the dependencies of a target, not just the immediate ones.

The `dependencies-proper` function returns all recursive dependencies, except the dependencies that are leaf targets. A leaf target is a target that has no dependencies and no build commands; a leaf target corresponds to a source file in the current project.

In all three functions, files that are not part of the current project are silently discarded. All three functions will return phony and scanner targets along with the “real” ones.

One purpose of the `dependencies-proper` function is for “clean” targets. For example, one way to delete all intermediate files in a build is with a rule that uses the `dependencies-proper`. Note however, that the rule requires building the project before it can be deleted.

        .PHONY: clean

        APP = ...     # the name of the target application
        clean: $(APP)
           rm -f $(dependencies-proper $(APP))

Also note that the `dependencies-proper` function will return the phony and scanner targets in addition to real one.

For other (possibly better) alternatives, see Section ‍10.3.3 and `filter-proper-targets` function.

### 13.3.2 target

       $(target targets) : Target Array
          targets : File Sequence
       raises RuntimeException

The `target` function returns the Target object associated with each of the targets. See the `Target` object for more information.

### 13.3.3 find-build-targets

        $(find-build-targets tag) : Target Array
           tag : Succeeded | Failed

The `find-build-targets` allow the results of the build to be examined. The `tag` must specifies which targets are to be returned; the comparison is case-insensitive.

Succeeded
  The list of targets that were built successfully.
Failed
  The list of targets that could not be built.

These are used mainly in conjuction with the `.BUILD_SUCCESS` (Section ‍13.1) and `.BUILD_FAILURE` (Section ‍13.1) phony targets. For example, adding the following to your project `OMakefile` will print the number of targets that failed (if the build failed).

        .BUILD_FAILURE:
            echo "Failed target count: $(length $(find-build-targets Failed))"

### 13.3.4 project-directories

       $(project-directories) : Dir Array

The `project-directories` function returns the list of all directories that are considered to be part of the project.

To get the complete directory list, this function should be called from within a rule body.

### 13.3.5 rule

The `rule` function is called whenever a build rule is defined. It is unlikely that you will need to redefine this function, except in very exceptional cases.

       rule(multiple, target, pattern, sources, options, body) : Rule
          multiple : String
          target   : Sequence
          pattern  : Sequence
          sources  : Sequence
          options  : Array
          body     : Body

The `rule` function is called when a rule is evaluated.

multiple
  A Boolean value indicating whether the rule was defined with a double colon `::`.
target
  The sequence of target names.
pattern
  The sequence of patterns. This sequence will be empty for two-part rules.
sources
  The sequence of dependencies.
options
  An array of options. Each option is represented as a `Map` object associating each specified option with a value.
body
  The body expression of the rule.

Consider the following rule.

       target: pattern: sources :name1: option1 :name2: option2
          expr1
          expr2

This expression represents the following function call, where square brackets are used to indicate arrays, and the curly brackets represent a `Map` object.

       rule(false, target, pattern, sources,
            { $|:name1:| = option1; $|:name2:| = option2 }
            [expr1; expr2])

### 13.3.6 build

        build(targets : File Array) : bool

Build the given targets. The value is true iff the build was successful. This function can be used only in `osh`.

## 13.4 The OMakeroot file

The standard OMakeroot file defines the functions are rules for building standard projects.

### 13.4.1 Variables

##### ROOT

The root directory of the current project.

##### CWD

The current working directory (the directory is set for each OMakefile in the project).

##### EMPTY

The empty string.

##### STDROOT

The name of the standard installed OMakeroot file.

##### ABORT_ON_COMMAND_ERROR

If set to true, the construction of a target should be aborted whenever one of the commands to build it fail. This defaults to true, and should normally be left that way.

##### SCANNER_MODE

This variable should be defined as one of four values (defaults to `enabled`).

enabled
  Allow the use of default `.SCANNER` rules. Whenever a rule does not specify a `:scanner:` dependency explicitly, try to find a `.SCANNER` with the same target name.
disabled
  Never use default `.SCANNER` rules.
warning
  Allow the use of default `.SCANNER` rules, but print a warning whenever one is selected.
error
  Do not allow the use of default `.SCANNER` rules. If a rule does not specify a `:scanner:` dependency, and there is a default `.SCANNER` rule, the build will terminate abnormally.

### 13.4.2 System variables

##### INSTALL

The command to install a program (`install` on `Unix`, `cp` on `Win32`).

##### PATHSEP

The normal path separator (`:` on `Unix`, `;` on `Win32`).

##### DIRSEP

The normal directory separator (`/` on `Unix`, `\` on `Win32`).

##### EXT_OBJ

File suffix for an object file (default is `.o` on `Unix`, and `.obj` on `Win32`).

##### EXT_LIB

File suffix for a static library (default is `.a` on `Unix`, and `.lib` on `Win32`).

##### EXT_DLL

File suffix for a shared library (default is `.so` on `Unix`, and `.dll` on `Win32`).

##### EXT_ASM

File suffix for an assembly file (default is `.s` on `Unix`, and `.asm` on `Win32`).

##### EXE

File suffix for executables (default is empty for `Unix`, and `.exe` on `Win32` and `Cygwin`).

## 13.5 Building C and C++ code

OMake provides extensive support for building C and C++ programs. In order to use the functions defined in this section, you need to make sure the line

    open build/C

is present in your `OMakeroot` file.

### 13.5.1 Autoconfiguration variables

These variables will get defined based on the “autoconf-style” `static.` tests executed when you run OMake for the first time. You can use them to configure your project accordingly, and you should not redefine them.

You can use the `--configure` command line option (Section ‍A.3.9) to force re-execution of all the tests.

A different set of autoconfiguration tests is performed depending on the build environment involved — one set of tests would be performed in a `Win32` environment, and another — in a Unix-like environment (including Linux, OS X and Cygwin).

#### 13.5.1.1 Unix-like systems

##### GCC_FOUND

A boolean flag specifying whether the `gcc` binary was found in your path.

##### GXX_FOUND

A boolean flag specifying whether the `g++` binary was found in your path.

#### 13.5.1.2 Win32

##### CL_FOUND

A boolean flag specifying whether the `cl` binary was found in your path.

##### LIB_FOUND

A boolean flag specifying whether the `lib` binary was found in your path.

### 13.5.2 C and C++ configuration variables

The following variables can be redefined in your project.

##### CC

The name of the C compiler (on `Unix` it defaults to `gcc` when `gcc` is present and to `cc` otherwise; on `Win32` defaults to `cl /nologo`).

##### CXX

The name of the C++ compiler (on `Unix` it defaults to `gcc` when `gcc` is present and to `c`++ otherwise; on `Win32` defaults to `cl /nologo`).

##### CPP

The name of the C preprocessor (defaults to `cpp` on `Unix`, and `cl /E` on `Win32`).

##### CFLAGS

Compilation flags to pass to the C compiler (default empty on `Unix`, and `/DWIN32` on `Win32`).

##### CXXFLAGS

Compilation flags to pass to the C++ compiler (default empty on `Unix`, and `/DWIN32` on `Win32`).

##### INCLUDES

Additional directories that specify the search path to the C and C++ compilers (default is `.`). The directories are passed to the C and C++ compilers with the `-I` option. The include path with `-I` prefixes is defined in the `PREFIXED_INCLUDES` variable.

##### LIBS

Additional libraries needed when building a program (default is empty).

##### CCOUT

The option to use for specifying the output file in C and C++ compilers (defaults to `-o` on `Unix` and `/Fo` on `Win32`).

##### AS

The name of the assembler (defaults to `as` on `Unix`, and `ml` on `Win32`).

##### ASFLAGS

Flags to pass to the assembler (default is empty on `Unix`, and `/c /coff` on `Win32`).

##### ASOUT

The option string that specifies the output file for `AS` (defaults to `-o` on `Unix` and `/Fo` on `Win32`).

##### AR

The name of the program to create static libraries (defaults to `ar cq` on `Unix`, and `lib` on `Win32`).

##### LD

The name of the linker (defaults to `ld` on `Unix`, and `cl` on `Win32`).

##### LDFLAGS

Options to pass to the linker (default is empty).

##### LDFLAGS_DLL

Options to pass to the linker when compiling a shared library (defaults to `-shared` on `Unix` and `/DLL` on `Win32`).

##### LDOUT

The option to use for specifying the output file in C and C++ linkers (defaults to `-o` on `Unix` and `/Fe` on `Win32`).

##### YACC

The name of the `yacc` parser generator (default is `yacc` on `Unix`, empty on `Win32`).

##### LEX

The name of the `lex` lexer generator (default is `lex` on `Unix`, empty on `Win32`).

### 13.5.3 Generated C files

Because the C scanners do not normally know anything about generated source files (such as generated header files), these files may need to be created before running the scanner.

#### 13.5.3.1 CGeneratedFiles, LocalCGeneratedFiles

    CGeneratedFiles(files)
    LocalCGeneratedFiles(files)

The `CGeneratedFiles` and `LocalCGeneratedFiles` functions specify files that need to be generated before any C files are scanned for dependencies. For example, if `config.h` and `inputs.h` are both generated files, specify:

    CGeneratedFiles(config.h inputs.h)

The `CGeneratedFiles` function is global — its arguments will be generated before any C files anywhere in the project are scanned for dependencies. The `LocalCGeneratedFiles` function follows the normal scoping rules of OMake.

### 13.5.4 Building C programs and Libraries

#### 13.5.4.1 StaticCLibrary, DynamicCLibrary

The `StaticCLibrary` builds a static library and the `DynamicCLibrary` function builds a shared library (DLL).

    StaticCLibrary(<target>, <files>)
    DynamicCLibrary(<target>, <files>)

The `<target>` does not include the library suffix, and The `<files>` list does not include the object suffix. These are obtained from the `EXT_LIB` (`EXT_DLL`) and `EXT_OBJ` variables.

This function returns the library filename.

The following command builds the library `libfoo.a` from the files `a.o b.o c.o` on `Unix`, or the library `libfoo.lib` from the files `a.obj b.obj c.obj` on `Win32`.

    StaticCLibrary(libfoo, a b c)
    .DEFAULT: $(StaticCLibrary libbar, a b c d)

##### CDLL_IMPLIES_STATIC

If the `CDLL_IMPLIES_STATIC` variable is enabled (this is default on `Win32`), all the `DynamicC` functions would assume that creating a shared library automatically created a static one.

#### 13.5.4.2 StaticCLibraryCopy, DynamicCLibraryCopy

The `StaticCLibraryCopy` and `DynamicCLibraryCopy` functions copy a library to an install location.

    StaticCLibraryCopy(<tag>, <dir>, <lib>)
    DynamicCLibraryCopy(<tag>, <dir>, <lib>)

The `<tag>` is the name of a target (typically a `.PHONY` target); the `<dir>` is the installation directory, and `<lib>` is the library to be copied (without the library suffix).

This function returns the filename of the library in the target directory.

For example, the following code copies the library `libfoo.a` to the `/usr/lib` directory.

    .PHONY: install

    StaticCLibraryCopy(install, /usr/lib, libfoo)

#### 13.5.4.3 StaticCLibraryInstall, DynamicCLibraryInstall

The `StaticCLibraryInstall` and `DynamicCLibraryInstall` functions build a library, and set the install location in one step. Return the filename of the library in the target directory.

    StaticCLibraryInstall(<tag>, <dir>, <libname>, <files>)
    DynamicCLibraryInstall(<tag>, <dir>, <libname>, <files>)

    StaticCLibraryInstall(install, /usr/lib, libfoo, a b c)

#### 13.5.4.4 StaticCObject, StaticCObjectCopy, StaticCObjectInstall

These functions mirror the `StaticCLibrary`, `StaticCLibraryCopy`, and `StaticCLibraryInstall` functions, but they build an object file (a `.o` file on `Unix`, and a `.obj` file on `Win32`).

#### 13.5.4.5 CProgram

The `CProgram` function builds a C program from a set of object files and libraries.

`CProgram(<name>, <files>)`

The `<name>` argument specifies the name of the program to be built; the `<files>` argument specifies the files to be linked. The function returns the filename of the executable.

Additional options can be passed through the following variables.

CFLAGS
  Flags used by the C compiler during the link step.
LDFLAGS
  Flags to pass to the loader.
LIBS
  Additional libraries to be linked.

For example, the following code specifies that the program `foo` is to be produced by linking the files `bar.o` and `baz.o` and libraries `libfoo.a`.

    section
       LIBS = libfoo
       LDFLAGS += -lbar
       CProgram(foo, bar baz)

#### 13.5.4.6 CProgramCopy

The `CProgramCopy` function copies a file to an install location.

`CProgramCopy(<tag>, <dir>, <program>)`

    CProgramCopy(install, /usr/bin, foo)

#### 13.5.4.7 CProgramInstall

The `CProgramInstall` function specifies a program to build, and a location to install, simultaneously.

`CProgramInstall(<tag>, <dir>, <name>, <files>)`

    section
       LIBS = libfoo
       LDFLAGS += -lbar
       CProgramInstall(install, /usr/bin, foo, bar baz)

#### 13.5.4.8 CXXProgram, CXXProgramInstall

The `CXXProgram` and `CXXProgramInstall` functions are equivalent to their C counterparts, except that would use `$(CXX)` and `$(CXXFLAGS)` for linking instead of `$(CC)` and `$(CFLAGS)`.

#### 13.5.4.9 StaticCXXLibrary, StaticCXXLibraryCopy, StaticCXXLibraryInstall, DynamicCXXLibrary, DynamicCXXLibraryCopy, DynamicCXXLibraryInstall

Similarly, the six `CXXLibrary` functions the C++ equivalents of the corresponding `CLibrary` functions.

## 13.6 Building OCaml code

OMake provides extensive support for building OCaml code, including support for tools like `ocamlfind`, `ocamlyacc` and `menhir`. In order to use the functions defined in this section, you need to make sure the line

    open build/OCaml

is present in your `OMakeroot` file.

### 13.6.1 Autoconfiguration variables for OCaml compilation

These variables will get defined based on the “autoconf-style” tests executed when you run OMake for the first time. You can use them to configure your project accordingly, and you should not redefine them.

You can use the `--configure` command line option (Section ‍A.3.9) to force re-execution of all the tests.

##### OCAMLOPT_EXISTS

True when `ocamlopt` (or `ocamlopt.opt`) is available on your machine.

##### OCAMLFIND_EXISTS

True when the ocamlfind is available on your machines.

##### OCAMLDEP_MODULES_AVAILABLE

True when a version of `ocamldep` that understands the `-modules` option is available on your machine.

##### CMXS_SUPPORTED

True if "ocamlopt -shared" is supported by the compiler.

##### MENHIR_AVAILABLE

True when the Menhir parser-generator is available on your machine.

##### OCAMLLIB

The location of OCaml library directory (output of `ocamlc -where`). Empty when no ocamlc is found.

### 13.6.2 Configuration variables for OCaml compilation

The following variables can be redefined in your project.

##### USE_OCAMLFIND

Whether to use the `ocamlfind` utility (default `false`)

##### OCAMLC

The OCaml bytecode compiler (default `ocamlc.opt` if it exists and `USE_OCAMLFIND` is not set, otherwise `ocamlc`).

##### OCAMLOPT

The OCaml native-code compiler (default `ocamlopt.opt` if it exists and `USE_OCAMLFIND` is not set, otherwise `ocamlopt`).

##### CAMLP4

The `camlp4` preprocessor (default `camlp4`).

##### OCAMLLEX

The OCaml lexer generator (default `ocamllex`).

##### OCAMLLEXFLAGS

The flags to pass to `ocamllex` (default `-q`).

##### OCAMLYACC

The OCaml parser generator (default `ocamlyacc`).

##### OCAMLYACCFLAGS

Additional options to pass to `$(OCAMLYACC)`.

##### OCAMLDEP

The OCaml dependency analyzer (default `ocamldep`).

##### OCAMLDEP_MODULES_ENABLED

Instead of using `OCAMLDEP` in a traditional `make`-style fashion, run `$(OCAMLDEP) -modules` and then postprocess the output internally to discover all the relevant generated `.ml` and `.mli` files. See Section ‍13.6.5 for more information on interactions between OMake, `OCAMLDEP` and generated files. Set to `$(OCAMLDEP_MODULES_AVAILABLE)` by default.

##### OCAMLMKTOP

The OCaml toploop compiler (default `ocamlmktop`).

##### OCAMLLINK

The OCaml bytecode linker (default `$(OCAMLC)`).

##### OCAMLOPTLINK

The OCaml native-code linker (default `$(OCAMLOPT)`).

##### OCAMLINCLUDES

Search path to pass to the OCaml compilers (default `.`). The search path with the `-I` prefix is defined by the `PREFIXED_OCAMLINCLUDES` variable.

##### OCAMLINCLUDES_FOR_OCAMLDEP_MODULES

Extra path for searching files corresponding to dependencies returned by "ocamldep -modules". This defaults to ".". There is normally no reason to change this value.

##### OCAMLFIND

The `ocamlfind` utility (default `ocamlfind` if `USE_OCAMLFIND` is set, otherwise empty).

##### OCAMLFINDFLAGS

The flags to pass to `ocamlfind` (default empty, `USE_OCAMLFIND` must be set).

##### OCAMLPACKS

Package names to pass to `ocamlfind` (`USE_OCAMLFIND` must be set).

##### BYTE_ENABLED

Flag indicating whether to use the bytecode compiler (default `true`, when no `ocamlopt` found, `false` otherwise).

##### NATIVE_ENABLED

Flag indicating whether to use the native-code compiler (default `true`, when ocamlopt is found, `false` otherwise). Both `BYTE_ENABLED` and `NATIVE_ENABLED` can be set to true; at least one should be set to true.

##### CMXS_ENABLED

Flag indicating whether libraries are also created as plugins. This defaults to `false` for compatibility with old omake versions. Set it to `CMXS_SUPPORTED` to enable this feature when supported

##### MENHIR_ENABLED

Define this as `true` if you wish to use `menhir` instead of `ocamlyacc` (default `false`).

##### EXTENDED_DIGESTS

Whether to include more information into rule digests and make it more sensitive to structural changes at the cost of build speed (`true` or `false`).

##### OCAML_CC

The C compiler used internally by OCaml

##### OCAML_CFLAGS

The C compiler flags used by OCaml

### 13.6.3 OCaml command flags

The following variables specify additional options to be passed to the OCaml tools.

##### OCAMLDEPFLAGS

Flags to pass to `OCAMLDEP`.

##### OCAMLPPFLAGS

Flags to pass to `CAMLP4`.

##### OCAMLCFLAGS

Flags to pass to the byte-code compiler (default `-g`).

##### OCAMLOPTFLAGS

Flags to pass to the native-code compiler (default empty).

##### OCAMLFLAGS

Flags to pass to either compiler (default `-warn-error A`).

##### OCAML_BYTE_LINK_FLAGS

Flags to pass to the byte-code linker (default empty).

##### OCAML_NATIVE_LINK_FLAGS

Flags to pass to the native-code linker (default empty).

##### OCAML_LINK_FLAGS

Flags to pass to either linker.

##### MENHIR_FLAGS

Additional flags to pass to `menhir`.

### 13.6.4 Library variables

The following variables are used during linking.

##### OCAML_LIBS

Libraries to pass to the linker. These libraries become dependencies of the link step.

##### OCAML_OTHER_LIBS

Additional libraries to pass to the linker. These libraries are not included as dependencies to the link step. Typical use is for the OCaml standard libraries like `unix` or `str`.

##### OCAML_CLIBS

C libraries to pass to the linker.

##### OCAML_LIB_FLAGS

Extra flags for the library linker.

##### ABORT_ON_DEPENDENCY_ERRORS

OCaml linker requires the OCaml files to be listed in dependency order. Normally, all the functions presented in this section will automatically sort the list of OCaml modules passed in as the `<files>` argument. However, this variable is set to `true`, the order of the files passed into these function will be left as is, but OMake will abort with an error message if the order is illegal.

### 13.6.5 Generated OCaml Files

As of OCaml version 3.09.2, the standard `ocamldep` scanner is “broken”. The main issue is that it finds only those dependencies that already exist. If `foo.ml` contains a dependency on `Bar`,

    foo.ml:
       open Bar

then the default `ocamldep` will only find the dependency if a file `bar.ml` or `bar.ml` exists in the include path. It will not find (or print) the dependency if, for example, only `bar.mly` exists at the time `ocamldep` is run, even though `bar.ml` and `bar.mli` can be generated from `bar.mly`.

OMake currently provides two methods for addressing this problem — one that requires manually specifying the generated files, and an experimental method for discovering such “hidden” dependencies automatically. The `OCAMLDEP_MODULES_ENABLED` variable controls which method is going to be used. When this variable is false, the manual specifications are expected and when it is true, the automated discovery will be attempted.

#### 13.6.5.1 OCamlGeneratedFiles, LocalOCamlGeneratedFiles

    OCamlGeneratedFiles(files)
    LocalOCamlGeneratedFiles(files)

When the `OCAMLDEP_MODULES_ENABLED` variable variable is set to `false`, the `OCamlGeneratedFiles` and `LocalOCamlGeneratedFiles` functions specify files that need to be generated before any OCaml files are scanned for dependencies. For example, if `parser.ml` and `lexer.ml` are both generated files, specify:

    OCamlGeneratedFiles(parser.ml lexer.ml)

The `OCamlGeneratedFiles` function is global — its arguments will be generated before any OCaml files anywhere in the project are scanned for dependencies. The `LocalOCamlGeneratedFiles` function follows the normal scoping rules of OMake.

These functions have no effect when the `OCAMLDEP_MODULES_ENABLED` variable is true.

#### 13.6.5.2 Automatic discovery of generated files during dependency analysis

Having to specify the generated files manually when OMake could discover them automatically is obviously suboptimal. To address this, we tell `ocamldep` to only find the free module names in a file and then post-process the results internally.

This automated functionality is enabled when the `OCAMLDEP_MODULES_ENABLED` variable is set to `true`. By default, `OCAMLDEP_MODULES_ENABLED` variable will be set to `$(OCAMLDEP_MODULES_AVAILABLE)`.

Note that the `ocamldep` functionality this relies upon is only included in the OCaml version 3.10 and higher. It’s availability will be discovered automatically and the `OCAMLDEP_MODULES_AVAILABLE` variable will be set accordingly.

#### 13.6.5.3 DeclareMLIOnly

Sometimes, MLI files only contain type and exception definitions. In fact, the MLI file could also be parsed as ML file. For convenience, it is possible to declare modules as MLI-only. In this case, an ML file needs not to be written. Do this as follows:

`DeclareMLIOnly(<files>)`

where the `<files>` are without suffixes.

Note that this really only works if the MLI file can be parsed as ML file. Also, it is possible this results in an object to be linked in, so don’t forget to link the modules into the library or executable.

### 13.6.6 Using the Menhir parser generator

Menhir is a parser generator that is mostly compatible with `ocamlyacc`, but with many improvements. A few of these are listed here (excerpted from the Menhir home page http://cristal.inria.fr/~fpottier/menhir/).

- Menhir’s explanations are believed to be understandable by mere humans.
- Menhir allows grammar specifications to be split over multiple files. It also allows several grammars to share a single set of tokens.
- Menhir is able to produce parsers that are parameterized by Objective Caml modules.
- Added by jyh With the `--infer` option, Menhir can typecheck the semantic actions in your grammar at generation time.

What do you need to do to use Menhir instead of `ocamlyacc`?

1. Place the following definition before the relevant section of your project (or at the top of your project `OMakefile` if you want to use Menhir everywhere).

          MENHIR_ENABLED = true

2. Optionally, add any desired Menhir options to the `MENHIR_FLAGS` variable.

          MENHIR_FLAGS += --infer

With this setup, any file with a `.mly` suffix will be compiled with Menhir.

If your grammar is split across several files, you need to specify it explicitly, using the `MenhirMulti` function.

        MenhirMulti(target, sources)
            target : filename, without suffix
            sources : the files that define the grammar, without suffixes

For example, if you want to generate the parser files `parse.ml` and `parse.mli`, from the grammar specified in files `a.mly` and `b.mly`, you would use the following.

        MenhirMulti(parse, a b)

### 13.6.7 Building OCaml programs and Libraries

#### 13.6.7.1 OCamlLibrary

The `OCamlLibrary` function builds an OCaml ‍library.

`OCamlLibrary(<libname>, <files>)`

The `<libname>` and `<files>` are listed without suffixes.

This function returns the list of all the targets that it defines the rules for (including the `$(name)$(EXT_LIB)` file when `NATIVE_ENABLED` is set).

The following code builds the `libfoo.cmxa` library from the files `foo.cmx` and `bar.cmx` (if `NATIVE_ENABLED` is set), and `libfoo.cma` from `foo.cmo` and `bar.cmo` (if `BYTE_ENABLED` is set).

    OCamlLibrary(libfoo, foo bar)

If the variable `CMXS_ENABLED` is set, additionally the cmxs ‍plugin is created. Note that `CMXS_SUPPORTED` returns whether the compiler installation supports plugins, so you can simply set

    CMXS_ENABLED = CMXS_SUPPORTED

before calling `OCamlLibrary`. For compatibility with older omake versions, `CMXS_ENABLED` defaults to `false`.

#### 13.6.7.2 OCamlMixedLibrary

The `OCamlMixedLibrary` function builds an OCaml ‍library from ML ‍files and foreign objects.

`OCamlMixedLibrary(<libname>, <ml-files>, <foreign-files>)`

It is particularly useful if one or more ml-files contain `external`‍definitions that are satisifed by the foreign-files. It works similarly to `OCamlLibrary`, but also

1. adds dependencies of `<foreign-files>` to `<libname>` and
2. appends all objects defined by `<foreign-files>` to `<libname>`.

The `<libname>`, `<files>`, and `<foreign-files>` are listed without suffixes.

#### 13.6.7.3 OCamlPackage

The `OCamlPackage` function builds an OCaml package.

`OCamlPackage(<name>, <files>)`

The `<name>` and `<files>` are listed without suffixes. The `<files>` must have been compiled with the `-for-pack <ident>` flag to the OCaml compiler.

This function returns the list of all the targets that it defines the rules for (including the `$(name)$(EXT_LIB)` file when `NATIVE_ENABLED` is set).

The following code builds the `libfoo.cmx` package from the files `package.cmx` and `bar.cmx` (if `NATIVE_ENABLED` is set), and `package.cmo` from `foo.cmo` and `bar.cmo` (if `BYTE_ENABLED` is set).

    OCamlPackage(package, foo bar)

#### 13.6.7.4 OCamlLibraryCopy

The `OCamlLibraryCopy` function copies a library to an install location.

`OCamlLibraryCopy(<tag>, <libdir>, <libname>, <interface-files>)`

The `<interface-files>` specify additional interface files to be copied if the `INSTALL_INTERFACES` variable is true.

#### 13.6.7.5 OCamlLibraryInstall

The `OCamlLibraryInstall` function builds a library and copies it to an install location in one step.

`OCamlLibraryInstall(<tag>, <libdir>, <libname>, <files>)`

#### 13.6.7.6 OCamlProgram

The `OCamlProgram`‍function builds an OCaml ‍program. It returns the array with all the targets for which it has defined the rules (`$(name)$(EXE)` and `$(name).run` and/or `$(name).opt`, depending on the `NATIVE_ENABLED` and `BYTE_ENABLED` variables).

`OCamlProgram(<name>, <files>)`

Additional variables used:

`OCAML_LIBS`
  Additional libraries passed to the linker, without suffix. These files become dependencies of the target program.
`OCAML_OTHER_LIBS`
  Additional libraries passed to the linker, without suffix. These files do not become dependencies of the target program.
`OCAML_CLIBS`
  C ‍libraries to pass to the linker.
`OCAML_BYTE_LINK_FLAGS`
  Flags to pass to the bytecode ‍linker.
`OCAML_NATIVE_LINK_FLAGS`
  Flags to pass to the native-code ‍linker.
`OCAML_LINK_FLAGS`
  Flags to pass to both linkers.

#### 13.6.7.7 OCamlMixedProgram

The `OCamlMixedProgram` function builds an OCaml ‍program from ML files and foreign objects.

`OCamlMixedProgram(<programname>, <ml-files>, <foreign-files>)`

It is particularly useful if one or more ml-files contain `external`‍definitions that are satisifed by the foreign-files. It works similarly to `OCamlProgram`, but also

1. adds dependencies of `<foreign-files>` to `<programname>` and
2. appends all objects defined by `<foreign-files>` to `<programname>`.

The `<programname>`, `<files>`, and `<foreign-files>` are listed without suffixes.

#### 13.6.7.8 OCamlProgramCopy

The `OCamlProgramCopy` function copies an OCaml program to an install location.

`OCamlProgramCopy(<tag>, <bindir>, <name>)`

Additional variables used:

NATIVE_ENABLED
  If the `NATIVE_ENABLED` variable is set, the native-code executable is copied; otherwise the byte-code executable is copied.

#### 13.6.7.9 OCamlProgramInstall

The `OCamlProgramInstall` function builds a programs and copies it to an install location in one step.

`OCamlProgramInstall(<tag>, <bindir>, <name>, <files>)`

## 13.7 Building LATEX files

OMake provides support for building LATEX documents, including support for automatically running BiBTex and for producing PostScript and PDF files. In order to use the functions defined in this section, you need to make sure the line

    open build/LaTeX

is present in your `OMakeroot` file.

### 13.7.1 Configuration variables

The following variables can be modified in your project.

##### LATEX

The LATEX command (default `latex`).

##### TETEX2_ENABLED

Flag indicating whether to use advanced LATEX options present in TeTeX v.2 (default value is determined the first time omake reads `LaTeX.src` and depends on the version of LATEX you have installed).

##### LATEXFLAGS

The LATEX flags (defaults depend on the `TETEX2_ENABLED` variable)

##### BIBTEX

The BibTeX command (default `bibtex`).

##### MAKEINDEX

The command to build an index (default `makeindex`).

##### DVIPS

The `.dvi` to PostScript converter (default `dvips`).

##### DVIPSFLAGS

Flags to pass to `dvips` (default `-t letter`).

##### DVIPDFM

The `.dvi` to `.pdf` converter (default `dvipdfm`).

##### DVIPDFMFLAGS

Flags to pass to `dvipdfm` (default `-p letter`).

##### PDFLATEX

The `.latex` to `.pdf` converter (default `pdflatex`).

##### PDFLATEXFLAGS

Flags to pass to pdflatex (default is `$`(LATEXFLAGS)`).

##### USEPDFLATEX

Flag indicating whether to use pdflatex instead of dvipdfm to generate the `.pdf` document (default `false`).

### 13.7.2 Building LATEX documents

#### 13.7.2.1 LaTeXDocument

The `LaTeXDocument` produces a LATEX document.

`LaTeXDocument(<name>, <texfiles>)`

The document `<name>` and `<texfiles>` are listed without suffixes. This function returns the filenames for the generated `.ps` (unless `USEPDFLATEX` variable is set) and `.pdf` files.

Additional variables used:

##### TEXINPUTS

The LATEX search path (an array of directories, default is taken from the `TEXINPUTS` environment variable).

##### TEXDEPS

Additional files this document depends on.

##### TEXVARS

An array of names of the environment variables that are to be updated based on the value of OMake’s `TEXINPUTS` variable. Defaults to `TEXINPUTS` `BIBINPUTS` `BSTINPUTS`.

#### 13.7.2.2 TeXGeneratedFiles, LocalTeXGeneratedFiles

    TeXGeneratedFiles(files)
    LocalTeXGeneratedFiles(files)

The `TeXGeneratedFiles` and `LocalTeXGeneratedFiles` functions specify files that need to be generated before any LATEXfiles are scanned for dependencies. For example, if `config.tex` and `inputs.tex` are both generated files, specify:

        TeXGeneratedFiles(config.tex inputs.tex)

The `TeXGeneratedFiles` function is global — its arguments will be generated before any TeX files anywhere in the project are scanned for dependencies. The `LocalTeXGeneratedFiles` function follows the normal scoping rules of OMake.

#### 13.7.2.3 LaTeXDocumentCopy

The `LaTeXDocumentCopy` copies the document to an install location.

`LaTeXDocumentCopy(<tag>, <libdir>, <installname>, <docname>)`

This function copies just the `.pdf` and `.ps` files.

#### 13.7.2.4 LaTeXDocumentInstall

The `LaTeXDocumentInstall` builds a document and copies it to an install location in one step.

`LaTeXDocumentInstall(<tag>, <libdir>, <installname>, <docname>, <files>)`

Jump to: | ‍ ‍ | OMake Home • Guide Home • Guide (single-page) • Contents (short) • Contents (long)
Index: | ‍ ‍ | All • Variables • Functions • Objects • Targets • Options