Installing Batteries Included

The GODI package manager

At the moment, on most computers, the easiest manner of installing OCaml Batteries Included on your computer is to take advantage of GODI , a package manager specifically dedicated to OCaml. You will first need to install GODI, if GODI isn't install on your machine yet, then to select package batteries in the list of packages and accept the decisions of GODI. This should take care of installing OCaml Batteries Included for you.

Note that producing the documentation is long (typically 10-15 minutes).

Fedora / Debian / Red Hat / Ubuntu

At the time of this writing, this method is experimental.

On Fedora / Debian / Red Hat / Ubuntu stations, packages may be able for Batteries. If this is the case, to install OCaml Batteries Included, just run your usual package manager (generally either Synaptic, Yum, KPackage, Aptitude or DSelect), and select package libbatteries-ocaml-dev. This should take care of installing OCaml Batteries Included for you.

Manually

To perform installation of OCaml Batteries Included manually, please make sure that you have already installed all the following tools and libraries:

Once all these libraries are installed, you may download and uncompress the latest version of OCaml Batteries Included, enter the directory produced by decompression and invoke

make byte opt doc install
to build and install both the byte-code version, the native version and the documentation of OCaml Batteries Included. If you are not interested in respectively the byte-code version, the native version or the documentation of OCaml Batteries Included, just omit respectively byte, opt or doc from that command.

Note that producing the documentation is long (typically 10-15 minutes).

Using Batteries Included

Interactive environment

To launch the toplevel, from a shell, invoke
ocamlfind batteries/ocaml , or, if you have rlwrap installed, rlwrap ocamlfind batteries/ocaml , for more comfortable editting.
This technique also works from your favorite OCaml-compatible editor (Emacs, Vim, etc.)

Individual files

OCaml Batteries Included provides drop-in replacement for the compilation tools tools you use to compile or execute individual OCaml files. To invoke these:
Interpreter
To execute a file called date.ml, invoke ocamlfind batteries/ocaml date.ml. You may also invoke ocamlfind batteries/ocaml --help for more informations on the interpreter.
Bytecode compiler
To compile a file called date.ml, invoke ocamlfind batteries/ocamlc date.ml. You may also invoke ocamlfind batteries/ocamlc --help for more informations on the bytecode compiler.
Optimizing compiler
To compile a file called date.ml, invoke ocamlfind batteries/ocamlopt date.ml. You may also invoke ocamlfind batteries/ocamlopt --help for more informations on the optimizing compiler.
Profiling compiler
To compile a file called date.ml, invoke ocamlfind batteries/ocamlcp date.ml. You may also invoke ocamlfind batteries/ocamlcp --help for more informations on the profiling compiler.

Complete projects (easiest technique)

OCaml Batteries Included also provides drop-in replacement for OCamlBuild, the standard tool used to compile complete projects.
Bytecode compilation
To compile a file called date.ml and all the files it requires to bytecode, invoke ocamlfind batteries/ocamlbuild date.byte.
Optimized compilation
To compile a file called date.ml and all the files it requires to an optimized native binary, invoke ocamlfind batteries/ocamlbuild date.native.
For more informations on OCamlBuild, you may read the official documentation.

More control

File doc/batteries/myocamlbuild.ml is an extension of OCamlBuild. It defines tags, which you may use in your projects to specify that your project should take advantage of the various features of Batteries Included. Copying this file to your project directory is required to take advantage of these tags.
The tags defined by Batteries Included are:
use_batteries
Use Batteries Included both as a library and to extend the OCaml language.
use_batteries_r
Use Batteries Included both as a library and to extend the OCaml language -- in revised syntax.
pkg_threads
Allow threading. Required to use module Control.Concurrency.Threads.
pkg_batteries
Use Batteries Included only as a library. No language extension is involved. To use the features of Batteries Included with pkg_batteries, you need to start your files with open Batteries.
use_boilerplate
Use only the syntax extensions necessary to automatically generate boiler-plate code. These syntax extensions are not added by default when performing use_batteries as they can suddenly turn correct code into something which doesn't compile. Use tag use_boilerplate in conjunction with either use_batteries or use_batteries_r.
To take advantage of a tag for a file or a set of files, you need to add this tag to a speciale file named _tags, placed in the same directory as your files. For instance, to have my_file.ml compiled with Batteries Included as a library and my_other_file.ml compiled with both the library, the language extensions and boiler-plate code, your file _tags should read:
<my_file.ml>: pkg_batteries
<my_other_file.ml>: use_batteries,use_boilerplate
The order of lines doesn't matter, nor does the order of tags on one line. For more informations on myocamlbuild.ml and _tags, see the documentation of OCamlBuild.

Even more control

During its installation, Batteries Included creates a set of findlib packages:
batteries
The main package for Batteries Included. In turn, this package defines subpackages
batteries.pa_openin.syntax
A language extension adding new possibilities for the opening of modules.
batteries.pa_type_conv.syntax
A language extension adding boiler-plate possibilities.
batteries.pa_where.syntax
A language extension adding a construction where dual to let.
batteries.pa_batteries.syntax
A language extension for automatically opening module Batteries.
batteries.pa_comprehension.syntax
A language extension for list comprehension.
batteries.pa_strings.syntax
A language extension added the ability to declare and pattern-match against new kinds of strings.
batteries_threads
You will probably never need to manipulate this package yourself. It is automatically linked to your files when you use both package batteries and package threads.
batteries_nothreads
You will probably never need to manipulate this package yourself. It is automatically linked to your files when you use package batteries without using package threads.
For more information on how to use these packages, please see the documentation of findlib.

Another method (using OMake)

Building a project with OMake is fairly simple. You just need to take advantage of OMake's built-in findlib support by adding the following to your OMakefile:
USE_OCAMLFIND = true

OCAMLPACKS[] +=
   batteries.pa_openin.syntax
   batteries.pa_where.syntax
   batteries.pa_batteries.syntax
   batteries.pa_comprehension.syntax
   batteries.pa_type_conv.syntax
   batteries.pa_strings.syntax
   batteries

OCAMLDEPFLAGS += -syntax camlp4o
OCAMLFLAGS += -syntax camlp4o
Here's a complete OMakefile for building the "cat" implementation you will find under the examples/ subdirectory:
USE_OCAMLFIND = true

OCAMLPACKS[] +=
   batteries.pa_openin.syntax
   batteries.pa_where.syntax
   batteries.pa_batteries.syntax
   batteries

OCAMLDEPFLAGS += -syntax camlp4o
OCAMLFLAGS += -syntax camlp4o

OCamlProgram(cat, cat)
The above OCAMLPACKS definition uses Batteries and all the non-destructive syntax extensions available as of 2008-11-16; this corresponds to the use_batteries tag in ocamlbuild. If you only want to use Batteries as a library, without syntax extensions, use
OCAMLPACKS[] += batteries
and drop the OCAMLDEPFLAGS and OCAMLFLAGS lines in the above examples, as they are no longer needed.