☰
The OCaml system
release 5.0
December , 2022
Select another version
The OCaml Manual
Contents
Foreword
Index of keywords
OCaml API
OCaml Compiler API
Contents
Part I An introduction to OCaml
Chapter 1
The core language
1
Basics
2
Data types
3
Functions as values
4
Records and variants
4.1
Record and variant disambiguation
5
Imperative features
6
Exceptions
7
Lazy expressions
8
Symbolic processing of expressions
9
Pretty-printing
10
Printf formats
11
Standalone OCaml programs
Chapter 2
The module system
1
Structures
2
Signatures
3
Functors
4
Functors and type abstraction
5
Modules and separate compilation
Chapter 3
Objects in OCaml
1
Classes and objects
2
Immediate objects
3
Reference to self
4
Initializers
5
Virtual methods
6
Private methods
7
Class interfaces
8
Inheritance
9
Multiple inheritance
10
Parameterized classes
11
Polymorphic methods
12
Using coercions
13
Functional objects
14
Cloning objects
15
Recursive classes
16
Binary methods
17
Friends
Chapter 4
Labeled arguments
1
Optional arguments
2
Labels and type inference
3
Suggestions for labeling
Chapter 5
Polymorphic variants
1
Basic use
2
Advanced use
3
Weaknesses of polymorphic variants
Chapter 6
Polymorphism and its limitations
1
Weak polymorphism and mutation
1.1
Weakly polymorphic types
1.2
The value restriction
1.3
The relaxed value restriction
1.4
Variance and value restriction
1.5
Abstract data types
2
Polymorphic recursion
2.1
Explicitly polymorphic annotations
2.2
More examples
3
Higher-rank polymorphic functions
Chapter 7
Generalized algebraic datatypes
1
Recursive functions
2
Type inference
3
Refutation cases
4
Advanced examples
5
Existential type names in error messages
6
Explicit naming of existentials
7
Equations on non-local abstract types
Chapter 8
Advanced examples with classes and modules
1
Extended example: bank accounts
2
Simple modules as classes
2.1
Strings
2.2
Hashtbl
2.3
Sets
3
The subject/observer pattern
Chapter 9
Parallel programming
1
Domains
1.1
Joining domains
2
Domainslib: A library for nested-parallel programming
2.1
Parallelising Fibonacci using domainslib
2.2
Parallel iteration constructs
3
Parallel garbage collection
4
Memory model: The easy bits
5
Blocking synchronisation
5.1
Interaction with systhreads
6
Interaction with C bindings
7
Atomics
7.1
Lock-free stack
Chapter 10
Memory model: The hard bits
1
Why weakly consistent memory?
1.1
Compiler optimisations
1.2
Hardware optimisations
2
Data race freedom implies sequential consistency
2.1
Memory locations
2.2
Happens-before relation
2.3
Data race
2.4
DRF-SC
3
Reasoning with DRF-SC
4
Local data race freedom
5
An operational view of the memory model
5.1
Non-atomic locations
5.2
Domains
5.3
Non-atomic accesses
5.4
Atomic accesses
5.5
Reasoning with the semantics
6
Non-compliant operations
Part II The OCaml language
Chapter 11
The OCaml language
1
Lexical conventions
2
Values
2.1
Base values
2.2
Tuples
2.3
Records
2.4
Arrays
2.5
Variant values
2.6
Polymorphic variants
2.7
Functions
2.8
Objects
3
Names
4
Type expressions
5
Constants
6
Patterns
7
Expressions
7.1
Precedence and associativity
7.2
Basic expressions
7.3
Control structures
7.4
Operations on data structures
7.5
Operators
7.6
Objects
7.7
Coercions
7.8
Other
8
Type and exception definitions
8.1
Type definitions
8.2
Exception definitions
9
Classes
9.1
Class types
9.2
Class expressions
9.3
Class definitions
9.4
Class specifications
9.5
Class type definitions
10
Module types (module specifications)
10.1
Simple module types
10.2
Signatures
10.3
Functor types
10.4
The
with
operator
11
Module expressions (module implementations)
11.1
Simple module expressions
11.2
Structures
11.3
Functors
12
Compilation units
Chapter 12
Language extensions
1
Recursive definitions of values
2
Recursive modules
3
Private types
3.1
Private variant and record types
3.2
Private type abbreviations
3.3
Private row types
4
Locally abstract types
5
First-class modules
6
Recovering the type of a module
7
Substituting inside a signature
7.1
Destructive substitutions
7.2
Local substitution declarations
7.3
Module type substitutions
8
Type-level module aliases
9
Overriding in open statements
10
Generalized algebraic datatypes
11
Syntax for Bigarray access
12
Attributes
12.1
Built-in attributes
13
Extension nodes
13.1
Built-in extension nodes
14
Extensible variant types
14.1
Private extensible variant types
15
Generative functors
16
Extension-only syntax
16.1
Extension operators
16.2
Extension literals
17
Inline records
18
Documentation comments
18.1
Floating comments
18.2
Item comments
18.3
Label comments
19
Extended indexing operators
19.1
Multi-index notation
20
Empty variant types
21
Alerts
22
Generalized open statements
23
Binding operators
23.1
Short notation for variable bindings (let-punning)
23.2
Rationale
24
Effect handlers
24.1
Basics
24.2
Concurrency
24.3
User-level threads
24.4
Control inversion
24.5
Semantics
24.6
Shallow handlers
Part III The OCaml tools
Chapter 13
Batch compilation (ocamlc)
1
Overview of the compiler
2
Options
3
Modules and the file system
4
Common errors
5
Warning reference
5.1
Warning 6: Label omitted in function application
5.2
Warning 9: missing fields in a record pattern
5.3
Warning 52: fragile constant pattern
5.4
Warning 57: Ambiguous or-pattern variables under guard
Chapter 14
The toplevel system or REPL (ocaml)
1
Options
2
Toplevel directives
3
The toplevel and the module system
4
Common errors
5
Building custom toplevel systems:
ocamlmktop
5.1
Options
6
The native toplevel:
ocamlnat
(experimental)
Chapter 15
The runtime system (ocamlrun)
1
Overview
2
Options
3
Dynamic loading of shared libraries
4
Common errors
Chapter 16
Native-code compilation (ocamlopt)
1
Overview of the compiler
2
Options
3
Common errors
4
Running executables produced by ocamlopt
5
Compatibility with the bytecode compiler
Chapter 17
Lexer and parser generators (ocamllex, ocamlyacc)
1
Overview of
ocamllex
1.1
Options
2
Syntax of lexer definitions
2.1
Header and trailer
2.2
Naming regular expressions
2.3
Entry points
2.4
Regular expressions
2.5
Actions
2.6
Variables in regular expressions
2.7
Refill handlers
2.8
Reserved identifiers
3
Overview of
ocamlyacc
4
Syntax of grammar definitions
4.1
Header and trailer
4.2
Declarations
4.3
Rules
4.4
Error handling
5
Options
6
A complete example
7
Common errors
Chapter 18
Dependency generator (ocamldep)
1
Options
2
A typical Makefile
Chapter 19
The documentation generator (ocamldoc)
1
Usage
1.1
Invocation
1.2
Merging of module information
1.3
Coding rules
2
Syntax of documentation comments
2.1
Placement of documentation comments
2.2
The Stop special comment
2.3
Syntax of documentation comments
2.4
Text formatting
2.5
Documentation tags (@-tags)
3
Custom generators
3.1
The generator modules
3.2
Handling custom tags
4
Adding command line options
4.1
Compilation and usage
Chapter 20
The debugger (ocamldebug)
1
Compiling for debugging
2
Invocation
2.1
Starting the debugger
2.2
Initialization file
2.3
Exiting the debugger
3
Commands
3.1
Getting help
3.2
Accessing the debugger state
4
Executing a program
4.1
Events
4.2
Starting the debugged program
4.3
Running the program
4.4
Time travel
4.5
Killing the program
5
Breakpoints
6
The call stack
7
Examining variable values
8
Controlling the debugger
8.1
Setting the program name and arguments
8.2
How programs are loaded
8.3
Search path for files
8.4
Working directory
8.5
Turning reverse execution on and off
8.6
Behavior of the debugger with respect to
fork
8.7
Stopping execution when new code is loaded
8.8
Communication between the debugger and the program
8.9
Fine-tuning the debugger
8.10
User-defined printers
9
Miscellaneous commands
10
Running the debugger under Emacs
Chapter 21
Profiling (ocamlprof)
1
Compiling for profiling
2
Profiling an execution
3
Printing profiling information
4
Time profiling
Chapter 22
Interfacing C with OCaml
1
Overview and compilation information
1.1
Declaring primitives
1.2
Implementing primitives
1.3
Statically linking C code with OCaml code
1.4
Dynamically linking C code with OCaml code
1.5
Choosing between static linking and dynamic linking
1.6
Building standalone custom runtime systems
2
The
value
type
2.1
Integer values
2.2
Blocks
2.3
Pointers outside the heap
3
Representation of OCaml data types
3.1
Atomic types
3.2
Tuples and records
3.3
Arrays
3.4
Concrete data types
3.5
Objects
3.6
Polymorphic variants
4
Operations on values
4.1
Kind tests
4.2
Operations on integers
4.3
Accessing blocks
4.4
Allocating blocks
4.5
Raising exceptions
5
Living in harmony with the garbage collector
5.1
Simple interface
5.2
Low-level interface
5.3
Pending actions and asynchronous exceptions
6
A complete example
7
Advanced topic: callbacks from C to OCaml
7.1
Applying OCaml closures from C
7.2
Obtaining or registering OCaml closures for use in C functions
7.3
Registering OCaml exceptions for use in C functions
7.4
Main program in C
7.5
Embedding the OCaml code in the C code
8
Advanced example with callbacks
9
Advanced topic: custom blocks
9.1
The
struct custom_operations
9.2
Allocating custom blocks
9.3
Accessing custom blocks
9.4
Writing custom serialization and deserialization functions
9.5
Choosing identifiers
9.6
Finalized blocks
10
Advanced topic: Bigarrays and the OCaml-C interface
10.1
Include file
10.2
Accessing an OCaml bigarray from C or Fortran
10.3
Wrapping a C or Fortran array as an OCaml Bigarray
11
Advanced topic: cheaper C call
11.1
Passing unboxed values
11.2
Direct C call
11.3
Example: calling C library functions without indirection
12
Advanced topic: multithreading
12.1
Registering threads created from C
12.2
Parallel execution of long-running C code with systhreads
13
Advanced topic: interfacing with Windows Unicode APIs
14
Building mixed C/OCaml libraries:
ocamlmklib
15
Cautionary words: the internal runtime API
15.1
Internal variables and CAML_INTERNALS
15.2
OCaml version macros
Chapter 23
Optimisation with Flambda
1
Overview
2
Command-line flags
2.1
Specification of optimisation parameters by round
3
Inlining
3.1
Classic inlining heuristic
3.2
Overview of “Flambda” inlining heuristics
3.3
Handling of specific language constructs
3.4
Inlining reports
3.5
Assessment of inlining benefit
3.6
Control of speculation
4
Specialisation
4.1
Assessment of specialisation benefit
5
Default settings of parameters
5.1
Settings at -O2 optimisation level
5.2
Settings at -O3 optimisation level
6
Manual control of inlining and specialisation
7
Simplification
8
Other code motion transformations
8.1
Lifting of constants
8.2
Lifting of toplevel let bindings
9
Unboxing transformations
9.1
Unboxing of closure variables
9.2
Unboxing of specialised arguments
9.3
Unboxing of closures
10
Removal of unused code and values
10.1
Removal of redundant let expressions
10.2
Removal of redundant program constructs
10.3
Removal of unused arguments
10.4
Removal of unused closure variables
11
Other code transformations
11.1
Transformation of non-escaping references into mutable variables
11.2
Substitution of closure variables for specialised arguments
12
Treatment of effects
13
Compilation of statically-allocated modules
14
Inhibition of optimisation
15
Use of unsafe operations
16
Glossary
Chapter 24
Fuzzing with afl-fuzz
1
Overview
2
Generating instrumentation
2.1
Advanced options
3
Example
Chapter 25
Runtime tracing with runtime events
1
Overview
2
Architecture
2.1
Probes
2.2
Events transport
3
Usage
3.1
With OCaml APIs
3.2
With tooling
Chapter 26
The “Tail Modulo Constructor” program transformation
1
Disambiguation
2
Danger: getting out of tail-mod-cons
3
Details on the transformation
4
Current limitations
Part IV The OCaml library
Chapter 27
The core library
1
Built-in types and predefined exceptions
2
Module
Stdlib
: the initially opened module
Chapter 28
The standard library
Chapter 29
The compiler front-end
Chapter 30
The unix library: Unix system calls
Chapter 31
The str library: regular expressions and string processing
Chapter 32
The runtime_events library
Chapter 33
The threads library
Chapter 34
The dynlink library: dynamic loading and linking of object files
Chapter 35
Recently removed or moved libraries (Graphics, Bigarray, Num, LablTk)
1
The Graphics Library
2
The Bigarray Library
3
The Num Library
4
The Labltk Library and OCamlBrowser
Part V Indexes
Home
Foreword »
Copyright © 2022 Institut National de Recherche en Informatique et en Automatique