Skip to content

README.md

Latest commit

 

History

History
167 lines (120 loc) · 7.68 KB

README.md

File metadata and controls

167 lines (120 loc) · 7.68 KB

OCaml DevContainer

Build Tests Docker Pulls

Create a GitHub Codespace

A ready-to-use OCaml 5.4 development environment packaged as a devcontainer. Designed for tutorials and workshops where zero-friction onboarding is critical — participants get a working environment in minutes, regardless of their OS or editor.

Choose your workflow

VS Code

This is for you if:

  • You use VS Code as your primary editor
  • You want graphical IDE features (hover types, diagnostics, go-to-definition)
  • You have Docker (or Podman) installed locally
git clone https://github.com/tarides/ocaml-devcontainer.git
code ocaml-devcontainer
# Click "Reopen in Container" when prompted

Full guide

DevContainer CLI

This is for you if:

npm install -g @devcontainers/cli
git clone https://github.com/tarides/ocaml-devcontainer.git
cd ocaml-devcontainer
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . vim examples/hello/hello.ml

Full guide

GitHub Codespaces

This is for you if:

  • You don't want to install anything on your machine
  • You want the fastest possible start (~2 minutes)
  • You're attending a workshop or tutorial

Click "Create a GitHub Codespace" above, or:

gh codespace create --repo tarides/ocaml-devcontainer
gh codespace ssh

Full guide

What's inside

Image variants

Image Switches Size Codespaces
ocaml-devcontainer ocaml ~4.5 GB Yes
ocaml-devcontainer-rocq ocaml ~5.5 GB Yes
ocaml-devcontainer-tsan ocaml, ocaml+tsan ~7.5 GB No
oxcaml-devcontainer oxcaml ~18.8 GB Yes

The default image (ocaml-devcontainer) ships a single ocaml switch. See the Rocq variant, TSan variant, and OxCaml variant sections below for the other images.

Installed tools

Category Tools
Compilers OCaml 5.4.0
Build & dev dune, ocaml-lsp-server, merlin, utop
Testing alcotest, ppx_inline_test, ppx_expect, qcheck
Profiling landmarks, memtrace, runtime_events_tools (olly), printbox
Libraries base
Debugging gdb, lldb, valgrind, rr, perf, strace, ltrace, bpftrace, hyperfine
Editors vim, emacs

Common commands

dune build           # Build the project
dune test            # Run tests
utop                 # Interactive REPL

Using this devcontainer in your project

Want contributors to your OCaml project to get a working environment with one click? Add a .devcontainer/devcontainer.json that references the pre-built image.

Full guide

For tutorial and workshop authors

This environment is designed to be extended. Create a tutorial-specific image layered on top:

FROM ghcr.io/tarides/ocaml-devcontainer:latest
RUN opam install -y lwt eio        # Add your packages
COPY exercises/ /home/vscode/exercises/

Tips:

  • Test beforehand — spin up a Codespace and run through your exercises
  • Provide a Codespace link — attendees click one button to get started
  • Have a local fallback — some venues have poor wifi; the DevContainer CLI workflow works offline once images are pulled
  • Clean up after — remind attendees to delete their Codespaces to avoid charges (gh codespace delete --all)

Rocq variant

The Rocq variant adds Rocq (formerly Coq) on top of the standard OCaml image. Same ocaml switch, same tools, plus the Rocq proof assistant.

# Pre-built image
devcontainer up --workspace-folder . --config .devcontainer-rocq/devcontainer.json

# Local build
docker build -t ocaml-devcontainer-base base/
docker build -t ocaml-devcontainer dev/
docker build -t ocaml-devcontainer-rocq rocq/
devcontainer up --workspace-folder . --config .devcontainer-rocq-from-scratch/devcontainer.json

TSan variant

The TSan variant adds an ocaml+tsan switch for ThreadSanitizer race detection. It requires vm.mmap_rnd_bits <= 28 at runtime — use it for local development or CI, not Codespaces.

# Pre-built image
devcontainer up --workspace-folder . --config .devcontainer-tsan/devcontainer.json

# Switch to TSan
opam switch ocaml+tsan
eval $(opam env)

# Local build
docker build -t ocaml-devcontainer-base base/
docker build -t ocaml-devcontainer dev/
sudo sysctl -w vm.mmap_rnd_bits=28
docker build -t ocaml-devcontainer-tsan tsan/
devcontainer up --workspace-folder . --config .devcontainer-tsan-from-scratch/devcontainer.json

OxCaml variant

An OxCaml variant is available with Jane Street's OxCaml compiler. It has a single oxcaml switch with OxCaml 5.2.0+ox — supports local_ allocations and other OxCaml features. The switch includes await and parallel packages from the oxcaml opam repository.

# Pre-built image
devcontainer up --workspace-folder . --config .devcontainer-oxcaml/devcontainer.json

# Local build
docker build -t oxcaml-devcontainer-base oxcaml-base/
docker build -t oxcaml-devcontainer --build-arg BASE_IMAGE=oxcaml-devcontainer-base oxcaml-dev/
devcontainer up --workspace-folder . --config .devcontainer-oxcaml-from-scratch/devcontainer.json

Hacking

See HACKING.md for building images, running tests, and CI details.