ocaml-project-setup

avsm's avatarfrom avsm

Standards for OCaml project metadata files. Use when initializing a new OCaml library/module, preparing for opam release, setting up CI, or discussing project structure. Not for normal code edits.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 25, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill streamlines OCaml project initialization and maintenance by enforcing standardized metadata and directory structures. It automates the creation of essential configuration files like dune-project, .ocamlformat, and CI workflows, ensuring projects are compliant with opam release requirements and follow best practices for interface design and logging.

Use Cases

  • New Project Scaffolding: Quickly initialize a new OCaml library or module with a standardized directory structure, including pre-configured lib, bin, and test directories.
  • Opam Release Preparation: Automatically generate and validate dune-project files and opam metadata to ensure the project is ready for official package distribution.
  • CI/CD Pipeline Setup: Generate optimized configuration files for GitHub Actions, GitLab CI, or Tangled, specifically tailored for OCaml build environments.
  • Enforcing Documentation Standards: Automatically set up .mli interface files and documentation templates to ensure clear API boundaries and consistent code comments.
  • Consistent Code Formatting: Deploy standardized .ocamlformat configurations across a project to maintain a uniform coding style and simplify code reviews.
nameocaml-project-setup
description"Standards for OCaml project metadata files. Use when initializing a new OCaml library/module, preparing for opam release, setting up CI, discussing project structure, or ensuring proper .mli/.ocamlformat files exist."
licenseISC

OCaml Project Setup

Required Files

Every OCaml project needs:

File Purpose
dune-project Build configuration, opam generation
dune (root) Top-level build rules
.ocamlformat Code formatting (required)
.gitignore VCS ignores
LICENSE.md License file
README.md Project documentation
CI config GitHub Actions / GitLab CI / Tangled

Interface Files (.mli)

Every library module must have an .mli file for:

  • Clear API boundaries
  • Proper encapsulation
  • Documentation surface
(* lib/user.mli *)

(** User management.

    This module provides types and functions for user operations. *)

type t
(** A user. *)

val create : name:string -> email:string -> t
(** [create ~name ~email] creates a new user. *)

val name : t -> string
(** [name u] is the user's name. *)

val pp : t Fmt.t
(** [pp] is a pretty-printer for users. *)

Documentation style:

  • Functions: [name args] is/does ...
  • Values: [name] is ...
  • End with period

Standard Module Interface

For modules with a central type t:

type t
val v : ... -> t                           (* pure constructor *)
val create : ... -> (t, Error.t) result    (* constructor with I/O *)
val pp : t Fmt.t                           (* pretty-printer - required *)
val equal : t -> t -> bool                 (* equality *)
val compare : t -> t -> int                (* comparison *)
val of_json : Yojson.Safe.t -> (t, string) result
val to_json : t -> Yojson.Safe.t

OCamlFormat Configuration

Required: .ocamlformat in project root.

version = 0.28.1

Run dune fmt before every commit.

Logging Setup

Each module using logging should declare a source:

let log_src = Logs.Src.create "project.module"
module Log = (val Logs.src_log log_src : Logs.LOG)

Log levels:

  • Log.app - Always shown (startup)
  • Log.err - Critical errors
  • Log.warn - Potential issues
  • Log.info - Informational
  • Log.debug - Verbose debugging

User Configuration

Read from ~/.claude/ocaml-config.json:

{
  "author": { "name": "Name", "email": "email@example.com" },
  "license": "ISC",
  "ci_platform": "github",
  "git_hosting": { "type": "github", "org": "username" },
  "ocaml_version": "5.2.0"
}

License Headers

Every source file starts with license header:

(*---------------------------------------------------------------------------
  Copyright (c) {{YEAR}} {{AUTHOR}}. All rights reserved.
  SPDX-License-Identifier: ISC
 ---------------------------------------------------------------------------*)

Project Structure

project/
├── dune-project
├── dune
├── .ocamlformat
├── .gitignore
├── LICENSE.md
├── README.md
├── lib/
│   ├── dune
│   ├── foo.ml
│   └── foo.mli         # Required for every .ml
├── bin/
│   ├── dune
│   └── main.ml
├── test/
│   ├── dune
│   ├── test.ml
│   └── test_foo.ml
└── .github/workflows/  # or .gitlab-ci.yml

dune-project

(lang dune 3.16)
(name project_name)
(generate_opam_files true)
(maintenance_intent "(latest)")

(package
 (name project_name)
 (synopsis "Short description")
 (description "Longer description")
 (depends
  (ocaml (>= 5.2))
  (alcotest :with-test)))

Note: Don't add (version ...) - added at release time.

Templates

See templates/ directory for:

  • dune-project.template
  • dune-root.template
  • ci-github.yml
  • ci-gitlab.yml
  • ci-tangled.yml
  • gitignore
  • ocamlformat
  • LICENSE-ISC.md
  • LICENSE-MIT.md
  • README.template.md