dune-migration

OCaml Build System Migration

When to Use This Skill

Invoke this skill when:

• Converting a project from ocamlbuild to dune
• Discussing _tags, .mllib, or pkg.ml files
• Migrating from topkg to dune
• Understanding ocamlbuild artifacts

Process Overview

1. Analyze the Existing Build

Read these files to understand the project:

• _tags - ocamlbuild compilation flags and package dependencies
• pkg/pkg.ml - topkg package description
• pkg/META - findlib metadata
• *.mllib files - module lists for libraries
• opam - package dependencies

2. Create dune-project

(lang dune 3.20)
(name <package-name>)
(generate_opam_files true)

3. Create Library dune Files

For each library (from .mllib files):

(library
 (name <library_name>)
 (public_name <package.subname>)
 (libraries <dependencies>))

For optional libraries (from pkg/pkg.ml):

(library
 (name <library_name>)
 (public_name <package.subname>)
 (optional)
 (libraries <dependencies>))

4. Handle Toplevel Init Files

Files like *_top_init.ml shouldn't be compiled as modules:

(library
 (name lib_name)
 (modules lib_module)  ; Explicitly list modules
 (libraries deps))

(install
 (package pkg)
 (section lib)
 (files lib_top_init.ml))

5. Handle Warnings

If the original code triggers warnings:

(library
 (name lib)
 (flags (:standard -w -27)))

Common warnings to suppress in vendored code:

• -w -27 - unused variable

6. Create Test dune File

(test
 (name test_name)
 (libraries lib_name alcotest))

For optional tests:

(executable
 (name test_optional)
 (modules test_optional)
 (optional)
 (libraries lib some_optional_lib))

7. Update opam File

1. Rename opam to <package>.opam
2. Remove ocamlbuild/topkg dependencies
3. Add dune:

depends: [
  "ocaml" {>= "4.14.0"}
  "dune" {>= "3.0"}
]

1. Update build commands:

build: [
  ["dune" "subst"] {dev}
  ["dune" "build" "-p" name "-j" jobs]
  ["dune" "runtest" "-p" name "-j" jobs] {with-test}
  ["dune" "build" "@doc" "-p" name "-j" jobs] {with-doc}
]