(docs) add pages describing all of OCaml's compilation targets #3378
+308
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
sabine
added a commit
that referenced
this pull request
Oct 22, 2025
|
The documentation of the various platforms could include the word size; in JSOO an OCaml int is 31 bit, whereas on Intel, AMD, Arm it is 63 bit. This can limit portability of code. |
Member
|
This is great Sabine, thanks a bunch! I support Christian's point about
A couple of things that struck me:
|
dinosaure
reviewed
Oct 23, 2025
dinosaure
reviewed
Oct 23, 2025
dinosaure
reviewed
Oct 23, 2025
dinosaure
reviewed
Oct 23, 2025
shym
reviewed
Oct 23, 2025
F-Loyer
reviewed
Oct 28, 2025
Contributor
There was a problem hiding this comment.
The contribution is really nice, but I guess a reference to the dune manual, especially https://dune.readthedocs.io/en/stable/reference/dune/executable.html#linking-modes can be handy, since Dune is more likely the way to specify if the compilation is native, byte, or else…
…nking out to reference docs of tools or the compiler
sabine
force-pushed
the
wasm_landing_page
branch
from
7f5cebf to
91e2351
Compare
ILeandersson
approved these changes
Nov 4, 2025
Contributor
|
Hi, I have seen your PR about OCaml targets and dune. According to the dune manual, wasm is supported too (then the dune link could added there too).About mirage, the proposed hello world of the official documentation use Make to build the whole unikernel instead of dune. I don’t think it is relevant to point dune there. (I suppose Mirage is a native build with a specific runtime or something like that, but I havn’t search enough to be sure). Yours sincerely --Frédéric LoyerOn 4 Nov 2025, at 16:49, ILeandersson ***@***.***> wrote:
@ILeandersson approved this pull request.
In data/tool_pages/platform/2ct_00_native.md:
@@ -0,0 +1,49 @@
+---
+id: "native-target"
+short_title: "Native"
+title: "Compilation Targets: Native"
+description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimized machine code for production deployments."
+category: "Compilation Targets"
+---
+
+OCaml can compile to native code, delivering high-performance executables with optimized machine code for production environments.
⬇️ Suggested change
-OCaml can compile to native code, delivering high-performance executables with optimized machine code for production environments.
+OCaml can compile to native code, delivering high-performance executables with optimised machine code for production environments.
In data/tool_pages/platform/2ct_00_native.md:
@@ -0,0 +1,49 @@
+---
+id: "native-target"
+short_title: "Native"
+title: "Compilation Targets: Native"
+description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimized machine code for production deployments."
⬇️ Suggested change
-description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimized machine code for production deployments."
+description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimised machine code for production deployments."
In data/tool_pages/platform/2ct_00_native.md:
+---
+id: "native-target"
+short_title: "Native"
+title: "Compilation Targets: Native"
+description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimized machine code for production deployments."
+category: "Compilation Targets"
+---
+
+OCaml can compile to native code, delivering high-performance executables with optimized machine code for production environments.
+
+## What is OCaml Native Code?
+
+OCaml native code is generated by **ocamlopt**, the native-code compiler that produces standalone executables with integrated runtime and garbage collector. Key characteristics:
+
+- Faster runtime performance than bytecode
+- Stand-alone executables requiring no external runtime
⬇️ Suggested change
-- Stand-alone executables requiring no external runtime
+- Standalone executables requiring no external runtime
In data/tool_pages/platform/2ct_00_native.md:
+id: "native-target"
+short_title: "Native"
+title: "Compilation Targets: Native"
+description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimized machine code for production deployments."
+category: "Compilation Targets"
+---
+
+OCaml can compile to native code, delivering high-performance executables with optimized machine code for production environments.
+
+## What is OCaml Native Code?
+
+OCaml native code is generated by **ocamlopt**, the native-code compiler that produces standalone executables with integrated runtime and garbage collector. Key characteristics:
+
+- Faster runtime performance than bytecode
+- Stand-alone executables requiring no external runtime
+- Cross-module inlining and optimization
⬇️ Suggested change
-- Cross-module inlining and optimization
+- Cross-module inlining and optimisation
In data/tool_pages/platform/2ct_00_native.md:
@@ -0,0 +1,49 @@
+---
+id: "native-target"
+short_title: "Native"
+title: "Compilation Targets: Native"
+description: "Compile OCaml to high-performance native code with ocamlopt. Maximum runtime performance with optimized machine code for production deployments."
+category: "Compilation Targets"
+---
+
+OCaml can compile to native code, delivering high-performance executables with optimized machine code for production environments.
+
+## What is OCaml Native Code?
+
+OCaml native code is generated by **ocamlopt**, the native-code compiler that produces standalone executables with integrated runtime and garbage collector. Key characteristics:
⬇️ Suggested change
-OCaml native code is generated by **ocamlopt**, the native-code compiler that produces standalone executables with integrated runtime and garbage collector. Key characteristics:
+OCaml native code is generated by **ocamlopt**, the native-code compiler that produces standalone executables with an integrated runtime and garbage collector. Key characteristics:
In data/tool_pages/platform/2ct_01_bytecode.md:
+id: "bytecode-target"
+short_title: "Bytecode"
+title: "Compilation Targets: Bytecode"
+description: "Compile OCaml to portable bytecode with ocamlc. Fast compilation, excellent portability, and easy debugging for OCaml development and production."
+category: "Compilation Targets"
+---
+
+OCaml can compile to bytecode, providing fast compilation, excellent portability, and predictable execution across different platforms.
+
+## What is OCaml Bytecode?
+
+OCaml bytecode is a portable intermediate representation of OCaml programs that is executed by the OCaml bytecode interpreter. The bytecode system consists of:
+
+- **ocamlc** - The bytecode compiler that compiles OCaml source files to bytecode
+- **ocamlrun** - The bytecode interpreter that executes bytecode programs
+- **Runtime system** - Includes the bytecode interpreter, garbage collector, and C primitive operations
⬇️ Suggested change
-- **Runtime system** - Includes the bytecode interpreter, garbage collector, and C primitive operations
+- **Runtime system** - Includes the bytecode interpreter, garbage collector, and primitive C operations
In data/tool_pages/platform/2ct_01_bytecode.md:
+
+OCaml can compile to bytecode, providing fast compilation, excellent portability, and predictable execution across different platforms.
+
+## What is OCaml Bytecode?
+
+OCaml bytecode is a portable intermediate representation of OCaml programs that is executed by the OCaml bytecode interpreter. The bytecode system consists of:
+
+- **ocamlc** - The bytecode compiler that compiles OCaml source files to bytecode
+- **ocamlrun** - The bytecode interpreter that executes bytecode programs
+- **Runtime system** - Includes the bytecode interpreter, garbage collector, and C primitive operations
+
+Bytecode provides several advantages over native compilation:
+- Fast compilation speed
+- Portability across all platforms where OCaml is installed
+- Smaller compiler footprint
+- Predictable and consistent execution behavior
⬇️ Suggested change
-- Predictable and consistent execution behavior
+- Predictable and consistent execution behaviour
In data/tool_pages/platform/2ct_02_javascript.md:
+- **32-bit integers** (JavaScript's bit operations are 32-bit)
+
+**Note:** While Js_of_ocaml supports OCaml 5 effects, it has limited support for Domains (multicore parallelism).
+
+Js_of_ocaml is ideal when you want to leverage existing OCaml code in web applications or need access to the complete OCaml ecosystem.
+
+**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.
+
+### Melange
+
+[Melange](https://melange.re) compiles OCaml and Reason to JavaScript with a focus on JavaScript ecosystem integration. It provides:
+
+- Idiomatic JavaScript output designed for readability
+- Deep integration with NPM packages and JavaScript tooling
+- Excellent TypeScript interoperability
+- Optimized bundle sizes for modern web applications
⬇️ Suggested change
-- Optimized bundle sizes for modern web applications
+- Optimised bundle sizes for modern web applications
In data/tool_pages/platform/2ct_03_wasm.md:
+- Ability to run OCaml code in browsers and WASM runtimes
+- Shared infrastructure with Js_of_ocaml for web development
+- **31-bit integers** (similar to traditional OCaml bytecode on 32-bit systems)
+
+**Note:** While wasm_of_ocaml supports OCaml 5 effects, it has limited support for Domains (multicore parallelism).
+
+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.
+
+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.
+
+### Wasocaml (Experimental)
+
+[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:
+- Direct compilation from OCaml's Flambda intermediate representation to WASM-GC
+- Native WebAssembly garbage collection support
+- Optimized performance through the Flambda optimizer
⬇️ Suggested change
-- Optimized performance through the Flambda optimizer
+- Optimised performance through the Flambda optimiser
In data/tool_pages/platform/2ct_03_wasm.md:
+**Note:** While wasm_of_ocaml supports OCaml 5 effects, it has limited support for Domains (multicore parallelism).
+
+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.
+
+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.
+
+### Wasocaml (Experimental)
+
+[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:
+- Direct compilation from OCaml's Flambda intermediate representation to WASM-GC
+- Native WebAssembly garbage collection support
+- Optimized performance through the Flambda optimizer
+- Support for functional programming language features in WebAssembly
+- **31-bit integers** (similar to traditional OCaml bytecode on 32-bit systems)
+
+**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 production use.
⬇️ Suggested change
-**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 production use.
+**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.
In data/tool_pages/platform/2ct_03_wasm.md:
+- **31-bit integers** (similar to traditional OCaml bytecode on 32-bit systems)
+
+**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 production use.
+
+Visit the [Wasocaml repository](https://github.com/OCamlPro/wasocaml) to learn how to install the Wasocaml compiler switch and explore its experimental features.
+
+## Choosing a Tool
+
+**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.
+
+**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.
+
+## Learn More
+
+- [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
+- [ocaml-wasm Organization](https://github.com/ocaml-wasm) - Coordination hub for OCaml WebAssembly efforts
⬇️ Suggested change
-- [ocaml-wasm Organization](https://github.com/ocaml-wasm) - Coordination hub for OCaml WebAssembly efforts
+- [ocaml-wasm Organisation](https://github.com/ocaml-wasm) - Coordination hub for OCaml WebAssembly efforts
In data/tool_pages/platform/2ct_04_unikernels.md:
@@ -0,0 +1,82 @@
+---
+id: "unikernel-target"
+short_title: "Unikernels"
+title: "Compilation Targets: Unikernels"
+description: "Compile OCaml to specialized unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
⬇️ Suggested change
-description: "Compile OCaml to specialized unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
+description: "Compile OCaml to specialised unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
In data/tool_pages/platform/2ct_04_unikernels.md:
@@ -0,0 +1,82 @@
+---
+id: "unikernel-target"
+short_title: "Unikernels"
+title: "Compilation Targets: Unikernels"
+description: "Compile OCaml to specialized unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
+category: "Compilation Targets"
+---
+
+OCaml can compile to specialized unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
⬇️ Suggested change
-OCaml can compile to specialized unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
+OCaml can compile to specialised unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
In data/tool_pages/platform/2ct_04_unikernels.md:
@@ -0,0 +1,82 @@
+---
+id: "unikernel-target"
+short_title: "Unikernels"
+title: "Compilation Targets: Unikernels"
+description: "Compile OCaml to specialized unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
+category: "Compilation Targets"
+---
+
+OCaml can compile to specialized unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
+
+## What are Unikernels?
+
+Unikernels are specialized, 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:
⬇️ Suggested change
-Unikernels are specialized, 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:
+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:
In data/tool_pages/platform/2ct_04_unikernels.md:
+short_title: "Unikernels"
+title: "Compilation Targets: Unikernels"
+description: "Compile OCaml to specialized unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
+category: "Compilation Targets"
+---
+
+OCaml can compile to specialized unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
+
+## What are Unikernels?
+
+Unikernels are specialized, 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:
+
+- Include only the necessary OS components, resulting in tiny footprints (often just a few megabytes)
+- Boot in milliseconds
+- Have reduced attack surfaces due to minimal code
+- Run directly on hypervisors or specialized monitor layers
⬇️ Suggested change
-- Run directly on hypervisors or specialized monitor layers
+- Run directly on hypervisors or specialised monitor layers
In data/tool_pages/platform/2ct_04_unikernels.md:
+description: "Compile OCaml to specialized unikernel targets using MirageOS. Create minimal, fast-booting applications for hvt, virtio, Xen, and more with reduced attack surfaces."
+category: "Compilation Targets"
+---
+
+OCaml can compile to specialized unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
+
+## What are Unikernels?
+
+Unikernels are specialized, 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:
+
+- Include only the necessary OS components, resulting in tiny footprints (often just a few megabytes)
+- Boot in milliseconds
+- Have reduced attack surfaces due to minimal code
+- Run directly on hypervisors or specialized monitor layers
+
+MirageOS lets you write OCaml applications once and deploy them as unikernels to different virtualization platforms.
⬇️ Suggested change
-MirageOS lets you write OCaml applications once and deploy them as unikernels to different virtualization platforms.
+MirageOS lets you write OCaml applications once and deploy them as unikernels to different virtualisation platforms.
In data/tool_pages/platform/2ct_04_unikernels.md:
+
+MirageOS lets you write OCaml applications once and deploy them as unikernels to different virtualization platforms.
+
+## Available Targets
+
+MirageOS supports compilation to several unikernel backends:
+
+### Solo5 Targets
+
+[Solo5](https://github.com/Solo5/solo5) is a sandboxed execution environment that provides multiple deployment options:
+
+- **hvt** (Hardware Virtualized Tender) - Runs on KVM/Linux, bhyve/FreeBSD, and vmm/OpenBSD with minimal overhead
+- **spt** (Sandboxed Process Tender) - Runs as a regular Unix process with seccomp sandboxing on Linux
+- **virtio** - Runs on standard virtio-based hypervisors including QEMU/KVM, Google Compute Engine, and OpenStack
+- **muen** - Runs on the Muen Separation Kernel
+- **xen** - Runs on the Xen hypervisor as a paravirtualized guest (PVHv2 mode)
⬇️ Suggested change
-- **xen** - Runs on the Xen hypervisor as a paravirtualized guest (PVHv2 mode)
+- **xen** - Runs on the Xen hypervisor as a paravirtualised guest (PVHv2 mode)
In data/tool_pages/platform/2ct_04_unikernels.md:
+### Unikraft Targets
+
+[Unikraft](https://unikraft.org) is a general Unikernel Development Kit that can be used as a MirageOS backend:
+
+- **unikraft-qemu** - Runs on the [QEMU](https://www.qemu.org/) virtual machine monitor
+- **unikraft-firecracker** - Runs on the [Firecracker](https://firecracker-microvm.github.io/) virtual machine monitor
+
+### Unix
+
+- **unix** - Runs as a standard Unix process (useful for development and testing)
+
+## Choosing a Target
+
+**Use Unix** when you're developing and testing your unikernel locally.
+
+**Use hvt** when you want lightweight virtualization on Linux, FreeBSD, or OpenBSD with KVM, bhyve, or vmm.
⬇️ Suggested change
-**Use hvt** when you want lightweight virtualization on Linux, FreeBSD, or OpenBSD with KVM, bhyve, or vmm.
+**Use hvt** when you want lightweight virtualisation on Linux, FreeBSD, or OpenBSD with KVM, bhyve, or vmm.
In data/tool_pages/platform/2ct_04_unikernels.md:
+- **unikraft-qemu** - Runs on the [QEMU](https://www.qemu.org/) virtual machine monitor
+- **unikraft-firecracker** - Runs on the [Firecracker](https://firecracker-microvm.github.io/) virtual machine monitor
+
+### Unix
+
+- **unix** - Runs as a standard Unix process (useful for development and testing)
+
+## Choosing a Target
+
+**Use Unix** when you're developing and testing your unikernel locally.
+
+**Use hvt** when you want lightweight virtualization on Linux, FreeBSD, or OpenBSD with KVM, bhyve, or vmm.
+
+**Use virtio** when deploying to cloud providers like Google Compute Engine, or standard KVM/QEMU setups.
+
+**Use spt** when you want process-level isolation on Linux without full virtualization.
⬇️ Suggested change
-**Use spt** when you want process-level isolation on Linux without full virtualization.
+**Use spt** when you want process-level isolation on Linux without full virtualisation.
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>
|
Collaborator
Author
|
Thanks everyone, I'll merge this, and if there's any more feedback / corrections / changes, they can be done by opening a new PR! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.