--- name: "omake-root" section: "1" platform: "linux" package: "omake" version: "0.9.6.9-1-2" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/omake-root" --- # omake-root(1) ## NAME omake is a flexible build system designed for building a wide variety of projects. This document describes the standard build configuration defined in the system OMakeroot. For an overview of omake, see the [omake(1)](/omake/1.md) man page. ## BUILD FUNCTIONS ### 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 ``` ### 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. ### 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. ### 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. ## THE OMAKEROOT FILE The standard OMakeroot file defines the functions are rules for building standard projects. ### 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. - VERBOSE Whether certain commands should be verbose (false by default). - 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. ### 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). ## BUILDING C PROGRAMS omake provides extensive support for building C programs. ### 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). - 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). - AR The name of the program to create static libraries (defaults to ar cq on Unix, and lib on Win32). - AROUT The option string that specifies the output file for AR. - 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). - 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). ### 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. ### 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. ``` StaticCLibrary(libfoo, a b c) ``` ### 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. ``` StaticCLibraryCopy(install, /usr/lib, libfoo) ``` ### 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(\, \, \, \) ``` StaticCLibraryInstall(install, /usr/lib, libfoo, a b c) ``` ### 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). ### 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. ``` section LIBS = libfoo$(EXT_LIB) CProgram(foo, bar baz) ``` ### CPROGRAMCOPY The CProgramCopy function copies a file to an install location. CProgramCopy(\, \, \) ``` CProgramCopy(install, /usr/bin, foo) ``` ### CPROGRAMINSTALL The CProgramInstall function specifies a program to build, and a location to install, simultaneously. CProgramInstall(\, \, \, \) ``` section LIBS = libfoo$(EXT_LIB) CProgramInstall(install, /usr/bin, foo, bar baz) ``` ### 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). ## BUILDING OCAML PROGRAMS ### VARIABLES FOR OCAML PROGRAMS 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). - OCAMLDEP The OCaml dependency analyzer (default ocamldep). - 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. ### 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). - OCAMLINCLUDES Include path (default .). - 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. ### 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. ### OCAMLGENERATEDFILES, LOCALOCAMLGENERATEDFILES ``` OCamlGeneratedFiles(files) LocalOCamlGeneratedFiles(files) ``` 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. ### OCAMLLIBRARY The OCamlLibrary function builds an OCaml library. OCamlLibrary(\, \) The \ and \ are listed *without* suffixes. Additional variables used by the function: - ABORT\_ON\_DEPENDENCY\_ERRORS The linker requires that the files to be listed in dependency order. If this variable is true, the order of the files is determined by the command line, but omake will abort with an error message if the order is illegal. Otherwise, the files are sorted automatically. 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) ``` ### 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. ### OCAMLLIBRARYINSTALL The OCamlLibraryInstall function builds a library and copies it to an install location in one step. OCamlLibraryInstall(\, \, \, \) ### OCAMLPROGRAM The OCamlProgram function builds an OCaml program. It returns the array with all the targets for which it have 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. ### OCAMLPROGRAMCOPY The OCamlProgramCopy function copies an OCaml program to an install location. OCamlProgramCopy(\, \, \) Additional variables used: - NATIVE\_ENABLED If NATIVE\_ENABLED is set, the native-code executable is copied; otherwise the byte-code executable is copied. ### OCAMLPROGRAMINSTALL The OCamlProgramInstall function builds a programs and copies it to an install location in one step. OCamlProgramInstall(\, \, \, \) ## BUILDING LaTeX PROGRAMS ### 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 empty). - USEPDFLATEX Flag indicating whether to use pdflatex instead of dvipdfm to generate the .pdf document (default false). ### 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. ### 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. ### LATEXDOCUMENTCOPY The LaTeXDocumentCopy copies the document to an install location. LaTeXDocumentCopy(\, \, \, \) This function copies just the .pdf and .ps files. ### LATEXDOCUMENTINSTALL The LaTeXDocumentInstall builds a document and copies it to an install location in one step. LaTeXDocumentInstall(\, \, \, \, \) ## EXAMINING THE DEPENDENCY GRAPH ### DEPENDENCIES, DEPENDENCIES-ALL ``` $(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)) ``` ### TARGET ``` $(target targets) : Rule 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. ### 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 two-element array with an option name, and the option 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. ``` rule(false, target, pattern, sources, [[:name1:, option1], [:name2:, option2]] [expr1; expr2]) ``` ## REFERENCES ### SEE ALSO [omake(1)](/omake/1.md), [omake-quickstart(1)](/omake-quickstart/1.md), [omake-options(1)](/omake-options/1.md), [omake-root(1)](/omake-root/1.md), [omake-language(1)](/omake-language/1.md), [omake-shell(1)](/omake-shell/1.md), [omake-rules(1)](/omake-rules/1.md), [omake-base(1)](/omake-base/1.md), [omake-system(1)](/omake-system/1.md), [omake-pervasives(1)](/omake-pervasives/1.md), [osh(1)](/osh/1.md), [*make*(1)](/make/1.md) ### VERSION Version: 0.9.6.9 of April 11, 2006. ### LICENSE AND COPYRIGHT (C)2003-2006, Mojave Group, Caltech This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ### AUTHOR Jason Hickey *et. al.*.br Caltech 256-80\ Pasadena, CA 91125, USA\ Email: **omake-devel@metaprl.org**\ WWW: **http://www.cs.caltech.edu/~jyh**