The OCaml system release 4.05 Documentation and user's manual Xavier Leroy, Damien Doligez, Alain Frisch, Jacques Garrigue, Didier R´emy and J´er^omeVouillon July 13, 2017 Copyright © 2017 Institut National de Recherche en Informatique et en Automatique 2 Contents I An introduction to OCaml 11 1 The core language 13 1.1 Basics........................................... 13 1.2 Data types......................................... 14 1.3 Functions as values.................................... 15 1.4 Records and variants................................... 16 1.5 Imperative features.................................... 18 1.6 Exceptions......................................... 20 1.7 Symbolic processing of expressions........................... 21 1.8 Pretty-printing...................................... 22 1.9 Standalone OCaml programs............................... 23 2 The module system 25 2.1 Structures......................................... 25 2.2 Signatures......................................... 26 2.3 Functors.......................................... 27 2.4 Functors and type abstraction.............................. 29 2.5 Modules and separate compilation............................ 31 3 Objects in OCaml 33 3.1 Classes and objects.................................... 33 3.2 Immediate objects..................................... 36 3.3 Reference to self...................................... 37 3.4 Initializers......................................... 38 3.5 Virtual methods...................................... 38 3.6 Private methods...................................... 40 3.7 Class interfaces...................................... 42 3.8 Inheritance......................................... 43 3.9 Multiple inheritance.................................... 43 3.10 Parameterized classes................................... 44 3.11 Polymorphic methods................................... 47 3.12 Using coercions...................................... 50 3.13 Functional objects..................................... 54 3.14 Cloning objects...................................... 55 3.15 Recursive classes..................................... 58 1 2 3.16 Binary methods...................................... 58 3.17 Friends........................................... 60 4 Labels and variants 63 4.1 Labels........................................... 63 4.2 Polymorphic variants................................... 69 5 Advanced examples with classes and modules 73 5.1 Extended example: bank accounts............................ 73 5.2 Simple modules as classes................................ 79 5.3 The subject/observer pattern.............................. 84 II The OCaml language 89 6 The OCaml language 91 6.1 Lexical conventions.................................... 91 6.2 Values........................................... 95 6.3 Names........................................... 97 6.4 Type expressions..................................... 100 6.5 Constants......................................... 103 6.6 Patterns.......................................... 104 6.7 Expressions........................................ 108 6.8 Type and exception definitions.............................. 121 6.9 Classes........................................... 123 6.10 Module types (module specifications).......................... 130 6.11 Module expressions (module implementations)..................... 134 6.12 Compilation units..................................... 137 7 Language extensions 139 7.1 Integer literals for types int32, int64 and nativeint ................ 139 7.2 Recursive definitions of values.............................. 139 7.3 Lazy patterns....................................... 141 7.4 Recursive modules..................................... 141 7.5 Private types........................................ 142 7.6 Local opens........................................ 145 7.7 Record and object notations............................... 146 7.8 Explicit polymorphic type annotations......................... 147 7.9 Locally abstract types.................................. 147 7.10 First-class modules.................................... 149 7.11 Recovering the type of a module............................. 151 7.12 Substituting inside a signature.............................. 151 7.13 Type-level module aliases................................. 152 7.14 Explicit overriding in class definitions.......................... 154 7.15 Overriding in open statements.............................. 154 7.16 Generalized algebraic datatypes............................. 155 3 7.17 Syntax for Bigarray access................................ 160 7.18 Attributes......................................... 160 7.19 Extension nodes...................................... 167 7.20 Quoted strings....................................... 169 7.21 Exception cases in pattern matching.......................... 169 7.22 Extensible variant types................................. 170 7.23 Generative functors.................................... 171 7.24 Extension-only syntax.................................. 171 7.25 Inline records....................................... 172 7.26 Local exceptions...................................... 173 7.27 Documentation comments................................ 173 III The OCaml tools 177 8 Batch compilation (ocamlc) 179 8.1 Overview of the compiler................................. 179 8.2 Options........................................... 180 8.3 Modules and the file system............................... 191 8.4 Common errors...................................... 192 8.5 Warning reference..................................... 194 9 The toplevel system (ocaml) 199 9.1 Options........................................... 200 9.2 Toplevel directives..................................... 207 9.3 The toplevel and the module system.......................... 209 9.4 Common errors...................................... 210 9.5 Building custom toplevel systems: ocamlmktop ..................... 210 9.6 Options........................................... 211 10 The runtime system (ocamlrun) 213 10.1 Overview.......................................... 213 10.2 Options........................................... 214 10.3 Dynamic loading of shared libraries........................... 216 10.4 Common errors...................................... 216 11 Native-code compilation (ocamlopt) 219 11.1 Overview of the compiler................................. 219 11.2 Options........................................... 220 11.3 Common errors...................................... 232 11.4 Running executables produced by ocamlopt...................... 232 11.5 Compatibility with the bytecode compiler....................... 232 4 12 Lexer and parser generators (ocamllex, ocamlyacc) 235 12.1 Overview of ocamllex .................................. 235 12.2 Syntax of lexer definitions................................ 236 12.3 Overview of ocamlyacc .................................. 241 12.4 Syntax of grammar definitions.............................. 241 12.5 Options........................................... 244 12.6 A complete example.................................... 245 12.7 Common errors...................................... 246 12.8 Module Depend : Module dependencies.......................... 247 13 The browser/editor (ocamlbrowser) 249 14 The documentation generator (ocamldoc) 251 14.1 Usage............................................ 251 14.2 Syntax of documentation comments........................... 258 14.3 Custom generators.................................... 268 14.4 Adding command line options.............................. 271 15 The debugger (ocamldebug) 273 15.1 Compiling for debugging................................. 273 15.2 Invocation......................................... 273 15.3 Commands......................................... 274 15.4 Executing a program................................... 275 15.5 Breakpoints........................................ 278 15.6 The call stack....................................... 278 15.7 Examining variable values................................ 279 15.8 Controlling the debugger................................. 280 15.9 Miscellaneous commands................................. 283 15.10 Running the debugger under Emacs........................... 283 16 Profiling (ocamlprof) 285 16.1 Compiling for profiling.................................. 285 16.2 Profiling an execution................................... 286 16.3 Printing profiling information.............................. 286 16.4 Time profiling....................................... 287 17 The ocamlbuild compilation manager 289 18 Interfacing C with OCaml 291 18.1 Overview and compilation information......................... 291 18.2 The value type...................................... 298 18.3 Representation of OCaml data types.......................... 299 18.4 Operations on values................................... 302 18.5 Living in harmony with the garbage collector..................... 305 18.6 A complete example.................................... 309 18.7 Advanced topic: callbacks from C to OCaml...................... 313 5 18.8 Advanced example with callbacks............................ 317 18.9 Advanced topic: custom blocks............................. 319 18.10 Advanced topic: cheaper C call............................. 323 18.11 Advanced topic: multithreading............................. 325 18.12 Building mixed C/OCaml libraries: ocamlmklib .................... 328 19 Optimisation with Flambda