ocaml-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

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

### 3. Create Library dune Files

For each library (from `.mllib` files):

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

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

```dune
(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:

```dune
(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:

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

Common warnings to suppress in vendored code:
- `-w -27` - unused variable

### 6. Create Test dune File

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

For optional tests:

```dune
(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"}
]
```

4. Update build commands:

```
build: [
  ["dune" "subst"] {dev}
  ["dune" "build" "-p"