OMAKE-ROOT(1)                    Build Tools                     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) man page.


BUILD FUNCTIONS
   OMAKEFLAGS
          OMakeFlags(options)
             options : String


       The OMakeFlags function is used to set omake options from within OMake-
       files.  The options have exactly the same format as options on the com-
       mand 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
       <version1>,  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 nega-
       tive 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  build-
       ing 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_ERRORS
              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  abnor-
                     mally.



   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 /nol-
              ogo).

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


   STATICCLIBRARY
       The StaticCLibrary builds a static library.

       StaticCLibrary(<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
       and EXT_OBJ variables.

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

       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.

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

       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(<name>, <files>)

       The  <name> argument specifies the name of the program to be built; the
       <files> argument specifies the files to be linked.

       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(<tag>, <dir>, <program>)

       CProgramCopy(install, /usr/bin, foo)


   CPROGRAMINSTALL
       The  CProgramInstall function specifies a program to build, and a loca-
       tion to install, simultaneously.

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

       section
          LIBS = libfoo$(EXT_LIB)
          CProgramInstall(install, /usr/bin, foo, bar baz)


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 true\ if ocamlfind
              exists, false\ otherwise).

       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_OCAM-
              LINCLUDES 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 depen-
              dencies 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.


   OCAMLLIBRARY
       The OCamlLibrary function builds an OCaml library.

       OCamlLibrary(<libname>, <files>)

       The <libname> and <files> 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.

       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(<tag>, <libdir>, <libname>, <interface-files>)

       The  <interface-files>  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(<tag>, <libdir>, <libname>, <files>)

   OCAMLPROGRAM
       The OCamlProgram function builds an OCaml program.

       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.


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

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

       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(<tag>, <bindir>, <name>, <files>)

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(<name>, <texfiles>)

       The document <name> and <texfiles> are listed without suffixes.

       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.


   LATEXDOCUMENTCOPY
       The LaTeXDocumentCopy copies the document to an install location.

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

       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(<tag>,    <libdir>,    <installname>,   <docname>,
       <files>)

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 dependen-
       cies  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  dependen-
       cies  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 tar-
       get that has no dependencies and no build commands; a leaf target  cor-
       responds 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''  tar-
       gets.  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-quickstart(1),    omake-options(1),   omake-root(1),
       omake-language(1),   omake-shell(1),   omake-rules(1),   omake-base(1),
       omake-system(1), omake-pervasives(1), osh(1), make(1)


   VERSION
       Version: 0.9.6.7 of December 28, 2005.


   LICENSE AND COPYRIGHT
       (C)2003-2005, Jason Hickey, Caltech 256-80, Pasadena, CA 91125, USA

       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 MER-
       CHANTABILITY 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
       Caltech 256-80
       Pasadena, CA 91125, USA
       Email: jyh@cs.caltech.edu
       WWW: http://www.cs.caltech.edu/~jyh




Build Tools                    December 28, 2005                 OMAKE-ROOT(1)
