2015-06-30 01:05:29 -07:00
|
|
|
OCAML DOCUMENTATION
|
|
|
|
===================
|
|
|
|
|
|
|
|
Prerequisites
|
|
|
|
-------------
|
|
|
|
|
|
|
|
- Any prerequisites required to build OCaml from sources.
|
|
|
|
|
|
|
|
- A LaTeX installation.
|
|
|
|
|
Fixing typos in various files (#2246)
Note: Typos found with https://github.com/codespell-project/codespell
Here is the (semi-manual) command used to get (and correct) the typos:
$ codespell -i 3 -w --skip=".png,.gif,./ocaml/boot,./ocaml/.git,./ocaml/manual/styles,./ocaml/manual/manual/htmlman" -L minimise,instal,contructor,"o'caml",cristal,pres,clos,cmo,uint,iff,te,objext,nto,nd,mut,upto,larg,exten,leage,mthod,delte,tim,atleast,langage,hten,iwth,mke,contant,succint,methids,eles,valu,clas,modul,que,classe,missings,froms,defaut,correspondance,differents,configury,reachs,cas,approche,normale,dur,millon,amin,oje,transfert
2019-02-13 05:04:56 -08:00
|
|
|
- The HeVeA LaTeX-to-HTML converter (available in OPAM):
|
2015-06-30 01:05:29 -07:00
|
|
|
<http://hevea.inria.fr/>
|
|
|
|
|
|
|
|
Note that you must make sure `hevea.sty` is installed into TeX properly. Your
|
|
|
|
package manager may not do this for you. Run `kpsewhich hevea.sty` to check.
|
|
|
|
|
|
|
|
|
|
|
|
Building
|
|
|
|
--------
|
|
|
|
|
2015-11-28 23:41:31 -08:00
|
|
|
0. Install the OCaml distribution.
|
2015-06-30 01:05:29 -07:00
|
|
|
|
2015-11-28 23:41:31 -08:00
|
|
|
1. Run `make` in the manual.
|
2015-11-20 02:23:35 -08:00
|
|
|
|
|
|
|
NB: If you already set `LD_LIBRARY_PATH` (OS X: `DYLD_LIBRARY_PATH`)
|
2016-05-03 08:23:37 -07:00
|
|
|
in your environment don't forget to add
|
2015-11-20 02:23:35 -08:00
|
|
|
`otherlibs/unix:otherlibs/str` to it in an absolute way.
|
2015-06-30 01:05:29 -07:00
|
|
|
|
|
|
|
Outputs
|
|
|
|
-------
|
|
|
|
|
|
|
|
In the manual:
|
|
|
|
|
|
|
|
- The HTML Manual is in directory `htmlman`. The main file is `index.html`.
|
|
|
|
|
2016-07-13 11:50:20 -07:00
|
|
|
- The plain text manual is in directory `textman` as file `manual.txt`.
|
2015-06-30 01:05:29 -07:00
|
|
|
|
|
|
|
- The Info manual is in directory `infoman`.
|
|
|
|
|
2018-06-26 02:15:39 -07:00
|
|
|
- The PDF manual is in directory `texstuff` as file `manual.pdf`.
|
2015-06-30 01:05:29 -07:00
|
|
|
|
2016-07-13 11:50:20 -07:00
|
|
|
Source files
|
|
|
|
------------
|
|
|
|
The manual is written in an extended dialect of latex and is split in many
|
|
|
|
source files. During the build process, the sources files are converted into
|
|
|
|
classical latex file using the tools available in `tools`. These files are
|
|
|
|
then converted to the different output formats using either latex or hevea.
|
|
|
|
|
|
|
|
Each part of the manual corresponds to a specific directory, and each distinct
|
|
|
|
chapters (or sometimes sections) are mapped to a distinct `.etex` file:
|
|
|
|
|
|
|
|
- Part I, Introduction to OCaml: `tutorials`
|
|
|
|
- The core language: `coreexamples.etex`
|
|
|
|
- The module system: `moduleexamples.etex`
|
|
|
|
- Objects in OCaml: `objectexamples.etex`
|
|
|
|
- Labels and variants: `lablexamples.etex`
|
|
|
|
- Advanced examples with classes and modules: `advexamples.etex`
|
|
|
|
|
|
|
|
- Part II, The OCaml language: `refman`
|
|
|
|
This part is separated in two very distinct chapters; the
|
|
|
|
`OCaml language` chapter and the `Language extensions` chapter.
|
|
|
|
|
|
|
|
- The OCaml language: `refman.etex`
|
|
|
|
This chapter consists in a technical description of the OCaml language.
|
|
|
|
Each section of this chapter is mapped to a separated latex file:
|
|
|
|
- `lex.etex`, `values.etex`, `names.etex`, `types.etex`, `const.etex`,
|
|
|
|
`patterns.etex`, `expr.etex`, `typedecl.etex`, `classes.etex`,
|
|
|
|
`modtypes.etex`, `compunit.etex`
|
|
|
|
|
|
|
|
- Language extensions: `exten.etex`
|
|
|
|
This chapter contains a description of all recent features of the OCaml
|
|
|
|
language.
|
|
|
|
|
|
|
|
- Part III, The OCaml tools: 'cmds'
|
|
|
|
- Batch compilation (ocamlc): `comp.etex`
|
|
|
|
- The toplevel system (ocaml): `top.etex`
|
|
|
|
- The runtime system (ocamlrun): `runtime.etex`
|
|
|
|
- Native-code compilation (ocamlopt): `native.etex`
|
|
|
|
- Lexer and parser generators (ocamllex, ocamlyacc): `lexyacc.etex`
|
2016-07-15 17:14:45 -07:00
|
|
|
- Dependency generator (ocamldep): `ocamldep.etex`
|
2016-07-13 11:50:20 -07:00
|
|
|
- The browser/editor (ocamlbrowser): `browser.etex`
|
2016-07-15 17:14:45 -07:00
|
|
|
- The documentation generator (ocamldoc): `ocamldoc.etex`
|
2016-07-13 11:50:20 -07:00
|
|
|
- The debugger (ocamldebug): `debugger.etex`
|
|
|
|
- Profiling (ocamlprof): `profil.etex`
|
|
|
|
- The ocamlbuild compilation manager: `ocamlbuild.etex`
|
|
|
|
- Interfacing C with OCaml: `intf-c.etex`
|
|
|
|
- Optimisation with Flambda: `flambda.etex`
|
2016-12-06 08:18:04 -08:00
|
|
|
- Fuzzing with afl-fuzz: `afl-fuzz.etex`
|
2020-05-05 07:51:53 -07:00
|
|
|
- Runtime tracing with the instrumented runtime: `instrumented-runtime.etex`
|
2016-07-13 11:50:20 -07:00
|
|
|
|
2016-03-02 09:38:52 -08:00
|
|
|
Note that ocamlc,ocamlopt and the toplevel options overlap a lot.
|
|
|
|
Consequently, these options are described together in the file
|
|
|
|
`unified-options.etex` and then included from `comp.etex`, `native.etex`,
|
|
|
|
and `top.etex`. If you need to update this list of options, the top comment
|
|
|
|
of `unified-options.etex` contains the relevant information.
|
|
|
|
|
2019-04-06 10:45:41 -07:00
|
|
|
- Part IV, The OCaml library: 'library'
|
2016-07-13 11:50:20 -07:00
|
|
|
This parts contains an brief presentation of all libraries bundled with the
|
|
|
|
compilers and the api documentation generated for these libraries.
|
|
|
|
- The core library: `core.etex`
|
2019-06-25 05:44:54 -07:00
|
|
|
- The standard library: `stdlib-blurb.etex`
|
2016-07-13 11:50:20 -07:00
|
|
|
- The compiler front-end: `compilerlibs.etex`
|
|
|
|
- The unix library: Unix system calls: `libunix.etex`
|
2017-08-19 05:17:58 -07:00
|
|
|
- The legacy num library: this library has been removed from the core
|
|
|
|
distribution, see `libnum.etex`
|
2016-07-13 11:50:20 -07:00
|
|
|
- The str library: regular expressions and string processing: `libstr.etex`
|
|
|
|
- The threads library: `libthreads.etex`
|
|
|
|
- The graphics library: `libgraph.etex`
|
|
|
|
- The dynlink library: dynamic loading and linking of object files:
|
|
|
|
`libdynlink.etex`
|
|
|
|
- The bigarray library: `libbigarray.etex`
|
|
|
|
|
|
|
|
Latex extensions
|
|
|
|
----------------
|
|
|
|
|
2019-12-06 01:08:40 -08:00
|
|
|
### Sections (and subsections, and subsubsections)
|
|
|
|
|
|
|
|
In order to provide stable links to all part of the manual, the standard
|
|
|
|
`\section`, `\subsection` and `\subsubsection` macros are replaced by
|
|
|
|
variants that take the section label as their first argument.
|
|
|
|
For instance, in the manual, you have to write
|
|
|
|
```latex
|
|
|
|
\section{s:basics}{Basics}
|
|
|
|
```
|
|
|
|
rather than
|
|
|
|
```latex
|
|
|
|
\section{Basics\label{s:basics}}
|
|
|
|
```
|
|
|
|
This restriction ensures that hevea picks the section label when generating the
|
|
|
|
header ids.
|
|
|
|
|
|
|
|
A similar macro, `\lparagraph`, is provided for paragraphs.
|
|
|
|
|
2018-01-05 13:36:29 -08:00
|
|
|
### Caml environments
|
|
|
|
|
2018-07-25 01:38:08 -07:00
|
|
|
The tool `tools/caml-tex` is used to generate the latex code for the examples
|
2016-11-28 11:18:03 -08:00
|
|
|
in the introduction and language extension parts of the manual. It implements
|
|
|
|
two pseudo-environments: `caml_example` and `caml_eval`.
|
2016-07-13 11:50:20 -07:00
|
|
|
|
|
|
|
The pseudo-environment `caml_example` evaluates its contents using an ocaml
|
|
|
|
interpreter and then translates both the input code and the interpreter output
|
|
|
|
to latex code, e.g.
|
|
|
|
```latex
|
2017-06-07 09:25:41 -07:00
|
|
|
\begin{caml_example}{toplevel}
|
2016-07-15 17:14:45 -07:00
|
|
|
let f x = x;;
|
2016-07-13 11:50:20 -07:00
|
|
|
\end{caml_example}
|
|
|
|
```
|
|
|
|
Note that the toplevel output can be suppressed by using a `*` suffix:
|
|
|
|
```latex
|
2017-06-07 09:25:41 -07:00
|
|
|
\begin{caml_example*}{verbatim}
|
|
|
|
let f x = x
|
2016-07-13 11:50:20 -07:00
|
|
|
\end{caml_example*}
|
|
|
|
```
|
2017-06-07 09:25:41 -07:00
|
|
|
|
2018-10-15 13:19:46 -07:00
|
|
|
The {verbatim} or {toplevel} argument of the environment corresponds
|
|
|
|
to the the mode of the example, three modes are available toplevel, verbatim and signature.
|
2017-06-07 09:25:41 -07:00
|
|
|
The `toplevel` mode mimics the appearance and behavior of the toplevel.
|
|
|
|
In particular, toplevel examples must end with a double semi-colon `;;`,
|
|
|
|
otherwise an error would be raised.
|
|
|
|
The `verbatim` does not require a final `;;` and is intended to be
|
|
|
|
a lighter mode for code examples.
|
2018-10-15 13:19:46 -07:00
|
|
|
If you want to declare a signature instead of ocaml code,
|
|
|
|
you must use the `{signature}` argument to the `caml_example` environment.
|
|
|
|
|
|
|
|
```latex
|
|
|
|
\begin{caml_example*}{signature}
|
|
|
|
val none : 'a option
|
|
|
|
\end{caml_example*}
|
|
|
|
```
|
2017-06-07 09:25:41 -07:00
|
|
|
|
2018-07-25 01:38:08 -07:00
|
|
|
By default, `caml-tex` raises an error and stops if the output of one
|
2016-07-15 17:14:45 -07:00
|
|
|
the `caml_example` environment contains an unexpected error or warning.
|
|
|
|
If such an error or warning is, in fact, expected, it is necessary to
|
2018-07-25 01:38:08 -07:00
|
|
|
indicate the expected output status to `caml-tex` by adding either
|
2016-07-15 17:14:45 -07:00
|
|
|
an option to the `caml_example` environment:
|
|
|
|
```latex
|
2017-06-07 09:25:41 -07:00
|
|
|
\begin{caml_example}{toplevel}[error]
|
2016-07-15 17:14:45 -07:00
|
|
|
1 + 2. ;;
|
|
|
|
\end{caml_example}
|
|
|
|
or for warning
|
|
|
|
\begin{caml_example}[warning=8]
|
|
|
|
let f None = None;;
|
|
|
|
\end{caml_example}
|
|
|
|
```
|
|
|
|
or an annotation to the concerned phrase:
|
|
|
|
|
|
|
|
```latex
|
2017-06-07 09:25:41 -07:00
|
|
|
\begin{caml_example}{toplevel}
|
2016-07-15 17:14:45 -07:00
|
|
|
1 + 2. [@@expect error] ;;
|
|
|
|
let f None = None [@@expect warning 8];;
|
|
|
|
3 + 4 [@@expect ok];;
|
|
|
|
\end{caml_example}
|
|
|
|
```
|
|
|
|
|
2018-05-06 09:11:54 -07:00
|
|
|
It is also possible to elide a code fragment by annotating it with
|
|
|
|
an `[@ellipsis]` attribute
|
|
|
|
|
|
|
|
```latex
|
|
|
|
\begin{caml_example}{toplevel}
|
|
|
|
let f: type a. a list -> int = List.length[@ellipsis] ;;
|
|
|
|
\end{caml_example}
|
|
|
|
```
|
|
|
|
For module components, it might be easier to hide them by using
|
|
|
|
`[@@@ellipsis.start]` and `[@@@ellipsis.stop]`:
|
|
|
|
```latex
|
|
|
|
\begin{caml_example*}{verbatim}
|
|
|
|
module M = struct
|
|
|
|
[@@@ellipsis.start]
|
|
|
|
type t = T
|
|
|
|
let x = 0
|
|
|
|
[@@@ellipsis.stop]
|
|
|
|
end
|
|
|
|
\end{caml_example*}
|
|
|
|
```
|
|
|
|
|
|
|
|
Another possibility to avoid displaying distracting code is to use
|
|
|
|
the `caml_eval` environment. This environment is a companion environment
|
|
|
|
to `caml_example` and can be used to evaluate OCaml expressions in the
|
|
|
|
toplevel without printing anything:
|
2016-07-13 11:50:20 -07:00
|
|
|
```latex
|
|
|
|
\begin{caml_eval}
|
2017-06-07 06:21:41 -07:00
|
|
|
let pi = 4. *. atan 1.;;
|
2016-07-13 11:50:20 -07:00
|
|
|
\end{caml_eval}
|
2017-06-07 09:25:41 -07:00
|
|
|
\begin{caml_example}{toplevel}
|
2017-06-07 06:21:41 -07:00
|
|
|
let f x = x +. pi;;
|
2016-07-13 11:50:20 -07:00
|
|
|
\end{caml_example}
|
|
|
|
```
|
|
|
|
Beware that the detection code for these pseudo-environments is quite brittle
|
|
|
|
and the environments must start and end at the beginning of the line.
|
|
|
|
|
2018-01-05 13:36:29 -08:00
|
|
|
### Quoting
|
|
|
|
|
2016-07-13 11:50:20 -07:00
|
|
|
The tool `tools/texquote2` provides support for verbatim-like quotes using
|
|
|
|
`\"` delimiters. More precisely, outside of caml environments and verbatim
|
|
|
|
environments, `texquote2` translates double quotes `"text"` to
|
|
|
|
`\machine{escaped_text}`.
|
|
|
|
|
2018-01-05 13:36:29 -08:00
|
|
|
### BNF grammar notation
|
|
|
|
|
2016-07-15 17:14:45 -07:00
|
|
|
The tool `tools/transf` provides support for BNF grammar notations and special
|
|
|
|
quotes for non-terminal. When transf is used, the environment `syntax` can
|
2016-07-13 11:50:20 -07:00
|
|
|
be used to describe grammars using BNF notation:
|
|
|
|
```latex
|
|
|
|
\begin{syntax}
|
|
|
|
expr:
|
|
|
|
value-path
|
|
|
|
| constant
|
|
|
|
| '(' expr ')'
|
|
|
|
| 'begin' expr 'end'
|
|
|
|
| '(' expr ':' typexpr ')'
|
|
|
|
| expr {{',' expr}}
|
|
|
|
| constr expr
|
|
|
|
| "`"tag-name expr
|
|
|
|
| expr '::' expr
|
|
|
|
| '[' expr { ';' expr } [';'] ']'
|
|
|
|
| '[|' expr { ';' expr } [';'] '|]'
|
|
|
|
| '{' field [':' typexpr] '=' expr%
|
|
|
|
{ ';' field [':' typexpr] '=' expr } [';'] '}'
|
|
|
|
\end{syntax}
|
|
|
|
```
|
|
|
|
Notice that terminal symbols are quoted using `'` delimiters.
|
|
|
|
Moreover, outside of the syntax environment, `@`-quotes can be used
|
|
|
|
to introduce fragment of grammar: `@'(' module-expr ')'@`. As a consequence,
|
|
|
|
when this extension is used `@` characters must be escaped as `\@`.
|
|
|
|
This extension is used mainly in the language reference part of the manual.
|
|
|
|
and a more complete description of the notation used is available in the
|
|
|
|
first subsection of `refman/refman.etex`.
|
2018-01-03 05:14:09 -08:00
|
|
|
|
|
|
|
Consistency tests
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
The `tests` folder contains consistency tests that checks that the manual
|
|
|
|
and the rest of the compiler sources stay synced.
|