This file has been translated from LaTeX by HeVeA.

File: omake-doc, Node: Subsection 13-3-1,	Next: Subsection 13-3-2,	Up: Section 13-3


13.3.1  dependencies, dependencies-all, dependencies-proper
===========================================================
\@name
{hevea_fun258}
<<   $(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*Note Subsection 10-3-3:: and 'filter-proper-targets'
function. 

File: omake-doc, Node: Subsection 13-3-2,	Next: Subsection 13-3-3,	Prev: Subsection 13-3-1,	Up: Section 13-3


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. 

File: omake-doc, Node: Subsection 13-3-3,	Next: Subsection 13-3-4,	Prev: Subsection 13-3-2,	Up: Section 13-3


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*Note Section 13-1::) and .BUILD_FAILURE
(Section 13.1*Note 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))"
>>


File: omake-doc, Node: Subsection 13-3-4,	Next: Subsection 13-3-5,	Prev: Subsection 13-3-3,	Up: Section 13-3


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. 

File: omake-doc, Node: Subsection 13-3-5,	Next: Subsection 13-3-6,	Prev: Subsection 13-3-4,	Up: Section 13-3


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


File: omake-doc, Node: Subsection 13-3-6,	Prev: Subsection 13-3-5,	Up: Section 13-3


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.  

File: omake-doc, Node: Section 13-4,	Next: Section 13-5,	Prev: Section 13-3,	Up: Chapter 13


13.4  The OMakeroot file
************************

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

* Subsection 13-4-1::	Variables
* Subsection 13-4-2::	System variables


File: omake-doc, Node: Subsection 13-4-1,	Next: Subsection 13-4-2,	Up: Section 13-4


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. 


File: omake-doc, Node: Subsection 13-4-2,	Prev: Subsection 13-4-1,	Up: Section 13-4


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

File: omake-doc, Node: Section 13-5,	Next: Section 13-6,	Prev: Section 13-4,	Up: Chapter 13


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.
* Menu:

* Subsection 13-5-1::	Autoconfiguration variables
* Subsection 13-5-2::	C and C++ configuration variables
* Subsection 13-5-3::	Generated C files
* Subsection 13-5-4::	Building C programs and Libraries


File: omake-doc, Node: Subsection 13-5-1,	Next: Subsection 13-5-2,	Up: Section 13-5


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


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.

File: omake-doc, Node: Subsection 13-5-2,	Next: Subsection 13-5-3,	Prev: Subsection 13-5-1,	Up: Section 13-5


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

File: omake-doc, Node: Subsection 13-5-3,	Next: Subsection 13-5-4,	Prev: Subsection 13-5-2,	Up: Section 13-5


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.

File: omake-doc, Node: Subsection 13-5-4,	Prev: Subsection 13-5-3,	Up: Section 13-5


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
-------------------------------------------------
\@nam
e{hevea_fun269}
  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
----------------------------------------------------------------
\@n
ame{hevea_fun274}
  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
---------------------------------------
\
@name{function: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
------------------------
\@name
{hevea_fun281}\@
name{hevea_default497}
  Similarly, the six CXXLibrary functions the C++ equivalents of the
corresponding CLibrary functions. 

File: omake-doc, Node: Section 13-6,	Next: Section 13-7,	Prev: Section 13-5,	Up: Chapter 13


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.
* Menu:

* Subsection 13-6-1::	Autoconfiguration variables for OCaml compilation
* Subsection 13-6-2::	Configuration variables for OCaml compilation
* Subsection 13-6-3::	OCaml command flags
* Subsection 13-6-4::	Library variables
* Subsection 13-6-5::	Generated OCaml Files
* Subsection 13-6-6::	Using the Menhir parser generator
* Subsection 13-6-7::	Building OCaml programs and Libraries


File: omake-doc, Node: Subsection 13-6-1,	Next: Subsection 13-6-2,	Up: Section 13-6


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

File: omake-doc, Node: Subsection 13-6-2,	Next: Subsection 13-6-3,	Prev: Subsection 13-6-1,	Up: Section 13-6


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*Note Subsection 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 

File: omake-doc, Node: Subsection 13-6-3,	Next: Subsection 13-6-4,	Prev: Subsection 13-6-2,	Up: Section 13-6


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. 

File: omake-doc, Node: Subsection 13-6-4,	Next: Subsection 13-6-5,	Prev: Subsection 13-6-3,	Up: Section 13-6


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.

File: omake-doc, Node: Subsection 13-6-5,	Next: Subsection 13-6-6,	Prev: Subsection 13-6-4,	Up: Section 13-6


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. 

File: omake-doc, Node: Subsection 13-6-6,	Next: Subsection 13-6-7,	Prev: Subsection 13-6-5,	Up: Section 13-6


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


File: omake-doc, Node: Subsection 13-6-7,	Prev: Subsection 13-6-6,	Up: Section 13-6


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

File: omake-doc, Node: Section 13-7,	Prev: Section 13-6,	Up: Chapter 13


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.
* Menu:

* Subsection 13-7-1::	Configuration variables
* Subsection 13-7-2::	Building LaTeX documents


File: omake-doc, Node: Subsection 13-7-1,	Next: Subsection 13-7-2,	Up: Section 13-7


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

File: omake-doc, Node: Subsection 13-7-2,	Prev: Subsection 13-7-1,	Up: Section 13-7


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
---------------------------------------------------
\@n
ame{hevea_fun300} 
<<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>)  

File: omake-doc, Node: Chapter 14,	Next: Chapter 15,	Prev: Chapter 13,	Up: Top


Chapter 14   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 14-1::	General-purpose autoconfiguration functions
* Section 14-2::	Translating 'autoconf' scripts
* Section 14-3::	Predefined configuration tests


File: omake-doc, Node: Section 14-1,	Next: Section 14-2,	Up: Chapter 14


14.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.15*Note Section 4-15:: for more information).
  In order to use the following general-purpose functions, you need to
have the line 
<<open configure/Configure
>>
   included in your OMakefile or OMakeroot. 
* Menu:

* Subsection 14-1-1::	ConfMsgChecking, ConfMsgResult
* Subsection 14-1-2::	ConfMsgWarn, ConfMsgError
* Subsection 14-1-3::	ConfMsgYesNo, ConfMsgFound
* Subsection 14-1-4::	TryCompileC, TryLinkC, TryRunC
* Subsection 14-1-5::	RunCProg
* Subsection 14-1-6::	CheckCHeader, VerboseCheckCHeader
* Subsection 14-1-7::	CheckCLib, VerboseCheckCLib
* Subsection 14-1-8::	CheckProg


File: omake-doc, Node: Subsection 14-1-1,	Next: Subsection 14-1-2,	Up: Section 14-1


14.1.1  ConfMsgChecking, ConfMsgResult
======================================
 
<<ConfMsgChecking(<msg>)
  ...
  ConfMsgResult(<msg>)
>>
   The ConfMsgChecking function output message of the form --- Checking
<msg>...  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: 
<<static. =
     ConfMsgChecking(which foo to use)
     foo = ...
     ConfMsgResult($(foo))
>>


File: omake-doc, Node: Subsection 14-1-2,	Next: Subsection 14-1-3,	Prev: Subsection 14-1-1,	Up: Section 14-1


14.1.2  ConfMsgWarn, ConfMsgError
=================================

 
<<ConfMsgWarn(<msg>)
  ConfMsgError(<msg>)
>>

  Print a warning or an error message respectively. ConfMsgError would
then abort OMake. 

File: omake-doc, Node: Subsection 14-1-3,	Next: Subsection 14-1-4,	Prev: Subsection 14-1-2,	Up: Section 14-1


14.1.3  ConfMsgYesNo, ConfMsgFound
==================================
 
<<flag = $(ConfMsgYesNo <bool expr>
  flag = $(ConfMsgFound <bool expr>
>>

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

File: omake-doc, Node: Subsection 14-1-4,	Next: Subsection 14-1-5,	Prev: Subsection 14-1-3,	Up: Section 14-1


14.1.4  TryCompileC, TryLinkC, TryRunC
======================================

\@n
ame{function:TryRunC} 
<<success = $(TryCompileC <prog_text>)
  success = $(TryLinkC <prog_text>)
  success = $(TryRunC <prog_text>)
>>

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

File: omake-doc, Node: Subsection 14-1-5,	Next: Subsection 14-1-6,	Prev: Subsection 14-1-4,	Up: Section 14-1


14.1.5  RunCProg
================
 
<<output = $(RunCProg <prog>)
>>

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

File: omake-doc, Node: Subsection 14-1-6,	Next: Subsection 14-1-7,	Prev: Subsection 14-1-5,	Up: Section 14-1


14.1.6  CheckCHeader, VerboseCheckCHeader
=========================================
 
<<success = $(CheckCHeader <files>)
  success = $(VerboseCheckCHeader <files>)
>>

  Use the 'TryCompileC' function to check whether your C compiler can
locate and process the specified headers files. Will incude <stdio.h>
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: 
<<static. =
     NCURSES_H_AVAILABLE = $(VerboseCheckCHeader ncurses.h)
>>


File: omake-doc, Node: Subsection 14-1-7,	Next: Subsection 14-1-8,	Prev: Subsection 14-1-6,	Up: Section 14-1


14.1.7  CheckCLib, VerboseCheckCLib
===================================
\@
name{function:VerboseCheckCLib} 
<<success = $(CheckCLib <libs>, <functions>)
  success = $(VerboseCheckCLib <libs>, <functions>)
>>

  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 <libs> 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: 
<<static. =
      NCURSES_LIB_AVAILABLE = $(VerboseCheckCLib ncurses, initscr
setupterm tigetstr)
>>


File: omake-doc, Node: Subsection 14-1-8,	Prev: Subsection 14-1-7,	Up: Section 14-1


14.1.8  CheckProg
=================

success = $(CheckProg <prog>)
  Checks whether the program <prog> exists in your path. Will use the
'ConfMsgChecking' and 'ConfMsgResult' functions to describe the test and
the outcome.

File: omake-doc, Node: Section 14-2,	Next: Section 14-3,	Prev: Section 14-1,	Up: Chapter 14


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


File: omake-doc, Node: Section 14-3,	Prev: Section 14-2,	Up: Chapter 14


14.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.8*Note Section 4-8::) 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 14-3-1::	NCurses library configuration
* Subsection 14-3-2::	ReadLine library configuration
* Subsection 14-3-3::	Snprintf configuration


File: omake-doc, Node: Subsection 14-3-1,	Next: Subsection 14-3-2,	Up: Section 14-3


14.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 <ncurses/term.h> instead of
<term.h>.
 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. 

File: omake-doc, Node: Subsection 14-3-2,	Next: Subsection 14-3-3,	Prev: Subsection 14-3-1,	Up: Section 14-3


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

File: omake-doc, Node: Subsection 14-3-3,	Prev: Subsection 14-3-2,	Up: Section 14-3


14.3.3  Snprintf configuration
==============================
   Add open configure/snprintf line to your OMakefile to get access to
the following autoconfiguration variables. 
 SNPRINTF_AVAILABLE
 A boolean flag telling
whether the snprintf function is available in the standard C library.


File: omake-doc, Node: Chapter 15,	Next: Appendix A,	Prev: Chapter 14,	Up: Top


Chapter 15   The OSH shell
**************************
    
  OMake also includes a standalone command-line interpreter osh that can
be used as an interactive shell. The shell uses the same syntax, and
provides the same features on all platforms omake supports, including
Win32.
* Menu:

* Section 15-1::	Startup
* Section 15-2::	Aliases
* Section 15-3::	Interactive syntax


File: omake-doc, Node: Section 15-1,	Next: Section 15-2,	Up: Chapter 15


15.1  Startup
*************


  On startup, osh reads the file ~/.oshrc if it exists. The syntax of
this file is the same as an OMakefile. The following additional
variables are significant.
 prompt
 The prompt variable
specifies the command-line prompt. It can be a simple string.
<<    prompt = osh>
>>

  Or you may choose to define it as a function of no arguments.
<<    prompt() =
          return $"<$(USER):$(HOST) $(homename $(CWD))>"
>>

  An example of the latter prompt is as follows.
<<    <jyh:kenai.yapper.org ~>cd links/omake
      <jyh:kenai.yapper.org ~/links/omake>
>>

  If you include any "invisible" text in the prompt (such as various
terminal escape sequences), they must be wrapped using the
'prompt-invisible' function. For example, to create a bold prompt on
terminals that support it, you can use the following. 
<<    prompt =
         bold-begin = $(prompt-invisible $(tgetstr bold))
         bold-end = $(prompt-invisible $(tgetstr sgr0))
         value $(bold-begin)$"osh>"$(bold-end)
>>

 ignoreeof
 If the ignoreeof is true,
then osh will not exit on a terminal end-of-file (usually ^D on Unix
systems).
