(docs) add pages describing all of OCaml's compilation targets

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 optimised machine code for production deployments."
+category: "Compilation Targets"
+---
+
+OCaml can compile to native code, delivering high-performance executables with optimised 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 an integrated runtime and garbage collector. Key characteristics:
+
+- Faster runtime performance than bytecode
+- Standalone executables requiring no external runtime
+- Cross-module inlining and optimisation
+- Production-ready deployments
+
+## When to Use Native Code
+
+**Use native code** (ocamlopt) when you need faster runtime performance in production, want standalone executables, or are deploying to end users.
+
+**Use bytecode** (ocamlc) for fast iteration during development, CI/testing environments where compilation speed matters, or maximum portability.
+
+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.
+
+## Platform Support
+
+The native-code compiler is available only on 64-bit systems (OCaml 5.0+):
+
+- **x86-64 (AMD64)** - Linux, macOS, Windows
+- **ARM64 (AArch64)** - Linux, macOS (including Apple Silicon)
+- **RISC-V** - Linux
+- **IBM Z (s390x)** - Linux (OCaml 5.1+)
+- **PowerPC (PPC64)** - Linux
+
+All native code platforms use **63-bit integers** (with 1 bit reserved for the garbage collector tag).
+
+**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.
+
+If your target platform lacks native code support, the bytecode compiler provides a highly portable fallback.
+
+## 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 Manual: Native-code Compilation](https://ocaml.org/manual/latest/native.html) - Complete ocamlopt reference
+- [Using the OCaml Compiler Toolchain](https://ocaml.org/docs/using-the-ocaml-compiler-toolchain) - Practical compilation guide
+- [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

@@ -0,0 +1,51 @@
+---
+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 primitive C 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 behaviour
+- Easier debugging with built-in tools
+
+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).
+
+## When to Use Bytecode
+
+**Use bytecode** when you want fast compilation during development, need maximum portability, or are targeting platforms without a native code compiler.
+
+**Use native code** (ocamlopt) when you need maximum runtime performance in production deployments.
+
+Many OCaml developers use bytecode during development for its fast compile times, then switch to native code for production releases.
+
+## File Extensions
+
+The bytecode compiler produces several types of files:
+
+- **.cmo** - Compiled module object (bytecode)
+- **.cmi** - Compiled module interface
+- **.cma** - Bytecode library archive (collection of .cmo files)
+- **executable** - Bytecode executable (often with no extension or .byte extension)
+
+## 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 Manual: Batch Compilation](https://ocaml.org/manual/latest/comp.html) - Complete reference for ocamlc
+- [OCaml Manual: Runtime System](https://ocaml.org/manual/latest/runtime.html) - Details on ocamlrun and bytecode execution
+- [Compiler Backend Documentation](https://ocaml.org/docs/compiler-backend) - How the OCaml compiler works
+- [Compiling OCaml Projects](https://ocaml.org/docs/compiling-ocaml-projects) - Getting started guide

data/tool_pages/platform/2ct_02_javascript.md

@@ -0,0 +1,60 @@
+---
+id: "javascript-target"
+short_title: "JavaScript"
+title: "Compilation Targets: JavaScript"
+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."
+category: "Compilation Targets"
+---
+
+OCaml can compile to JavaScript, enabling you to write type-safe, high-performance code that runs in web browsers and Node.js environments.
+
+## Available Tools
+
+### Js_of_ocaml
+
+[Js_of_ocaml](https://ocsigen.org/js_of_ocaml/) compiles OCaml bytecode to JavaScript. It provides:
+
+- Excellent performance with compact output
+- Strong integration with existing JavaScript libraries
+- Access to browser APIs and DOM manipulation
+- Support for the full OCaml language, including OCaml 5 effects
+- Compatibility with most OCaml libraries and the standard library
+- **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
+- Optimised bundle sizes for modern web applications
+- Support for React and modern frontend frameworks
+
+Melange is ideal when you're building JavaScript-first applications and want seamless integration with the JavaScript ecosystem.
+
+**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.
+
+## Choosing a Tool
+
+**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.
+
+**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.
+
+## 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
+- [Js_of_ocaml Manual](https://ocsigen.org/js_of_ocaml/latest/manual/overview) - Comprehensive guide and API reference
+- [Melange Playground](https://melange.re/v5.0.0/playground/) - Try Melange in your browser
+- [OCaml for Web Development](https://ocaml.org/docs/web-development) - Overview of web development with OCaml
+
+## Community
+
+- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
+- [Melange Discord](https://discord.gg/reasonml) - Melange and Reason community

data/tool_pages/platform/2ct_03_wasm.md

@@ -0,0 +1,66 @@
+---
+id: "wasm-target"
+short_title: "WebAssembly"
+title: "Compilation Targets: WebAssembly"
+description: "Compile OCaml to WebAssembly with wasm_of_ocaml and Wasocaml. Build high-performance applications for browsers, servers, and edge computing with Wasm."
+category: "Compilation Targets"
+---
+
+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.
+
+## What is WebAssembly?
+
+WebAssembly is a binary instruction format designed as a portable compilation target for programming languages. It provides:
+- Near-native performance in web browsers and standalone runtimes
+- Sandboxed execution environment for security
+- Broad platform support across browsers, servers, and edge computing
+- Compact binary format for fast loading and parsing
+
+## Available Tools
+
+### wasm_of_ocaml
+
+[wasm_of_ocaml](https://github.com/ocsigen/js_of_ocaml/blob/master/README_wasm_of_ocaml.md) compiles OCaml bytecode to WebAssembly. It provides:
+- Full OCaml language support, including the standard library and OCaml 5 effects
+- Compatibility with existing OCaml libraries
+- Integration with JavaScript through Js_of_ocaml-style bindings
+- 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
+- Optimised performance through the Flambda optimiser
+- 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 for use in production.
+
+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, WebAssembly, or other compilation modes in Dune
+- [ocaml-wasm Organisation](https://github.com/ocaml-wasm) - Coordination hub for OCaml WebAssembly efforts
+- [WebAssembly.org](https://webassembly.org/) - WebAssembly specification and documentation
+- [WASM-GC Proposal](https://github.com/WebAssembly/gc) - Garbage Collection proposal for WebAssembly
+
+## Community
+
+- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
+- [ocaml-wasm Updates](https://discuss.ocaml.org/tag/wasm) - Follow WebAssembly developments in OCaml

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 specialised 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 specialised unikernel targets through [MirageOS](https://mirage.io), a library operating system that creates secure, single-purpose applications.
+
+## What are 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:
+
+- 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 specialised monitor layers
+
+MirageOS lets you write OCaml applications once and deploy them as unikernels to different virtualisation 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 paravirtualised guest (PVHv2 mode)
+
+### 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 virtualisation 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 virtualisation.
+
+**Use Xen** when deploying to Xen-based infrastructure or cloud providers that support Xen.
+
+**Use Unikraft targets** when you want to use the Unikraft unikernel framework with QEMU or Firecracker.
+
+## Getting Started
+
+To start building unikernels with OCaml, visit the [MirageOS Getting Started Guide](https://mirage.io/docs/). The guide walks you through:
+
+- Installing the MirageOS tooling
+- Creating your first unikernel application
+- Configuring and building for different targets
+- Deploying your unikernel
+
+## 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
+- [MirageOS Documentation](https://mirage.io/docs/) - Comprehensive guides and tutorials
+- [MirageOS Blog](https://mirage.io/blog/) - Updates and advanced topics
+- [Solo5 Documentation](https://github.com/Solo5/solo5) - Details on Solo5 targets and deployment
+- [MirageOS Examples](https://github.com/mirage/mirage-skeleton) - Sample unikernel applications to explore
+
+## Community
+
+- [Discuss OCaml Forums](https://discuss.ocaml.org/) - Ask questions in the Ecosystem category
+- [MirageOS Mailing List](https://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel) - Development discussions
+- IRC: `#mirage` on Libera.Chat