Skip to content

Commit 3831310

Browse files
sabinesabine
committed
(docs) add pages describing all of OCaml's compilation targets #3378 (b0607d3)
1 parent a5df174 commit 3831310

File tree

6 files changed

+416
-0
lines changed

6 files changed

+416
-0
lines changed

‎data/tool_pages/platform/2ct_00_native.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
id: "native-target"
3+
short_title: "Compilation Targets: Native Code"
4+
title: "Compilation Targets: Native Code"
5+
description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimized machine code for production deployments."
6+
category: "Compilation Targets"
7+
---
8+
9+
OCaml can compile to native code, delivering high-performance executables with optimized machine code for production environments.
10+
11+
## What is OCaml Native Code?
12+
13+
OCaml native code is generated by ocamlopt, the high-performance native-code compiler that compiles OCaml source files to native code object files and links them to produce standalone executables. The native code system consists of:
14+
15+
- **ocamlopt** - The native-code compiler (analogous to gcc or clang for C/C++)
16+
- **Native executables** - Stand-alone executable files that can be invoked directly without depending on the ocamlrun bytecode runtime system
17+
- **Runtime system** - Integrated directly into each executable, including the garbage collector
18+
19+
Native code produces faster-running programs than bytecode, at the cost of increased compilation time and executable code size. Key characteristics:
20+
21+
- Faster runtime performance than bytecode
22+
- Stand-alone executables requiring no external runtime
23+
- Cross-module inlining and optimization
24+
- Production-ready deployments
25+
26+
## When to Use Native Code
27+
28+
**Use native code** (ocamlopt) when you need faster runtime performance in production, want standalone executables, or are deploying to end users.
29+
30+
**Use bytecode** (ocamlc) for fast iteration during development, CI/testing environments where compilation speed matters, or maximum portability.
31+
32+
The typical OCaml workflow: develop with bytecode for fast compile times, switch to native code for production releases. The same source code compiles to both targets without modification.
33+
34+
## Platform Support
35+
36+
The native-code compiler is only available on certain platforms. From OCaml 5.0 onwards, native compilation is available only on 64-bit systems.
37+
38+
### Supported Platforms (OCaml 5.x)
39+
40+
- **x86-64 (AMD64)** - Linux, macOS, Windows
41+
- **ARM64 (AArch64)** - Linux, macOS (including Apple Silicon)
42+
- **RISC-V** - Linux
43+
- **IBM Z (s390x)** - Linux (OCaml 5.1+)
44+
45+
Native compilation on 32-bit systems is no longer available, nor are there plans to bring it back.
46+
47+
**Windows specifics:** Native compilation is supported via MSVC, MinGW, or Cygwin toolchains. See [OCaml on Windows](https://ocaml.org/docs/ocaml-on-windows) for setup details.
48+
49+
If your target platform lacks native code support, the bytecode compiler provides a highly portable fallback.
50+
51+
## Getting Started
52+
53+
To compile OCaml programs to native code, use the ocamlopt compiler. For single files, specify the source file and output executable name. For projects with multiple modules, list them in dependency order. When using libraries, specify both the library archive and your source files.
54+
55+
In practice, most developers use build systems like [Dune](https://dune.build/) rather than invoking ocamlopt directly. Dune handles compilation, dependency management, and build orchestration.
56+
57+
For comprehensive compiler details, see the [OCaml Manual: Native-code Compilation (ocamlopt)](https://ocaml.org/manual/latest/native.html). For practical build workflows, see [Using the OCaml Compiler Toolchain](https://ocaml.org/docs/using-the-ocaml-compiler-toolchain).
58+
59+
## Compilation Model & File Extensions
60+
61+
OCaml's compilation model separates interface and implementation:
62+
63+
- **.ml** - Module implementation (source)
64+
- **.mli** - Module interface/signature (source)
65+
- **.cmi** - Compiled interface (used by both bytecode and native)
66+
- **.cmx** - Compiled native object with cross-module optimization metadata
67+
- **.o** / **.obj** - Native machine code object file
68+
- **.cmxa** - Native library archive (collection of .cmx files)
69+
- **.a** / **.lib** - Native static library (collection of .o files)
70+
71+
The .cmx files contain information for cross-module inlining and optimization. Unlike bytecode, these optimization metadata files must be available at link time for best performance.
72+
73+
## Compatibility with Bytecode
74+
75+
Compatibility with the bytecode compiler is extremely high: the same source code should run identically when compiled with ocamlc and ocamlopt.
76+
77+
Key constraints:
78+
79+
- It is not possible to mix native-code object files produced by ocamlopt with bytecode object files produced by ocamlc: a program must be compiled entirely with ocamlopt or entirely with ocamlc.
80+
- Native-code object files produced by ocamlopt cannot be loaded in the toplevel system.
81+
82+
This binary compatibility means you can develop and test with bytecode for fast iteration, then deploy with native code for performance, using the same source code for both compilation targets.
83+
84+
## Debugging and Profiling
85+
86+
Native executables integrate with standard system tools:
87+
88+
**Debugging:**
89+
- Compile with -g flag for debug symbols
90+
- Produces stack backtraces when the program terminates on an uncaught exception
91+
- Use gdb, lldb, or other native debuggers
92+
- OCaml and C frames appear in the same stack trace
93+
94+
**Profiling:**
95+
- Use perf (Linux), Instruments (macOS), or similar native profilers
96+
- Compile with -g for accurate symbol resolution
97+
- gprof support via -p flag
98+
99+
The native compiler maintains C calling conventions, making OCaml code visible to standard profiling and debugging tools.
100+
101+
## Dynamic Loading
102+
103+
The -shared option builds plugins (usually .cmxs files) that can be dynamically loaded with the Dynlink module. This provides a plugin system similar to shared libraries and DLLs, allowing runtime loading of OCaml code. Platform support varies—consult the manual for specifics.
104+
105+
## Learn More
106+
107+
- [OCaml Manual: Native-code Compilation](https://ocaml.org/manual/latest/native.html) - Complete ocamlopt reference
108+
- [Using the OCaml Compiler Toolchain](https://ocaml.org/docs/using-the-ocaml-compiler-toolchain) - Practical compilation guide
109+
- [The Compiler Backend: Bytecode and Native code](https://ocaml.org/docs/compiler-backend) - Deep dive: lambda form, optimization, assembly output

‎data/tool_pages/platform/2ct_01_bytecode.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
id: "bytecode-target"
3+
short_title: "Compilation Targets: Bytecode"
4+
title: "Compilation Targets: Bytecode"
5+
description: "Compile OCaml to portable bytecode with ocamlc. Fast compilation, excellent portability, and easy debugging for OCaml development and production."
6+
category: "Compilation Targets"
7+
---
8+
9+
OCaml can compile to bytecode, providing fast compilation, excellent portability, and predictable execution across different platforms.
10+
11+
## What is OCaml Bytecode?
12+
13+
OCaml bytecode is a portable intermediate representation of OCaml programs that is executed by the OCaml bytecode interpreter. The bytecode system consists of:
14+
15+
- **ocamlc** - The bytecode compiler that compiles OCaml source files to bytecode
16+
- **ocamlrun** - The bytecode interpreter that executes bytecode programs
17+
- **Runtime system** - Includes the bytecode interpreter, garbage collector, and C primitive operations
18+
19+
Bytecode provides several advantages over native compilation:
20+
- Fast compilation speed
21+
- Portability across all platforms where OCaml is installed
22+
- Smaller compiler footprint
23+
- Predictable and consistent execution behavior
24+
- Easier debugging with built-in tools
25+
26+
## When to Use Bytecode
27+
28+
**Use bytecode** when you want fast compilation during development, need maximum portability, or are targeting platforms without a native code compiler.
29+
30+
**Use native code** (ocamlopt) when you need maximum runtime performance in production deployments.
31+
32+
Many OCaml developers use bytecode during development for its fast compile times, then switch to native code for production releases.
33+
34+
## File Extensions
35+
36+
The bytecode compiler produces several types of files:
37+
38+
- **.cmo** - Compiled module object (bytecode)
39+
- **.cmi** - Compiled module interface
40+
- **.cma** - Bytecode library archive (collection of .cmo files)
41+
- **executable** - Bytecode executable (often with no extension or .byte extension)
42+
43+
## Getting Started
44+
45+
To get started with OCaml bytecode compilation, visit the [OCaml Manual: Batch Compilation (ocamlc)](https://ocaml.org/manual/latest/comp.html). This comprehensive guide covers:
46+
47+
- Compiling OCaml source files to bytecode
48+
- Linking bytecode object files into executables
49+
- Creating and using bytecode libraries
50+
- Compiler command-line options and flags
51+
- Separate compilation for larger projects
52+
53+
For information on running bytecode programs and configuring the runtime system, see the [OCaml Manual: Runtime System (ocamlrun)](https://ocaml.org/manual/latest/runtime.html).
54+
55+
## Debugging
56+
57+
The bytecode compiler includes excellent debugging support. Compile with the `-g` flag to include debugging information, which enables:
58+
- Stack backtraces for uncaught exceptions
59+
- Use of the OCaml debugger (ocamldebug)
60+
- Better error reporting
61+
62+
Learn more in the [OCaml Manual: The Debugger](https://ocaml.org/manual/latest/debugger.html).
63+
64+
## Custom Runtime Mode
65+
66+
For standalone executables that don't require ocamlrun to be installed separately, OCaml supports custom runtime mode. This bundles the runtime system with your bytecode in a single executable file.
67+
68+
Details can be found in the [OCaml Manual: Batch Compilation](https://ocaml.org/manual/latest/comp.html) under the `-custom` flag documentation.
69+
70+
## Learn More
71+
72+
- [OCaml Manual: Batch Compilation](https://ocaml.org/manual/latest/comp.html) - Complete reference for ocamlc
73+
- [OCaml Manual: Runtime System](https://ocaml.org/manual/latest/runtime.html) - Details on ocamlrun and bytecode execution
74+
- [Compiler Backend Documentation](https://ocaml.org/docs/compiler-backend) - How the OCaml compiler works
75+
- [Compiling OCaml Projects](https://ocaml.org/docs/compiling-ocaml-projects) - Getting started guide

‎data/tool_pages/platform/2ct_02_javascript.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
id: "javascript-target"
3+
short_title: "Compilation Targets: JavaScript"
4+
title: "Compilation Targets: JavaScript"
5+
description: "Compile OCaml to JavaScript with Js_of_ocaml and Melange. Build type-safe web applications that run in browsers and Node.js with high performance."
6+
category: "Compilation Targets"
7+
---
8+
9+
OCaml can compile to JavaScript, enabling you to write type-safe, high-performance code that runs in web browsers and Node.js environments.
10+
11+
## Available Tools
12+
13+
### Js_of_ocaml
14+
15+
[Js_of_ocaml](https://ocsigen.org/js_of_ocaml/) compiles OCaml bytecode to JavaScript. It provides:
16+
17+
- Excellent performance with compact output
18+
- Strong integration with existing JavaScript libraries
19+
- Access to browser APIs and DOM manipulation
20+
- Support for the full OCaml language, including advanced features
21+
- Compatibility with most OCaml libraries and the standard library
22+
23+
Js_of_ocaml is ideal when you want to leverage existing OCaml code in web applications or need access to the complete OCaml ecosystem.
24+
25+
### Melange
26+
27+
[Melange](https://melange.re) compiles OCaml and Reason to JavaScript with a focus on JavaScript ecosystem integration. It provides:
28+
29+
- Idiomatic JavaScript output designed for readability
30+
- Deep integration with NPM packages and JavaScript tooling
31+
- Excellent TypeScript interoperability
32+
- Optimized bundle sizes for modern web applications
33+
- Support for React and modern frontend frameworks
34+
35+
Melange is ideal when you're building JavaScript-first applications and want seamless integration with the JavaScript ecosystem.
36+
37+
## Choosing a Tool
38+
39+
**Use Js_of_ocaml** when you have existing OCaml code you want to run in the browser, need the full OCaml standard library, or want to use OCaml-native libraries.
40+
41+
**Use Melange** when you're building web applications that need to integrate tightly with JavaScript libraries, want readable JavaScript output, or need excellent TypeScript compatibility.
42+
43+
## Getting Started
44+
45+
### Js_of_ocaml
46+
47+
Visit the [Js_of_ocaml documentation](https://ocsigen.org/js_of_ocaml/latest/manual/overview) to learn how to:
48+
49+
- Install and set up Js_of_ocaml
50+
- Compile your first OCaml program to JavaScript
51+
- Interact with JavaScript APIs and the DOM
52+
- Integrate with web applications
53+
54+
### Melange
55+
56+
Visit the [Melange documentation](https://melange.re/v5.0.0/) to learn how to:
57+
58+
- Set up a Melange project
59+
- Bind to JavaScript libraries
60+
- Build web applications with Melange
61+
- Integrate with existing JavaScript tooling
62+
63+
## Learn More
64+
65+
- [Js_of_ocaml Manual](https://ocsigen.org/js_of_ocaml/latest/manual/overview) - Comprehensive guide and API reference
66+
- [Melange Playground](https://melange.re/v5.0.0/playground/) - Try Melange in your browser
67+
- [OCaml for Web Development](https://ocaml.org/docs/web-development) - Overview of web development with OCaml
68+
69+
## Community
70+
71+
- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
72+
- [Melange Discord](https://discord.gg/reasonml) - Melange and Reason community

‎data/tool_pages/platform/2ct_03_wasm.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
id: "wasm-target"
3+
short_title: "Compilation Targets: WASM"
4+
title: "Compilation Targets: WebAssembly"
5+
description: "Compile OCaml to WebAssembly with wasm_of_ocaml and Wasocaml. Build high-performance applications for browsers, servers, and edge computing with Wasm."
6+
category: "Compilation Targets"
7+
---
8+
9+
OCaml can compile to WebAssembly (WASM), enabling you to run high-performance OCaml code in web browsers, on the server, and in embedded environments with near-native speed.
10+
11+
## What is WebAssembly?
12+
13+
WebAssembly is a binary instruction format designed as a portable compilation target for programming languages. It provides:
14+
15+
- Near-native performance in web browsers and standalone runtimes
16+
- Sandboxed execution environment for security
17+
- Broad platform support across browsers, servers, and edge computing
18+
- Compact binary format for fast loading and parsing
19+
20+
## Available Tools
21+
22+
### wasm_of_ocaml
23+
24+
[wasm_of_ocaml](https://github.com/ocaml-wasm/wasm_of_ocaml) compiles OCaml bytecode to WebAssembly. It provides:
25+
26+
- Full OCaml language support, including the standard library
27+
- Compatibility with existing OCaml libraries
28+
- Integration with JavaScript through Js_of_ocaml-style bindings
29+
- Ability to run OCaml code in browsers and WASM runtimes
30+
- Shared infrastructure with Js_of_ocaml for web development
31+
32+
wasm_of_ocaml is ideal when you want to leverage existing OCaml code with WebAssembly's performance characteristics while maintaining compatibility with the OCaml ecosystem.
33+
34+
### Wasocaml
35+
36+
[Wasocaml](https://github.com/OCamlPro/wasocaml) is an OCaml compiler that targets WebAssembly GC (WASM-GC). Developed by OCamlPro, it provides:
37+
38+
- Direct compilation from OCaml's Flambda intermediate representation to WASM-GC
39+
- Native WebAssembly garbage collection support
40+
- Optimized performance through the Flambda optimizer
41+
- Support for functional programming language features in WebAssembly
42+
- First real-world functional language compiler targeting WASM-GC
43+
44+
Wasocaml is ideal when you need direct compilation to WebAssembly with garbage collection support and want to benefit from Flambda optimizations.
45+
46+
## Choosing a Tool
47+
48+
**Use wasm_of_ocaml** when you want to run existing OCaml bytecode in WebAssembly environments, need compatibility with Js_of_ocaml web bindings, or want a mature toolchain similar to Js_of_ocaml.
49+
50+
**Use Wasocaml** when you need direct compilation with Flambda optimizations, want to target the WebAssembly GC proposal, or are building performance-critical applications.
51+
52+
## Getting Started
53+
54+
### wasm_of_ocaml
55+
56+
Visit the [wasm_of_ocaml repository](https://github.com/ocaml-wasm/wasm_of_ocaml) to learn how to:
57+
58+
- Install and set up wasm_of_ocaml
59+
- Compile OCaml programs to WebAssembly
60+
- Interact with JavaScript APIs from WASM
61+
- Deploy WASM modules in web applications
62+
63+
### Wasocaml
64+
65+
Visit the [Wasocaml repository](https://github.com/OCamlPro/wasocaml) and [OCamlPro's blog posts](https://ocamlpro.com/blog/2022_12_14_wasm_and_ocaml/) to learn how to:
66+
67+
- Install the Wasocaml compiler switch
68+
- Compile OCaml programs to WASM-GC
69+
- Understand the compilation process and optimizations
70+
- Deploy to WebAssembly runtimes
71+
72+
## Learn More
73+
74+
- [ocaml-wasm Organization](https://github.com/ocaml-wasm) - Coordination hub for OCaml WebAssembly efforts
75+
- [WebAssembly.org](https://webassembly.org/) - WebAssembly specification and documentation
76+
- [WASM-GC Proposal](https://github.com/WebAssembly/gc) - Garbage Collection proposal for WebAssembly
77+
- [OCamlPro WASM Blog Posts](https://ocamlpro.com/blog/tags/wasm/) - Technical deep dives on Wasocaml
78+
79+
## Community
80+
81+
- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
82+
- [ocaml-wasm Updates](https://discuss.ocaml.org/tag/wasm) - Follow WebAssembly developments in OCaml

0 commit comments

Comments
 (0)