This file has been translated from LaTeX by HeVeA.  Node: Chapter 12, Next: Section 12-1, Prev: Section 11-1, Up: Top Chapter 12 Build functions and utilities ******************************************** * Menu: * Section 12-1:: Builtin .PHONY targets * Section 12-2:: Options and versioning * Section 12-3:: Examining the dependency graph * Section 12-4:: The OMakeroot file * Section 12-5:: Building C and C++ code * Section 12-6:: Building OCaml code * Section 12-7:: Building LaTeX files  Node: Section 12-1, Next: Section 12-2, Prev: Chapter 12, Up: Chapter 12 12.1 Builtin .PHONY targets *=*=*=*=*=*=*=*=*=*=*=*=*=*=* The complete set of builtin `.PHONY' targets include the following. .PHONY Declares new phony targets (Section 7.10*Note Section 7-10::). .DEFAULT Declare the default build targets (Section 7.7*Note Section 7-7::). .SUBDIRS Include a directory as part of the project (Section 7.8*Note Section 7-8::). .SCANNER Define a dependency scanner (Section 7.8*Note Section 7-8::). .INCLUDE Include a file (Section 7.9*Note Section 7-9::). .ORDER Define a file-dependency ordering rule (Section 9.3.5*Note Subsection 9-3-5::). .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*Note 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*Note Appendix 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.  Node: Section 12-2, Next: Subsection 12-2-1, Prev: Section 12-1, Up: Chapter 12 12.2 Options and versioning *=*=*=*=*=*=*=*=*=*=*=*=*=*=* * Menu: * Subsection 12-2-1:: OMakeFlags * Subsection 12-2-2:: OMakeVersion * Subsection 12-2-3:: cmp-versions * Subsection 12-2-4:: DefineCommandVars  Node: Subsection 12-2-1, Next: Subsection 12-2-2, Prev: Section 12-2, Up: Section 12-2 12.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 >>  Node: Subsection 12-2-2, Next: Subsection 12-2-3, Prev: Subsection 12-2-1, Up: Section 12-2 12.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 `', then an exception is raised. In the two argument form, the version must lie between `version1' and `version2'.  Node: Subsection 12-2-3, Next: Subsection 12-2-4, Prev: Subsection 12-2-2, Up: Section 12-2 12.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.  Node: Subsection 12-2-4, Next: Section 12-3, Prev: Subsection 12-2-3, Up: Section 12-2 12.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.  Node: Section 12-3, Next: Subsection 12-3-1, Prev: Section 12-2, Up: Chapter 12 12.3 Examining the dependency graph *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* * Menu: * Subsection 12-3-1:: dependencies, dependencies-all, dependencies-proper * Subsection 12-3-2:: target * Subsection 12-3-3:: find-build-targets * Subsection 12-3-4:: project-directories * Subsection 12-3-5:: rule  Node: Subsection 12-3-1, Next: Subsection 12-3-2, Prev: Section 12-3, Up: Section 12-3 12.3.1 dependencies, dependencies-all, dependencies-proper ============================================================ \@na me{@default356} << $(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. 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. For a shorter form, see the `filter-proper-targets' function. << .PHONY: clean APP = ... # the name of the target application clean: $(APP) rm $(dependencies-proper $(APP)) >>  Node: Subsection 12-3-2, Next: Subsection 12-3-3, Prev: Subsection 12-3-1, Up: Section 12-3 12.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.  Node: Subsection 12-3-3, Next: Subsection 12-3-4, Prev: Subsection 12-3-2, Up: Section 12-3 12.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 12.1*Note Section 12-1::) and `.BUILD_FAILURE' (Section 12.1*Note Section 12-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))" >>  Node: Subsection 12-3-4, Next: Subsection 12-3-5, Prev: Subsection 12-3-3, Up: Section 12-3 12.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.  Node: Subsection 12-3-5, Next: Section 12-4, Prev: Subsection 12-3-4, Up: Section 12-3 12.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]) >>  Node: Section 12-4, Next: Subsection 12-4-1, Prev: Section 12-3, Up: Chapter 12 12.4 The OMakeroot file *=*=*=*=*=*=*=*=*=*=*=*=* The standard OMakeroot file defines the functions are rules for building standard projects. * Menu: * Subsection 12-4-1:: Variables * Subsection 12-4-2:: System variables  Node: Subsection 12-4-1, Next: Subsection 12-4-2, Prev: Section 12-4, Up: Section 12-4 12.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.  Node: Subsection 12-4-2, Next: Section 12-5, Prev: Subsection 12-4-1, Up: Section 12-4 12.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_LIB File suffix for a static library (default is `.a' on `Unix', and `.lib' on `Win32'). EXT_OBJ File suffix for an object file (default is `.o' on `Unix', and `.obj' 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').  Node: Section 12-5, Next: Subsection 12-5-1, Prev: Section 12-4, Up: Chapter 12 12.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 <> is present in your `OMakeroot' file. * Menu: * Subsection 12-5-1:: Autoconfiguration variables * Subsection 12-5-2:: C and C++ configuration variables * Subsection 12-5-3:: Generated C files * Subsection 12-5-4:: Building C programs and Libraries  Node: Subsection 12-5-1, Next: Subsection 12-5-2, Prev: Section 12-5, Up: Section 12-5 12.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*Note Subsection 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). 12.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. 12.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.  Node: Subsection 12-5-2, Next: Subsection 12-5-3, Prev: Subsection 12-5-1, Up: Section 12-5 12.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). 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').  Node: Subsection 12-5-3, Next: Subsection 12-5-4, Prev: Subsection 12-5-2, Up: Section 12-5 12.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. 12.5.3.1 CGeneratedFiles, LocalCGeneratedFiles ------------------------------------------------ <> 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: <> 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.  Node: Subsection 12-5-4, Next: Section 12-6, Prev: Subsection 12-5-3, Up: Section 12-5 12.5.4 Building C programs and Libraries ========================================== 12.5.4.1 StaticCLibrary ------------------------- The `StaticCLibrary' builds a static library. `StaticCLibrary(, )' The `' does not include the library suffix, and The `' list does not include the object suffix. These are obtained from the `EXT_LIB' 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'. <> 12.5.4.2 StaticCLibraryCopy ----------------------------- The `StaticCLibraryCopy' function copies the static library to an install location. `StaticCLibraryCopy(, , )' The `' is the name of a target (typically a `.PHONY' target); the `' is the installation directory, and `' 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) >> 12.5.4.3 StaticCLibraryInstall -------------------------------- The `StaticCLibraryInstall' function builds a library, and sets the install location in one step. It returns the filename of the library in the target directory. `StaticCLibraryInstall(, , , )' <> 12.5.4.4 StaticCObject, StaticCObjectCopy, StaticCObjectInstall ----------------------------------------------------------------- \@na me{@default403} 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'). 12.5.4.5 CProgram ------------------- The `CProgram' function builds a C program from a set of object files and libraries. `CProgram(, )' The `' argument specifies the name of the program to be built; the `' 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'. <
> 12.5.4.6 CProgramCopy ----------------------- The `CProgramCopy' function copies a file to an install location. `CProgramCopy(, , )' <> 12.5.4.7 CProgramInstall -------------------------- The `CProgramInstall' function specifies a program to build, and a location to install, simultaneously. `CProgramInstall(, , , )' <
> 12.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)'. 12.5.4.9 StaticCXXLibrary, StaticCXXLibraryCopy, -------------------------------------------------- StaticCXXLibraryInstall ----------------------- \@na me{@default411} Similarly, `StaticCXXLibrary', `StaticCXXLibraryCopy' and `StaticCXXLibraryInstall' are the C++ equivalents of `StaticCLibrary', `StaticCLibraryCopy' and `StaticCLibraryInstall' functions.  Node: Section 12-6, Next: Subsection 12-6-1, Prev: Section 12-5, Up: Chapter 12 12.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 <> is present in your `OMakeroot' file. * Menu: * Subsection 12-6-1:: Autoconfiguration variables for OCaml compilation * Subsection 12-6-2:: Configuration variables for OCaml compilation * Subsection 12-6-3:: OCaml command flags * Subsection 12-6-4:: Library variables * Subsection 12-6-5:: Generated OCaml Files * Subsection 12-6-6:: Using the Menhir parser generator  Node: Subsection 12-6-1, Next: Subsection 12-6-2, Prev: Section 12-6, Up: Section 12-6 12.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*Note Subsection 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. MENHIR_AVAILABLE True when the Menhir parser-generator is available on your machine.  Node: Subsection 12-6-2, Next: Subsection 12-6-3, Prev: Subsection 12-6-1, Up: Section 12-6 12.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 The OCaml dependency analyzer that understands the `-module' option (default `ocamldep', if `ocamldep -modules' works, or `ocamlrun ocamldep-omake', if `ocamlrun ocamldep-omake -modules' works, and empty when neither works). OCAMLDEP_MODULES_ENABLED Instead of using `OCAMLDEP' in a traditional `make'-style fashion, run `$(OCAMLDEP_MODULES) -modules' and then postprocess the output internally to discover all the relevant generated `.ml' and `.mli' files. See Section 12.6.5*Note Subsection 12-6-5:: for more information on interactions between OMake, `OCAMLDEP' and generated files. This feature is currently considered highly experimental and is disabled 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. 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. MENHIR_ENABLED Define this as `true' if you wish to use `menhir' instead of `ocamlyacc' (default `false').  Node: Subsection 12-6-3, Next: Subsection 12-6-4, Prev: Subsection 12-6-2, Up: Section 12-6 12.6.3 OCaml command flags ============================ The following variables specify additional options to be passed to the OCaml tools. OCAMLDEPFLAGS Flags to pass to `OCAMLDEP' (but not to `OCAMLDEP_MODULES'). 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'.  Node: Subsection 12-6-4, Next: Subsection 12-6-5, Prev: Subsection 12-6-3, Up: Section 12-6 12.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 `' 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.  Node: Subsection 12-6-5, Next: Subsection 12-6-6, Prev: Subsection 12-6-4, Up: Section 12-6 12.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', <> 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. 12.6.5.1 OCamlGeneratedFiles, LocalOCamlGeneratedFiles -------------------------------------------------------- <> 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: <> 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. 12.6.5.2 Automatic discovery of generated files during dependency ------------------------------------------------------------------- analysis -------- Having to specify the generated files manualy when OMake could discover them automatically is obviously suboptimal. To address this, we try to use a custom `ocamldep' that only finds the free module names in a file. This functionality is experimental and is disabled by default for now. Set the 'OCAMLDEP_MODULES_ENABLED' variable to `true' (or to `$(OCAMLDEP_MODULES_AVAILABLE)') in your project to enable it. Note that the experimental `ocamldep' functionality this relies upon is not yet included in the standard OCaml (it is expected to be a part of the upcoming OCaml 3.10 --- see http://caml.inria.fr/mantis/view.php?id=4047). Temporarily, we distribute a bytecode version `ocamldep-omake' of the appropriately modified `ocamldep'. The appropriate `ocamldep' will be discovered automatically --- see and the 'OCAMLDEP_MODULES_AVAILABLE' and 'OCAMLDEP_MODULES' variables will be set accordingly.  Node: Subsection 12-6-6, Next: Section 12-7, Prev: Subsection 12-6-5, Up: Section 12-6 12.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) >> 12.6.6.1 OCamlLibrary ----------------------- The `OCamlLibrary' function builds an OCaml library. `OCamlLibrary(, )' The `' and `' 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). <> 12.6.6.2 OCamlPackage ----------------------- The `OCamlPackage' function builds an OCaml package. `OCamlPackage(, )' The `' and `' are listed without suffixes. The `' must have been compiled with the `-for-pack ' 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). <> 12.6.6.3 OCamlLibraryCopy --------------------------- The `OCamlLibraryCopy' function copies a library to an install location. `OCamlLibraryCopy(, , , )' The `' specify additional interface files to be copied if the `INSTALL_INTERFACES' variable is true. 12.6.6.4 OCamlLibraryInstall ------------------------------ The `OCamlLibraryInstall' function builds a library and copies it to an install location in one step. `OCamlLibraryInstall(, , , )' 12.6.6.5 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(, )' 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. 12.6.6.6 OCamlProgramCopy --------------------------- The `OCamlProgramCopy' function copies an OCaml program to an install location. `OCamlProgramCopy(, , )' 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. 12.6.6.7 OCamlProgramInstall ------------------------------ The `OCamlProgramInstall' function builds a programs and copies it to an install location in one step. `OCamlProgramInstall(, , , )'  Node: Section 12-7, Next: Subsection 12-7-1, Prev: Section 12-6, Up: Chapter 12 12.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 <> is present in your `OMakeroot' file. * Menu: * Subsection 12-7-1:: Configuration variables * Subsection 12-7-2:: Building LaTeX documents  Node: Subsection 12-7-1, Next: Subsection 12-7-2, Prev: Section 12-7, Up: Section 12-7 12.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').  Node: Subsection 12-7-2, Next: Chapter 13, Prev: Subsection 12-7-1, Up: Section 12-7 12.7.2 Building LaTeX documents ================================= 12.7.2.1 LaTeXDocument ------------------------ The `LaTeXDocument' produces a LaTeX document. `LaTeXDocument(, )' The document `' and `' are listed without suffixes. This function returns the filenames for the generated `.ps' 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'. 12.7.2.2 TeXGeneratedFiles, LocalTeXGeneratedFiles ---------------------------------------------------- <> 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. 12.7.2.3 LaTeXDocumentCopy ---------------------------- The `LaTeXDocumentCopy' copies the document to an install location. `LaTeXDocumentCopy(, , , )' This function copies just the `.pdf' and `.ps' files. 12.7.2.4 LaTeXDocumentInstall ------------------------------- The `LaTeXDocumentInstall' builds a document and copies it to an install location in one step. `LaTeXDocumentInstall(, , , , )'  Node: Chapter 13, Next: Section 13-1, Prev: Section 12-7, Up: Top Chapter 13 Autoconfiguration functions and variables ******************************************************** OMake standard library provides a number of functions and variables intended to help one write build specifications that need to be capable of autoconfiguring itself to adjust to different build environments. * Menu: * Section 13-1:: General-purpose autoconfiguration functions * Section 13-2:: Translating 'autoconf' scripts * Section 13-3:: Predefined configuration tests  Node: Section 13-1, Next: Subsection 13-1-1, Prev: Chapter 13, Up: Chapter 13 13.1 General-purpose autoconfiguration functions *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*= The following general-purpose functions can be used to discover the properties of your build environment in a fashion similar to the one used by GNU autoconf tool you may be familiar with. It is recommended that these function be used from an appropriate `static.' block (see Section 4.18*Note Section 4-18:: for more information). In order to use the following general-purpose functions, you need to have the line <> included in your `OMakefile' or `OMakeroot'. * Menu: * Subsection 13-1-1:: ConfMsgChecking, ConfMsgResult * Subsection 13-1-2:: ConfMsgWarn, ConfMsgError * Subsection 13-1-3:: ConfMsgYesNo, ConfMsgFound * Subsection 13-1-4:: TryCompileC, TryLinkC, TryRunC * Subsection 13-1-5:: RunCProg * Subsection 13-1-6:: CheckCHeader, VerboseCheckCHeader * Subsection 13-1-7:: CheckCLib, VerboseCheckCLib * Subsection 13-1-8:: CheckProg  Node: Subsection 13-1-1, Next: Subsection 13-1-2, Prev: Section 13-1, Up: Section 13-1 13.1.1 ConfMsgChecking, ConfMsgResult ======================================= <) ... ConfMsgResult() >> The `ConfMsgChecking' function output message of the form `--- Checking ... ' without any trailing newline. After the test advertized by `ConfMsgChecking' is performed, the `ConfMsgResult' function should be used to output the result. In certain cases users may want to redefine these function --- for example, to use a different output formatting and/or to copy the messages to a log file. Example: <>  Node: Subsection 13-1-2, Next: Subsection 13-1-3, Prev: Subsection 13-1-1, Up: Section 13-1 13.1.2 ConfMsgWarn, ConfMsgError ================================== <) ConfMsgError() >> Print a warning or an error message respectively. `ConfMsgError' would then abort OMake.  Node: Subsection 13-1-3, Next: Subsection 13-1-4, Prev: Subsection 13-1-2, Up: Section 13-1 13.1.3 ConfMsgYesNo, ConfMsgFound =================================== < flag = $(ConfMsgFound >> The `ConfMsgFound' function expects to receive a boolean flag describing whether a test previously announced using the 'ConfMsgChecking' function found what it was looking for. `ConfMsgFound' will output the appropriate result ("found" or "NOT found") using the 'ConfMsgResult' function and return its argument back. The `ConfMsgYesNo' function is similar, outputting a simple ("yes" or "NO").  Node: Subsection 13-1-4, Next: Subsection 13-1-5, Prev: Subsection 13-1-3, Up: Section 13-1 13.1.4 TryCompileC, TryLinkC, TryRunC ======================================= \@na me{@default489} <) success = $(TryLinkC ) success = $(TryRunC ) >> Given the text of a C program, the `TryCompileC', `TryLinkC', and `TryRunC' functions would try to compile / compile and link / compile, link, and run, the given program and return a boolean flag indicating whether the attempt was successful. `TryCompileC' will use the 'CC', 'CFLAGS' and 'INCLUDES' variables to run the C compiler. `TryLinkC' and `TryRunC' will also use the 'LDFLAGS' variable to run the C compiler and linker. However, the flags like `/WX', `-Werror' and `-warn-error' will be not be passed to the compiler, even if they occur in `CFLAGS'. These functions are silent and should normally be used with an appropriate 'ConfMsgChecking' ... 'ConfMsgResult'.  Node: Subsection 13-1-5, Next: Subsection 13-1-6, Prev: Subsection 13-1-4, Up: Section 13-1 13.1.5 RunCProg ================= <) >> `RunCProg' is similar to the 'RunCProg' function, except that it returns the output of the function (will return `false' if the program fails to compile or run).  Node: Subsection 13-1-6, Next: Subsection 13-1-7, Prev: Subsection 13-1-5, Up: Section 13-1 13.1.6 CheckCHeader, VerboseCheckCHeader ========================================== <) success = $(VerboseCheckCHeader ) >> Use the 'TryCompileC' function to check whether your C compiler can locate and process the specified headers files. Will incude `' before including the header files. Both functions return a boolean value. The `CheckCHeader' function is silent; the `VerboseCheckCHeader' function will use the 'ConfMsgChecking' and 'ConfMsgResult' functions to describe the test and the outcome. Example: <>  Node: Subsection 13-1-7, Next: Subsection 13-1-8, Prev: Subsection 13-1-6, Up: Section 13-1 13.1.7 CheckCLib, VerboseCheckCLib ==================================== <, ) success = $(VerboseCheckCLib , ) >> Use the 'TryLinkC' function to check whether your C compiler and linker can find the named functions when linking with the named libraries. Will pass the `' to the compiler using the `-l' flag. Both functions return a boolean value. The `CheckCLib' function is silent; the `VerboseCheckCHeader' function will use the 'ConfMsgChecking' and 'ConfMsgResult' functions to describe the test and the outcome. Example: <>  Node: Subsection 13-1-8, Next: Section 13-2, Prev: Subsection 13-1-7, Up: Section 13-1 13.1.8 CheckProg ================== `success = $(CheckProg )' Checks whether the program `' exists in your path. Will use the 'ConfMsgChecking' and 'ConfMsgResult' functions to describe the test and the outcome.  Node: Section 13-2, Next: Section 13-3, Prev: Section 13-1, Up: Chapter 13 13.2 Translating 'autoconf' scripts *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* Some of the functions described above are very similar to the ones present in `autoconf'. Below is a brief translation table for such functions. 'AC_MSG_CHECKING' is very similar to 'ConfMsgChecking' function. 'AC_MSG_RESULT' is very similar to 'ConfMsgResult' function. 'AC_MSG_WARN' is very similar to 'ConfMsgWarn' function. 'AC_MSG_ERROR' is very similar to 'ConfMsgError' function. 'AC_TRY_COMPILE' is somewhat similar to 'TryCompileC' function, except the 'TryCompileC' function returns a boolean value and only works for `C'. Similarly, 'AC_TRY_LINK' is approximated by 'TryLinkC' function, and 'AC_TRY_RUN' is approximated by 'TryRunC' function.  Node: Section 13-3, Next: Subsection 13-3-1, Prev: Section 13-2, Up: Chapter 13 13.3 Predefined configuration tests *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* A number of configuration tests are already included in the standard library. In order to use them in your project, simply `open' (see Section 4.7*Note Section 4-7::) the corresponding build file in your `OMakefile' and the tests will run the first time OMake is executed. Note that it is not a problem to `open' these files from more than one place in your project --- if you do that, the test will still run only once. * Menu: * Subsection 13-3-1:: NCurses library configuration * Subsection 13-3-2:: ReadLine library configuration * Subsection 13-3-3:: Snprintf configuration  Node: Subsection 13-3-1, Next: Subsection 13-3-2, Prev: Section 13-3, Up: Section 13-3 13.3.1 NCurses library configuration ====================================== Add `open configure/ncurses' line to your `OMakefile' to get access to the following autoconfiguration variables. NCURSES_AVAILABLE A boolean flag that would be set when both the `curses.h' header, the `term.h' header, and the `ncurses' library very found. NCURSES_TERMH_IN_NCURSES A boolean flag that would be set when `term.h' has to be included as `' instead of `'. NCURSES_CFLAGS The `CFLAGS' to use when compiling ncurses code. Will include `-DNCURSES' and `-DTERMH_IN_NCURSES', respectively when `NCURSES_AVAILABLE' and `NCURSES_TERMH_IN_NCURSES' are true. NCURSES_CLIBS The `LDFLAGS' to use when linking ncurses code. Will normally contain `-lncurses' when ncurses is found and remain empty otherwise.  Node: Subsection 13-3-2, Next: Subsection 13-3-3, Prev: Subsection 13-3-1, Up: Section 13-3 13.3.2 ReadLine library configuration ======================================= Add `open configure/readline' line to your `OMakefile' to get access to the following autoconfiguration variables. READLINE_AVAILABLE A boolean flag that would be set when both the `readline/readline.h' header, the `readline/history.h' header, and the `readline' library very found. READLINE_GNU A boolean flag that would be set when the GNU version of the readline library is found (as opposed to the BSD one). READLINE_CFLAGS The `CFLAGS' to use when compiling readline code. Will include `-DREADLINE_ENABLED' and `-DREADLINE_GNU', respectively when `READLINE_AVAILABLE' and `READLINE_GNU' are true. READLINE_CLIBS The `LDFLAGS' to use when linking readline code. Will normally contain `-lncurses -lreadline' when readline is found and remain empty otherwise.