Skip to content

Commit 9648686

Browse files
sabinesabine
authored
(docs) add pages describing all of OCaml's compilation targets (#3378)
* (docs) add pages describing all of OCaml's compilation targets and linking out to reference docs of tools or the compiler * remove redundancy * shorten * short titles * address all the code reviews up to this point * markdown linter * add link to dune executable linking modes guide * give more context on wasocaml experimental / research nature * apply spelling corrections from @ILeandersson * mention WebAssembly on Dune manual link on WASM page
1 parent 7926495 commit 9648686

File tree

6 files changed

+308
-0
lines changed

6 files changed

+308
-0
lines changed

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

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
id: "native-target"
3+
short_title: "Native"
4+
title: "Compilation Targets: Native"
5+
description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimised machine code for production deployments."
6+
category: "Compilation Targets"
7+
---
8+
9+
OCaml can compile to native code, delivering high-performance executables with optimised machine code for production environments.
10+
11+
## What is OCaml Native Code?
12+
13+
OCaml native code is generated by **ocamlopt**, the native-code compiler that produces standalone executables with an integrated runtime and garbage collector. Key characteristics:
14+
15+
- Faster runtime performance than bytecode
16+
- Standalone executables requiring no external runtime
17+
- Cross-module inlining and optimisation
18+
- Production-ready deployments
19+
20+
## When to Use Native Code
21+
22+
**Use native code** (ocamlopt) when you need faster runtime performance in production, want standalone executables, or are deploying to end users.
23+
24+
**Use bytecode** (ocamlc) for fast iteration during development, CI/testing environments where compilation speed matters, or maximum portability.
25+
26+
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.
27+
28+
## Platform Support
29+
30+
The native-code compiler is available only on 64-bit systems (OCaml 5.0+):
31+
32+
- **x86-64 (AMD64)** - Linux, macOS, Windows
33+
- **ARM64 (AArch64)** - Linux, macOS (including Apple Silicon)
34+
- **RISC-V** - Linux
35+
- **IBM Z (s390x)** - Linux (OCaml 5.1+)
36+
- **PowerPC (PPC64)** - Linux
37+
38+
All native code platforms use **63-bit integers** (with 1 bit reserved for the garbage collector tag).
39+
40+
**Windows:** Native compilation is supported via MSVC, MinGW, or Cygwin toolchains. See [OCaml on Windows](https://ocaml.org/docs/ocaml-on-windows) for setup details.
41+
42+
If your target platform lacks native code support, the bytecode compiler provides a highly portable fallback.
43+
44+
## Learn More
45+
46+
- [Dune Manual: Executable Linking Modes](https://dune.readthedocs.io/en/stable/reference/dune/executable.html#linking-modes) - How to specify native, bytecode, or other compilation modes in Dune
47+
- [OCaml Manual: Native-code Compilation](https://ocaml.org/manual/latest/native.html) - Complete ocamlopt reference
48+
- [Using the OCaml Compiler Toolchain](https://ocaml.org/docs/using-the-ocaml-compiler-toolchain) - Practical compilation guide
49+
- [The Compiler Backend: Bytecode and Native code](https://ocaml.org/docs/compiler-backend) - Deep dive into compilation internals

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

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
id: "bytecode-target"
3+
short_title: "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 primitive C 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 behaviour
24+
- Easier debugging with built-in tools
25+
26+
The bytecode compiler can be built in either 32-bit or 64-bit mode, resulting in **31-bit or 63-bit integers**, respectively (with 1 bit reserved for the garbage collector tag).
27+
28+
## When to Use Bytecode
29+
30+
**Use bytecode** when you want fast compilation during development, need maximum portability, or are targeting platforms without a native code compiler.
31+
32+
**Use native code** (ocamlopt) when you need maximum runtime performance in production deployments.
33+
34+
Many OCaml developers use bytecode during development for its fast compile times, then switch to native code for production releases.
35+
36+
## File Extensions
37+
38+
The bytecode compiler produces several types of files:
39+
40+
- **.cmo** - Compiled module object (bytecode)
41+
- **.cmi** - Compiled module interface
42+
- **.cma** - Bytecode library archive (collection of .cmo files)
43+
- **executable** - Bytecode executable (often with no extension or .byte extension)
44+
45+
## Learn More
46+
47+
- [Dune Manual: Executable Linking Modes](https://dune.readthedocs.io/en/stable/reference/dune/executable.html#linking-modes) - How to specify native, bytecode, or other compilation modes in Dune
48+
- [OCaml Manual: Batch Compilation](https://ocaml.org/manual/latest/comp.html) - Complete reference for ocamlc
49+
- [OCaml Manual: Runtime System](https://ocaml.org/manual/latest/runtime.html) - Details on ocamlrun and bytecode execution
50+
- [Compiler Backend Documentation](https://ocaml.org/docs/compiler-backend) - How the OCaml compiler works
51+
- [Compiling OCaml Projects](https://ocaml.org/docs/compiling-ocaml-projects) - Getting started guide

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

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
id: "javascript-target"
3+
short_title: "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 OCaml 5 effects
21+
- Compatibility with most OCaml libraries and the standard library
22+
- **32-bit integers** (JavaScript's bit operations are 32-bit)
23+
24+
**Note:** While Js_of_ocaml supports OCaml 5 effects, it has limited support for Domains (multicore parallelism).
25+
26+
Js_of_ocaml is ideal when you want to leverage existing OCaml code in web applications or need access to the complete OCaml ecosystem.
27+
28+
**Getting started:** Visit the [Js_of_ocaml documentation](https://ocsigen.org/js_of_ocaml/latest/manual/overview) to learn how to install and set up Js_of_ocaml, compile your first OCaml program to JavaScript, interact with JavaScript APIs and the DOM, and integrate with web applications.
29+
30+
### Melange
31+
32+
[Melange](https://melange.re) compiles OCaml and Reason to JavaScript with a focus on JavaScript ecosystem integration. It provides:
33+
34+
- Idiomatic JavaScript output designed for readability
35+
- Deep integration with NPM packages and JavaScript tooling
36+
- Excellent TypeScript interoperability
37+
- Optimised bundle sizes for modern web applications
38+
- Support for React and modern frontend frameworks
39+
40+
Melange is ideal when you're building JavaScript-first applications and want seamless integration with the JavaScript ecosystem.
41+
42+
**Getting started:** Visit the [Melange documentation](https://melange.re/v5.0.0/) to learn how to set up a Melange project, bind to JavaScript libraries, build web applications with Melange, and integrate with existing JavaScript tooling.
43+
44+
## Choosing a Tool
45+
46+
**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.
47+
48+
**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.
49+
50+
## Learn More
51+
52+
- [Dune Manual: Executable Linking Modes](https://dune.readthedocs.io/en/stable/reference/dune/executable.html#linking-modes) - How to specify native, bytecode, or other compilation modes in Dune
53+
- [Js_of_ocaml Manual](https://ocsigen.org/js_of_ocaml/latest/manual/overview) - Comprehensive guide and API reference
54+
- [Melange Playground](https://melange.re/v5.0.0/playground/) - Try Melange in your browser
55+
- [OCaml for Web Development](https://ocaml.org/docs/web-development) - Overview of web development with OCaml
56+
57+
## Community
58+
59+
- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
60+
- [Melange Discord](https://discord.gg/reasonml) - Melange and Reason community

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

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
id: "wasm-target"
3+
short_title: "WebAssembly"
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+
- Near-native performance in web browsers and standalone runtimes
15+
- Sandboxed execution environment for security
16+
- Broad platform support across browsers, servers, and edge computing
17+
- Compact binary format for fast loading and parsing
18+
19+
## Available Tools
20+
21+
### wasm_of_ocaml
22+
23+
[wasm_of_ocaml](https://github.com/ocsigen/js_of_ocaml/blob/master/README_wasm_of_ocaml.md) compiles OCaml bytecode to WebAssembly. It provides:
24+
- Full OCaml language support, including the standard library and OCaml 5 effects
25+
- Compatibility with existing OCaml libraries
26+
- Integration with JavaScript through Js_of_ocaml-style bindings
27+
- Ability to run OCaml code in browsers and WASM runtimes
28+
- Shared infrastructure with Js_of_ocaml for web development
29+
- **31-bit integers** (similar to traditional OCaml bytecode on 32-bit systems)
30+
31+
**Note:** While wasm_of_ocaml supports OCaml 5 effects, it has limited support for Domains (multicore parallelism).
32+
33+
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.
34+
35+
Visit the [wasm_of_ocaml documentation](https://github.com/ocsigen/js_of_ocaml/blob/master/README_wasm_of_ocaml.md) in the Js_of_ocaml repository to learn how to install and set up wasm_of_ocaml, compile OCaml programs to WebAssembly, interact with JavaScript APIs from WASM, and deploy WASM modules in web applications.
36+
37+
### Wasocaml (Experimental)
38+
39+
[Wasocaml](https://github.com/OCamlPro/wasocaml) is an experimental OCaml compiler developed by OCamlPro that targets WebAssembly GC (WASM-GC). As a research project exploring direct compilation to WASM-GC, it provides:
40+
- Direct compilation from OCaml's Flambda intermediate representation to WASM-GC
41+
- Native WebAssembly garbage collection support
42+
- Optimised performance through the Flambda optimiser
43+
- Support for functional programming language features in WebAssembly
44+
- **31-bit integers** (similar to traditional OCaml bytecode on 32-bit systems)
45+
46+
**Important limitations:** Wasocaml is based on OCaml 4.14 and does not currently support OCaml 5 effects or multicore features. As an experimental project, it should be considered for research and experimentation rather than for use in production.
47+
48+
Visit the [Wasocaml repository](https://github.com/OCamlPro/wasocaml) to learn how to install the Wasocaml compiler switch and explore its experimental features.
49+
50+
## Choosing a Tool
51+
52+
**Use wasm_of_ocaml** for most WebAssembly projects. It provides a mature toolchain for running existing OCaml bytecode in WebAssembly environments, with compatibility with Js_of_ocaml web bindings and OCaml 5 support.
53+
54+
**Explore Wasocaml** if you're interested in experimental approaches to WebAssembly compilation or researching direct compilation to WASM-GC, keeping in mind its current limitations and experimental status.
55+
56+
## Learn More
57+
58+
- [Dune Manual: Executable Linking Modes](https://dune.readthedocs.io/en/stable/reference/dune/executable.html#linking-modes) - How to specify native, bytecode, WebAssembly, or other compilation modes in Dune
59+
- [ocaml-wasm Organisation](https://github.com/ocaml-wasm) - Coordination hub for OCaml WebAssembly efforts
60+
- [WebAssembly.org](https://webassembly.org/) - WebAssembly specification and documentation
61+
- [WASM-GC Proposal](https://github.com/WebAssembly/gc) - Garbage Collection proposal for WebAssembly
62+
63+
## Community
64+
65+
- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
66+
- [ocaml-wasm Updates](https://discuss.ocaml.org/tag/wasm) - Follow WebAssembly developments in OCaml

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
id: "unikernel-target"
3+
short_title: "Unikernels"
4+
title: "Compilation Targets: Unikernels"
5+
description: "Compile OCaml to specialised unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
6+
category: "Compilation Targets"
7+
---
8+
9+
OCaml can compile to specialised unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
10+
11+
## What are Unikernels?
12+
13+
Unikernels are specialised, single-purpose virtual machine images that bundle your application with only the minimal OS functionality it needs. Unlike traditional applications that run on general-purpose operating systems, unikernels:
14+
15+
- Include only the necessary OS components, resulting in tiny footprints (often just a few megabytes)
16+
- Boot in milliseconds
17+
- Have reduced attack surfaces due to minimal code
18+
- Run directly on hypervisors or specialised monitor layers
19+
20+
MirageOS lets you write OCaml applications once and deploy them as unikernels to different virtualisation platforms.
21+
22+
## Available Targets
23+
24+
MirageOS supports compilation to several unikernel backends:
25+
26+
### Solo5 Targets
27+
28+
[Solo5](https://github.com/Solo5/solo5) is a sandboxed execution environment that provides multiple deployment options:
29+
30+
- **hvt** (Hardware Virtualized Tender) - Runs on KVM/Linux, bhyve/FreeBSD, and vmm/OpenBSD with minimal overhead
31+
- **spt** (Sandboxed Process Tender) - Runs as a regular Unix process with seccomp sandboxing on Linux
32+
- **virtio** - Runs on standard virtio-based hypervisors including QEMU/KVM, Google Compute Engine, and OpenStack
33+
- **muen** - Runs on the Muen Separation Kernel
34+
- **xen** - Runs on the Xen hypervisor as a paravirtualised guest (PVHv2 mode)
35+
36+
### Unikraft Targets
37+
38+
[Unikraft](https://unikraft.org) is a general Unikernel Development Kit that can be used as a MirageOS backend:
39+
40+
- **unikraft-qemu** - Runs on the [QEMU](https://www.qemu.org/) virtual machine monitor
41+
- **unikraft-firecracker** - Runs on the [Firecracker](https://firecracker-microvm.github.io/) virtual machine monitor
42+
43+
### Unix
44+
45+
- **unix** - Runs as a standard Unix process (useful for development and testing)
46+
47+
## Choosing a Target
48+
49+
**Use Unix** when you're developing and testing your unikernel locally.
50+
51+
**Use hvt** when you want lightweight virtualisation on Linux, FreeBSD, or OpenBSD with KVM, bhyve, or vmm.
52+
53+
**Use virtio** when deploying to cloud providers like Google Compute Engine, or standard KVM/QEMU setups.
54+
55+
**Use spt** when you want process-level isolation on Linux without full virtualisation.
56+
57+
**Use Xen** when deploying to Xen-based infrastructure or cloud providers that support Xen.
58+
59+
**Use Unikraft targets** when you want to use the Unikraft unikernel framework with QEMU or Firecracker.
60+
61+
## Getting Started
62+
63+
To start building unikernels with OCaml, visit the [MirageOS Getting Started Guide](https://mirage.io/docs/). The guide walks you through:
64+
65+
- Installing the MirageOS tooling
66+
- Creating your first unikernel application
67+
- Configuring and building for different targets
68+
- Deploying your unikernel
69+
70+
## Learn More
71+
72+
- [Dune Manual: Executable Linking Modes](https://dune.readthedocs.io/en/stable/reference/dune/executable.html#linking-modes) - How to specify native, bytecode, or other compilation modes in Dune
73+
- [MirageOS Documentation](https://mirage.io/docs/) - Comprehensive guides and tutorials
74+
- [MirageOS Blog](https://mirage.io/blog/) - Updates and advanced topics
75+
- [Solo5 Documentation](https://github.com/Solo5/solo5) - Details on Solo5 targets and deployment
76+
- [MirageOS Examples](https://github.com/mirage/mirage-skeleton) - Sample unikernel applications to explore
77+
78+
## Community
79+
80+
- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
81+
- [MirageOS Mailing List](https://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel) - Development discussions
82+
- IRC: `#mirage` on Libera.Chat

‎data/tool_pages/platform/2in_00_the_ocaml_infrastructure.md‎ renamed to ‎data/tool_pages/platform/3in_00_the_ocaml_infrastructure.md‎

File renamed without changes.

0 commit comments

Comments
 (0)