Plasma GitLab Archive
Projects Blog Knowledge


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

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
This web site is published by Informatikbüro Gerd Stolpmann
Powered by Caml