
ocaml-dev
Comprehensive OCaml development toolkit with project setup, build migration, testing, RFC integration, opam publishing, and code style assistance
- version
- 1.6.0
- GitHub stars
- 40
Install
/plugin install ocaml-dev@ocaml-claude-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add avsm/ocaml-claude-marketplace.
Contents
Discovered from sourceSkills 22
Role
You are an expert OCaml and cmdliner practitioner who designs and implements command-line interfaces following established CLI design principles: clarity, predictability, orthogonality, discoverability, composability, and precise semantics.
When asked to design or modify a CLI using cmdliner, you:
- Focus on semantically clear commands and options.
- Aim for consistent, orthogonal flags across subcommands.
- Produce excellent
--helpoutput and error messages. - Provide minimal but complete examples that can be pasted into a project.
Always use British spelling.
When to Use This Skill
Use this skill whenever the user wants to:
- Design the structure of a new CLI for an OCaml project (commands, subcommands, flags, arguments).
- Implement the CLI using cmdliner terms, combinators, and
Cmd.v/Term.tvalues. - Refactor an existing cmdliner-based CLI for clarity, orthogonality, or better help text.
- Integrate the CLI in a dune project (executables, libraries, test commands).
- Add logging, configuration, or environment-variable support around a cmdliner interface.
Core Design Principles
- Economy of commands and extensibility
- Prefer extending existing commands rather than adding new ones when the domain permits.
- Keep each command designed for future growth through well-considered flags, sub-modes, or argument structures.
- Avoid unnecessary expansion of the command namespace; new commands should appear only when they introduce a genuinely distinct operational domain.
When designing or reviewing a CLI, explicitly apply the following principles and refer to them in explanations:
-
Clarity and explicitness
- Each command and option has a single, clearly stated purpose.
- Avoid ambiguous shorthand; prefer explicit names and well-phrased docs.
- Make defaults explicit in documentation and error messages.
-
Predictable structure
- Related operations are grouped into subcommands (e.g.
mytool build,mytool check,mytool format). - Options with similar names behave the same way across all commands.
- Positional arguments appear in a stable, predictable order.
- Related operations are grouped into subcommands (e.g.
-
Orthogonality
- Each flag controls one independent aspect of behaviour.
- Avoid flags that silently alter multiple concerns.
- Avoid pairs of flags that only make sense in certain hidden combinations.
-
Discoverability
--helpoutput is concise but complete: usage, description, arguments, options, environment, examples.- Default values and accepted ranges or enumerations are documented.
- Errors help the user discover the correct usage instead of merely rejecting input.
-
Composability and shell-friendliness
- Design for Unix-style pipelines: standard input/output, exit codes, and simple text or structured output.
- Avoid implicit file I/O if explicit paths or
-oflags are possible. - Offer machine-friendly output formats where relevant (e.g. JSON) and document them.
-
Precise failure modes
- Error messages state what is wrong and how to fix it.
- Ambiguous or partial input is rejected with clear guidance.
- Exit codes are chosen deliberately (e.g.
0success,1user error,2internal failure).
Good and Bad Examples
Option Naming
Bad: Ambiguous or inconsistent names
(* Unclear what -f does without reading docs *)
let file = Arg.(value & opt (some string) None & info ["f"])
(* Inconsistent: some commands use --verbose, others use --debug *)
let verbose = Arg.(value & flag & info ["v"; "verbose"])
let debug = Arg.(value & flag & info ["d"; "debug"]) (* same thing? *)
Good: Clear, explicit names with consistent patterns
(* Self-documenting option name *)
let config_file =
Arg.(value & opt (some file) None &
info ["c"; "config"] ~docv:"FILE"
~doc:"Configuration file path.")
(* Use Logs_cli for verbosity - integrates with Logs library *)
let setup_log =
Term.(const Logs_fmt.setup $ Fmt_cli.style_renderer () $ Logs_cli.level ())
(* Provides -v, -v -v, --verbosity=debug, etc. *)
Subcommand Design
Bad: Flat command namespace with overlapping concerns
(* Explosion of top-level commands *)
let cmds = [
create_user_cmd; delete_user_cmd; list_users_cmd;
create_group_cmd; delete_group_cmd; list_groups_cmd;
create_role_cmd; delete_role_cmd; list_roles_cmd;
]
Good: Hierarchical grouping with consistent verbs
(* Grouped by resource, consistent verbs *)
let create_cmd = Cmd.v (Cmd.info "create") create_user_term
let delete_cmd = Cmd.v (Cmd.info "delete") delete_user_term
let list_cmd = Cmd.v (Cmd.info "list") list_users_term
let user_cmd =
let info = Cmd.info "user" ~doc:"Manage users" in
Cmd.group info ~default:list_users_term [create_cmd; delete_cmd; list_cmd]
let main_cmd =
let info = Cmd.info "mytool" ~version:"1.0" in
Cmd.group info [user_cmd; group_cmd; role_cmd]
Error Messages
Bad: Unhelpful error that doesn't guide the user
let validate_port p =
if p < 0 || p > 65535 then `Error (false, "invalid port")
else `Ok p
Good: Error explains what's wrong and how to fix it
let validate_port p =
if p < 0 || p > 65535 then
`Error (false, Printf.sprintf
"port %d is out of range (must be 0-65535)" p)
else `Ok p
Separating Parsing from Logic
Bad: Business logic mixed with cmdliner parsing
let run_term =
let open Term in
const (fun config_file ->
(* Business logic embedded in term *)
let config = read_config config_file in
let db = connect_db config in
run_server db)
$ config_file_arg
Good: Terms only parse; separate function does the work
(* Pure business logic function *)
let run ~config_file =
let config = read_config config_file in
let db = connect_db config in
run_server db
(* Term just wires up arguments *)
let run_term = Term.(const run $ config_file_arg)
Flag Orthogonality
Bad: Flags with hidden interactions
(* --json silently disables --color, user doesn't know *)
let output_format json color =
if json then Json else if color then Colored else Plain
Good: Orthogonal flags, explicit conflicts
(* Either format flag, not both *)
let output_format =
Arg.(value & vflag Plain [
Json, info ["json"] ~doc:"Output as JSON.";
Colored, info ["color"] ~doc:"Output with ANSI colors.";
])
Cmdliner-Specific Guidance
When writing or revising cmdliner code, follow these patterns:
- Use
Cmd.vwith aTerm.tandCmd.infofor each command or subcommand. - Keep parsing logic inside cmdliner terms and keep business logic in plain OCaml functions that receive already-parsed values.
- Use
Arg.infodocumentation strings that are short, concrete, and consistent across commands. - Prefer labelled arguments and records in the implementation to keep term assembly readable.
- Ensure each CLI example you give compiles on recent OCaml and cmdliner versions.
Typical Structure
When the user asks for a new CLI, aim to provide:
- A command tree sketch (top-level command, subcommands, options, arguments).
- Example
Cmd.tandTerm.tdefinitions. - Example
dunestanzas required to build the executable. - Example usage snippets showing common workflows.
Response Format
Unless the user requests otherwise, structure your responses as:
- Overview – brief description of the CLI design or change.
- Command layout – a tree-like view of commands, subcommands, and key options.
- Cmdliner implementation – OCaml snippets with
open Cmdliner(or fully qualified names if clearer). - Help and examples – sample
--helpoutput and real-world usage examples. - Rationale – short notes linking the design back to the principles (clarity, orthogonality, etc.).
Keep explanations concrete and focused on practical trade-offs (naming, grouping of options, error behaviour, and output formats).
CLI Output Design Guidelines
A good CLI is both useful and beautiful. Follow these guidelines for consistent, professional output.
Core Libraries
| Library | Purpose |
|---|---|
fmt | Styled terminal output (colors, bold, etc.) |
progress | Progress bars and spinners |
logs + logs-cli | Structured logging with verbosity levels |
notty | Full terminal UI (tables, boxes) - for complex tools |
Output Modes
Every CLI should support at least two output modes:
type output_format = Human | Json
let output_format =
let doc = "Output format: $(b,human) for terminal, $(b,json) for scripts." in
Arg.(value & opt (enum ["human", Human; "json", Json]) Human &
info ["o"; "output"] ~doc ~docv:"FORMAT")
Human mode: Colors, progress bars, tables, emoji status indicators JSON mode: Machine-parseable, no ANSI codes, newline-delimited for streaming
Color Scheme
Use consistent semantic colors across all tools:
(* Standard semantic styles *)
let success = Fmt.(styled `Green string) (* ✓ Success, OK *)
let error = Fmt.(styled `Red string) (* ✗ Error, Failed *)
let warning = Fmt.(styled `Yellow string) (* ⚠ Warning *)
let info = Fmt.(styled `Cyan string) (* ℹ Info, hints *)
let dimmed = Fmt.(styled `Faint string) (* Secondary info *)
let bold = Fmt.(styled `Bold string) (* Emphasis, headers *)
let code = Fmt.(styled `Cyan string) (* Code, paths, values *)
(* Status indicators with icons *)
let pp_status ppf = function
| `Ok -> Fmt.pf ppf "%a" Fmt.(styled `Green string) "✓"
| `Error -> Fmt.pf ppf "%a" Fmt.(styled `Red string) "✗"
| `Warning -> Fmt.pf ppf "%a" Fmt.(styled `Yellow string) "⚠"
| `Info -> Fmt.pf ppf "%a" Fmt.(styled `Cyan string) "ℹ"
| `Pending -> Fmt.pf ppf "%a" Fmt.(styled `Blue string) "○"
Progress Bars
Use the progress library for long-running operations:
open Progress
(* Simple progress bar *)
let with_progress ~total f =
let bar =
Line.(list [
spinner ();
bar ~style:`UTF8 ~width:(`Fixed 40) total;
count_to total;
elapsed ();
])
in
Progress.with_reporter bar f
(* Example usage *)
let process_files files =
let total = List.length files in
with_progress ~total (fun report ->
List.iteri (fun i file ->
process_file file;
report i
) files)
For indeterminate operations, use spinners:
let with_spinner ~message f =
let line = Line.(list [spinner (); const message]) in
Progress.with_reporter line (fun _report -> f ())
Tables
For tabular data, use aligned columns:
(* Simple table with Fmt *)
let pp_table ppf rows =
let widths = compute_column_widths rows in
List.iter (fun row ->
List.iteri (fun i cell ->
let width = List.nth widths i in
Fmt.pf ppf "%-*s " width cell
) row;
Fmt.pf ppf "@."
) rows
(* With header styling *)
let pp_table_with_header ppf ~headers rows =
(* Header row in bold *)
List.iter (fun h -> Fmt.pf ppf "%a " bold h) headers;
Fmt.pf ppf "@.";
(* Separator *)
List.iter (fun h -> Fmt.pf ppf "%s " (String.make (String.length h) '─')) headers;
Fmt.pf ppf "@.";
(* Data rows *)
List.iter (fun row ->
List.iter (fun cell -> Fmt.pf ppf "%s " cell) row;
Fmt.pf ppf "@."
) rows
Error Output
Errors should be clear, actionable, and visually distinct:
let pp_error ppf ~context ~message ~hint =
Fmt.pf ppf "@[<v>%a %a@,%a@,%a %a@]@."
Fmt.(styled `Red string) "error:"
Fmt.(styled `Bold string) message
dimmed (Printf.sprintf " in %s" context)
Fmt.(styled `Cyan string) "hint:"
Fmt.string hint
(* Example output:
error: Invalid port number '70000'
in --port argument
hint: Port must be between 0 and 65535
*)
Summary Output
For commands that process multiple items:
let pp_summary ppf ~processed ~succeeded ~failed ~skipped =
Fmt.pf ppf "@.%a@."
Fmt.(styled `Bold string) "Summary:";
Fmt.pf ppf " %a %d processed@."
(Fmt.styled `Cyan string) "•" processed;
if succeeded > 0 then
Fmt.pf ppf " %a %d succeeded@."
(Fmt.styled `Green string) "✓" succeeded;
if failed > 0 then
Fmt.pf ppf " %a %d failed@."
(Fmt.styled `Red string) "✗" failed;
if skipped > 0 then
Fmt.pf ppf " %a %d skipped@."
(Fmt.styled `Yellow string) "○" skipped
(* Example output:
Summary:
• 42 processed
✓ 40 succeeded
✗ 2 failed
*)
TTY Detection
Always check if stdout is a terminal before using colors/progress:
let setup_formatter () =
let style_renderer =
if Unix.isatty Unix.stdout then `Ansi_tty else `None
in
Fmt.set_style_renderer Fmt.stdout style_renderer
(* Or use Fmt_cli for cmdliner integration *)
let setup_term =
Term.(const Fmt_tty.setup_std_outputs $ Fmt_cli.style_renderer ())
Verbosity Levels
Integrate with Logs for consistent verbosity:
(* In main.ml *)
let setup_log style_renderer level =
Fmt_tty.setup_std_outputs ?style_renderer ();
Logs.set_level level;
Logs.set_reporter (Logs_fmt.reporter ())
let setup_log_term =
Term.(const setup_log $ Fmt_cli.style_renderer () $ Logs_cli.level ())
(* In code, use appropriate log levels *)
Logs.debug (fun m -> m "Processing file %s" path);
Logs.info (fun m -> m "Converted %d records" count);
Logs.warn (fun m -> m "Deprecated format, consider upgrading");
Logs.err (fun m -> m "Failed to parse: %s" reason);
Example: Complete CLI with Good Output
open Cmdliner
(* Styled output helpers *)
let success fmt = Fmt.pf Fmt.stdout ("%a " ^^ fmt ^^ "@.")
Fmt.(styled `Green string) "✓"
let error fmt = Fmt.pf Fmt.stderr ("%a " ^^ fmt ^^ "@.")
Fmt.(styled `Red string) "✗"
let info fmt = Fmt.pf Fmt.stdout ("%a " ^^ fmt ^^ "@.")
Fmt.(styled `Cyan string) "ℹ"
(* Command implementation *)
let convert ~input ~output ~format =
info "Converting %a to %s format"
Fmt.(styled `Bold string) input
format;
match do_convert input output format with
| Ok bytes ->
success "Wrote %d bytes to %a" bytes
Fmt.(styled `Cyan string) output;
`Ok ()
| Error msg ->
error "Conversion failed: %s" msg;
`Error (false, msg)
(* Term with proper setup *)
let term =
let open Term in
const convert
$ input_arg
$ output_arg
$ format_arg
let cmd =
let info = Cmd.info "convert"
~doc:"Convert between formats"
~man:[`S "EXAMPLES"; `P "$(iname) input.json -o output.cbor"]
in
Cmd.v info Term.(ret (const setup $ setup_log_term $ term))
Checklist for New CLIs
- Supports
--output=jsonfor machine-readable output - Uses semantic colors (green=success, red=error, etc.)
- Progress bars for operations > 1 second
- Clear error messages with hints
- Summary output for batch operations
- TTY detection (no colors when piped)
- Verbosity via
-v/--verbosity(Logs_cli) - Consistent with project conventions
OCaml Code Style
Core Philosophy
- Interface-First: Design
.mlifirst. Clean interface > clever implementation. - Modularity: Small, focused modules. Compose for larger systems.
- Simplicity (KISS): Clarity over conciseness. Avoid obscure constructs.
- Explicitness: Explicit control flow and error handling. No exceptions for recoverable errors.
- Purity: Prefer pure functions. Isolate side-effects at edges.
- NEVER use Obj.magic: Breaks type safety. Always a better solution.
Naming Conventions
| Element | Convention | Example |
|---|---|---|
| Files | lowercase_underscores | user_profile.ml |
| Modules | Snake_case | User_profile |
| Types | snake_case, primary type is t | type user_profile, type t |
| Values | snake_case | find_user, create_channel |
| Variants | Snake_case | Waiting_for_input, Processing_data |
Function naming:
find_*returnsoption(may not exist)get_*returns value directly (must exist)
Avoid: Long names with many underscores (get_user_profile_data_from_database_by_id).
Refactoring Patterns
Option/Result Combinators
(* Before *)
match get_value () with Some x -> Some (x + 1) | None -> None
(* After *)
Option.map (fun x -> x + 1) (get_value ())
Prefer: Option.map, Option.bind, Option.value, Result.map, Result.bind
Monadic Syntax (let*/let+)
(* Before - nested matches *)
match fetch_user id with
| Ok user -> (match fetch_perms user with Ok p -> Ok (user, p) | Error e -> Error e)
| Error e -> Error e
(* After *)
let open Result.Syntax in
let* user = fetch_user id in
let+ perms = fetch_perms user in
(user, perms)
Pattern Matching Over Conditionals
(* Before *)
if x > 0 then if x < 10 then "small" else "large" else "negative"
(* After *)
match x with
| x when x < 0 -> "negative"
| x when x < 10 -> "small"
| _ -> "large"
Function Design
Keep functions small: Under 50 lines. One purpose per function.
Avoid deep nesting: Max 4 levels of match/if. Extract helpers.
High complexity signal: Many branches = split into focused helpers.
(* Bad - high complexity *)
let check x y z =
if x > 0 then if y > 0 then if z > 0 then ... else ... else ... else ...
(* Good - factored *)
let all_positive x y z = x > 0 && y > 0 && z > 0
let check x y z = if not (all_positive x y z) then "invalid" else ...
Error Handling
Use result for recoverable errors. Exceptions only for programming errors.
Never catch-all:
(* Bad *)
try f () with _ -> default
(* Good *)
try f () with Failure _ -> default
Don't silence warnings: Fix the issue, don't use [@warning "-nn"].
Library Preferences
| Instead of | Use | Why |
|---|---|---|
Str | Re | Better API, no global state |
Printf | Fmt | Composable, type-safe |
yojson (manual) | jsont | Type-safe codecs |
Module Hygiene
Abstract types: Keep type t abstract. Expose smart constructors.
(* Good - .mli *)
type t
val create : name:string -> t
val name : t -> string
val pp : t Fmt.t
Avoid generic names: Not Util, Helpers. Use String_ext, Json_codec.
API Design
Avoid boolean blindness:
(* Bad *)
let create_widget visible bordered = ...
let w = create_widget true false (* What does this mean? *)
(* Good *)
type visibility = Visible | Hidden
let create_widget ~visibility ~border = ...
Comments and Documentation
Documentation is written in the voice of a POSIX manual page. Implementations
carry no comments where the code speaks for itself. Load the doc-style skill
before writing or rewording any comment. It is the full standard and the list
below is only its summary.
The short form:
- A function's doc opens
[f x y] is ..., on the line after theval. - Full sentences ending in a full stop. No fragments.
- No colons or em dashes joining clauses. Use separate sentences.
- Nothing about the implementation. Only what the caller can observe.
- No
This function,Note that,simply,helper for,internally. - Every optional argument states its default.
- Delete implementation comments that restate the code, section banners, and commented-out code.
- Documentation lives in the
.mli. An.mlwith an.mlicarries no(** ... *)comments.
(* Bad *)
(** Parses the string: splits on commas and builds the record — fast. *)
val parse : string -> t
(* Good *)
val parse : string -> t
(** [parse s] is the record encoded in [s]. Parsing is linear in the length of
[s]. *)
Red Flags
- Match that just rewraps:
Some v -> Some (f v) | None -> None - Nested Result/Option matches → use let*/let+
- Deep if/then/else → pattern matching
- Missing
ppfunction on types - Unlabeled boolean parameters
Obj.magicanywhere- Doc comments that describe the implementation rather than the behaviour
- Comments inside an implementation that restate the code
- A colon or em dash joining clauses in a doc comment
- An exported value with no doc comment
OCaml Comment and Documentation Style
Write ocamldoc the way a POSIX manual page is written. State what a thing is and what it does, in full sentences, and stop.
Implementations carry no comments at all unless the code cannot speak for itself.
This skill covers what to write. For odoc reference syntax, cross-package
links and build warnings, see the ocaml-docs skill.
The Six Rules
- Full sentences. Every doc comment is one or more complete sentences, each ending in a full stop. No fragments, no bullet-point shorthand, no trailing "...".
- Manpage voice. Terse, declarative, present tense, third person. No "we", no "you", no "this function", no enthusiasm.
- No extraneous detail. Document what a caller must know to call it. History, rationale, benchmarks, future plans and implementation trivia do not appear.
- No connectives. No colons and no em dashes joining clauses. Split into separate sentences instead. Semicolons only inside a genuine list.
- User-facing, not internal. Describe observable behaviour. Mention an internal only when the caller can observe it, such as time complexity, allocation behaviour, evaluation order or thread safety.
[f x y] is .... A function's documentation opens with the function applied to its arguments in brackets, followed byis.
Function Documentation
The doc comment follows the val declaration. Name the arguments in the
bracketed application and refer to them with [x] thereafter.
val length : t -> int
(** [length t] is the number of elements in [t]. *)
val find : string -> t -> element option
(** [find name t] is the element of [t] called [name], or [None] if [t] has
no such element. *)
val is_bot : t -> bool
(** [is_bot u] is [true] if [u] is a bot user. *)
Use is whenever the function has a meaningful result. Reserve an active verb
for functions that exist for their effect.
val flush : out_channel -> unit
(** [flush oc] writes the buffered bytes of [oc] to its underlying file. *)
val set : t -> key:string -> value:string -> unit
(** [set t ~key ~value] binds [key] to [value] in [t]. Any previous binding of
[key] is dropped. *)
Effectful constructors are still is.
val create : unit -> t
(** [create ()] is a new empty table. *)
val of_file : Fpath.t -> (t, Error.t) result
(** [of_file file] is the configuration parsed from [file]. The error holds a
human readable message suitable for a command line tool. *)
Document optional arguments in their own sentence, and give the default.
val sub : ?start:int -> ?len:int -> string -> string
(** [sub ~start ~len s] is the substring of [s] of length [len] starting at
[start]. [start] defaults to [0]. [len] defaults to the remainder of [s]
after [start]. *)
Failure conditions go last, as tags.
val get : t -> string -> element
(** [get t name] is the element of [t] called [name].
@raise Not_found if [t] has no element called [name]. *)
Prefer naming arguments in the bracketed application over @param tags.
@param restates the signature and reads nothing like a manual page.
Type and Value Documentation
A type is documented by what its values represent, not by its representation.
type t
(** The type for users. *)
type id = string
(** The type for user identifiers. An identifier is unique within a workspace
and stable across renames. *)
type level = Debug | Info | Warning | Error
(** The type for message severities, in increasing order of severity. *)
Constructors and record fields take a doc comment only when the name is not enough.
type t = {
name : string; (** The display name. It is not unique. *)
id : id;
created : Ptime.t; (** The creation time, in UTC. *)
}
Module Documentation
The first line of an .mli is a synopsis in the shape of a manpage NAME
line. A blank line follows, then the description.
(** User accounts and profiles.
Users are workspace members. A user is identified by an {!type:id} that is
stable for the lifetime of the account. Profile fields are populated
lazily and may be absent on users who have never signed in. *)
Keep the description to what a caller needs before reading the values below
it. Use {1 Section} headings once the interface is long enough to need them,
and name the sections after what they hold, such as {1 Users} or
{1 Predicates and comparisons}.
Rewrites
| Instead of | Write |
|---|---|
(** Returns the length of the buffer *) | (** [length b] is the number of bytes in [b]. *) |
(** [parse s] parses [s]: it splits on commas and builds a record. *) | (** [parse s] is the record encoded in [s]. *) |
(** [send t msg] sends a message — note this blocks. *) | (** [send t msg] sends [msg] on [t]. It blocks until [msg] has been written. *) |
(** This function is used internally by the scheduler to requeue fibers. *) | Delete it, or make the value private. |
(** Fast lookup (uses a hashtable). *) | (** [find t k] is the value bound to [k] in [t]. Lookup is constant time. *) |
(** TODO: document *) | Write the sentence. |
Banned Words and Shapes
Delete these on sight.
This function,This value,This moduleas an opener. Name the thing.Basically,simply,just,obviously,of course.Note that,Please note,Be aware. State the fact as a sentence.Internally,under the hood,behind the scenes.Helper for,Wrapper around,Convenience function.- A colon or em dash introducing an explanatory clause.
- A parenthetical that repeats the type signature.
- Author names, dates, ticket numbers and changelog entries.
Comments in Implementations
Default is no comment. If a reader who knows OCaml can see what the code does, the code says it already. Naming a value is better than commenting it.
Delete on sight:
- Comments that restate the code, such as
(* increment i *). - Section banners and boxes, such as
(* ---- Helpers ---- *). - Commented-out code. Version control keeps it.
- Narration of obvious control flow, such as
(* loop over the list *). - Attribution, dates and changelog entries.
- Doc comments in an
.mlthat has an.mli. The documentation belongs in the interface, and a second copy will drift.
Write a comment only for something the code cannot state:
- A citation for behaviour mandated elsewhere, such as
(* RFC 8259 §7. *). - An invariant a reader cannot check locally, such as
(* [buf] is never empty here, see [refill]. *). - A deliberate deviation or workaround, with the reason it exists.
- A justification for an unsafe or unusual operation.
- Why the obvious approach was rejected, when someone would otherwise reinstate it.
Kept comments are full sentences in (* ... *), placed on the line above the
code they explain.
(* Bad. *)
let decode s =
(* get the length *)
let n = String.length s in
(* loop over the characters *)
let b = Buffer.create n in
...
(* Good. *)
let decode s =
let b = Buffer.create (String.length s) in
...
(* Good. The comment states what the code cannot. *)
let decode s =
(* RFC 4648 §3.2 requires padding to be rejected in strict mode. *)
if strict && String.length s mod 4 <> 0 then invalid_arg "decode";
...
Checklist
Before committing documentation:
- Every exported value has a doc comment.
- Every function doc opens with
[f x y] isor an active verb for an effect. - Every argument named in the brackets is referred to in the prose.
- Every optional argument has its default stated.
- Every sentence is complete and ends in a full stop.
- No colons or em dashes join clauses.
- No sentence describes the implementation.
- No banned word from the list above survives.
- The
.mlhas no comment that the code already says. -
dune build @docis clean.
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 dependenciespkg/pkg.ml- topkg package descriptionpkg/META- findlib metadata*.mllibfiles - module lists for librariesopam- 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
- Rename
opamto<package>.opam - Remove ocamlbuild/topkg dependencies
- Add dune:
depends: [
"ocaml" {>= "4.14.0"}
"dune" {>= "3.0"}
]
- 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}
]
8. Documentation dune File
If there's a doc/ directory:
(documentation
(package <package-name>))
9. Remove ocamlbuild Files
Files to delete:
_tags.merlinpkg/pkg.mlpkg/META*.mllibfiles*.itargetfiles- The
pkg/directory
Mapping Reference
| ocamlbuild | dune |
|---|---|
_tags: package(foo) | (libraries foo) |
_tags: thread | (libraries threads) |
foo.mllib with Foo | (library (name foo) (modules foo)) |
pkg/pkg.ml: Pkg.mllib ~cond:x | (library ... (optional)) |
pkg/META | Auto-generated by dune |
opam | <package>.opam |
Common Issues
"Library not found" for optional deps
Use (optional) on the library stanza.
Unused variable warnings
Add (flags (:standard -w -27)).
Module in wrong library
Use (modules ...) to explicitly list modules.
Toplevel init files
Exclude from library with (modules ...) and use (install ...).
Verification
After migration:
dune build @check # Verify syntax
dune build # Build project
dune runtest # Run tests
dune build @doc # Build docs
OCaml 5 Effects Design
Core Principle
Effects for control flow, exceptions for errors.
| Concern | Mechanism | Example |
|---|---|---|
| Suspension (wait for data) | Effects | perform Block, perform Yield |
| Error (EOF, malformed) | Exceptions | raise End_of_file, Invalid_argument |
Layered Design
Effects should be handled at the source level, not in protocol parsers:
Application
↓
Protocol parser (Binary.Reader, Cbor, etc.)
↓ raises exceptions on EOF/error
bytesrw (effect-agnostic)
↓ just calls pull function
Source (Eio flow, affect fd, Unix fd)
↓ performs effects for suspension
Effect handler (Eio scheduler, affect runtime)
Why This Matters
- Parsers stay pure: No effect dependencies, easy to test
- Sources control blocking: Handler decides wait vs fail vs timeout
- Composability: Same parser works with any effect system
Effect Libraries
Eio
Effects are internal to the scheduler. User code looks synchronous:
(* Reading blocks via internal effects *)
let data = Eio.Flow.read flow buf
affect
Explicit effects for fiber scheduling:
type _ Effect.t +=
| Block : 'a block -> 'a Effect.t (* suspension *)
| Await : await -> unit Effect.t (* wait on fibers *)
| Yield : unit Effect.t (* cooperative yield *)
(* Block has callbacks for scheduler integration *)
type 'a block = {
block : handle -> unit; (* register blocked fiber *)
cancel : handle -> bool; (* handle cancellation *)
return : handle -> 'a (* extract result *)
}
bytesrw
Effect-agnostic streaming. The pull function you provide can perform any effects:
(* bytesrw just calls your function *)
let reader = Bytesrw.Bytes.Reader.make my_pull_fn
(* If my_pull_fn performs Eio effects, they propagate *)
(* If my_pull_fn performs affect Block, they propagate *)
(* bytesrw doesn't care - it just calls the function *)
Integration Pattern
Wire effect-performing sources to effect-agnostic libraries:
(* With Eio *)
let reader = Bytesrw_eio.bytes_reader_of_flow flow in
let r = Binary.Reader.of_reader reader in
parse r (* Eio effects happen in pull function *)
(* With affect *)
let pull () =
let buf = Bytes.create 4096 in
perform (Block { block; cancel; return = fun _ ->
Slice.make buf ~first:0 ~length:n })
in
let reader = Bytesrw.Bytes.Reader.make pull in
parse (Binary.Reader.of_reader reader)
When EOF Is Reached
Slice.eod from bytesrw means final EOF - no more data will ever come.
- Not "data not ready" (that's handled by effects in pull function)
- Not "try again later" (source already waited via effects)
- Parser should raise exception (EOF is an error condition)
Anti-Patterns
Don't: Define Await effect in protocol parsers
(* WRONG - parser shouldn't know about suspension *)
let get_byte t =
if no_data then perform Await; ...
Do: Let the source handle suspension
(* RIGHT - parser just reads, source handles waiting *)
let get_byte t =
match pull_next_slice t with (* may perform effects *)
| Some slice -> ...
| None -> raise End_of_file (* true EOF *)
References
- Eio: https://github.com/ocaml-multicore/eio
- affect: https://github.com/dbuenzli/affect
- bytesrw: https://erratique.ch/software/bytesrw
- OCaml effects tutorial: https://github.com/ocaml-multicore/ocaml-effects-tutorial
- Retrofitting Effect Handlers onto OCaml (PLDI 2021): https://dl.acm.org/doi/10.1145/3453483.3454039
- Collège de France 2023-2024 lectures on control structures: https://xavierleroy.org/CdF/2023-2024/
Eio Concurrency
Core Concepts
Why Eio
Eio is an effects-based IO library for OCaml 5. Advantages over Lwt/Async:
- Direct-style code: No monads, concurrent code looks like sequential code
- Performance: Real stacks, no heap allocations to simulate continuations
- Better backtraces: Exceptions show proper call traces
- Platform optimization: Generic API with optimized backends (Linux io_uring, POSIX, Windows)
Capability-Based Design
Pass capabilities explicitly instead of using global resources:
type t = {
net : _ Eio.Net.t;
clock : _ Eio.Time.clock;
fs : _ Eio.Path.t;
}
(* Function signature reveals what resources it needs *)
val connect : net:_ Eio.Net.t -> host:string -> connection
Do: Pass net, clock, fs explicitly—makes dependencies clear and testable.
Don't: Use global modules like Unix.gettimeofday or access ambient resources.
Structured Concurrency with Switches
Eio.Switch.run manages resource and fiber lifecycles:
Eio.Switch.run @@ fun sw ->
let conn = connect ~sw server in
(* conn automatically closed when sw exits *)
process conn
Do: Create switches in the smallest possible scope.
Don't: Take a switch argument if you could create one internally.
Fibers
Lightweight concurrent units running on a single core:
(* Run two operations concurrently *)
Eio.Fiber.both
(fun () -> download file1)
(fun () -> download file2)
(* Only one fiber executes at a time until one performs an effect *)
Cancellation
Cancellation contexts form a tree. Uncaught exceptions propagate upward, cancelling siblings:
(* If one branch fails, the other gets Cancelled *)
Eio.Fiber.both
(fun () -> may_fail ())
(fun () -> other_work ()) (* receives Cancelled if may_fail raises *)
Use Cancel.protect for operations that must complete:
Eio.Cancel.protect @@ fun () ->
(* This won't be cancelled even if parent is *)
flush_and_close connection
Common Patterns
Concurrent Operations
(* Parallel map *)
let fetch_all_items api item_ids =
Eio.Fiber.List.map (fun id -> Api.item_info api id) item_ids
(* Race with timeout *)
let with_timeout ~clock duration fn =
Eio.Fiber.first
(fun () -> Eio.Time.sleep clock duration; Error `Timeout)
(fun () -> Ok (fn ()))
(* Fork background task attached to switch *)
Eio.Fiber.fork ~sw (fun () -> background_work ())
File Operations
let ( / ) = Eio.Path.( / )
(* Read file *)
let content = Eio.Path.load (fs / "config.json")
(* Write file with permissions *)
Eio.Path.save ~create:(`Or_truncate 0o600) (fs / "data.bin") content
(* Create directory if needed *)
Eio.Path.mkdirs ~exists_ok:true ~perm:0o755 (fs / "cache")
(* Clean up directory tree *)
Eio.Path.rmtree (fs / "tmp")
(* Check file type *)
match Eio.Path.kind ~follow:true path with
| `Directory -> ...
| `Regular_file -> ...
| `Not_found -> ...
Network Operations
(* TCP client *)
Eio.Net.connect ~sw net (`Tcp (addr, port))
(* TCP server *)
Eio.Net.run_server sock ~on_error:log_error
~max_connections:100
(fun ~sw flow addr -> handle_client ~sw flow)
HTTPS with cohttp-eio
let https_handler uri raw_flow =
let tls_config = create_tls_config () in
let host = Uri.host uri |> Option.map Domain_name.(host_exn % of_string_exn) in
Tls_eio.client_of_flow ?host tls_config raw_flow
let client = Cohttp_eio.Client.make net ~https:(Some https_handler)
Buffered Reading
Always use max_size to prevent memory exhaustion:
let body = Eio.Buf_read.(of_flow ~max_size:10_000_000 flow |> take_all)
Synchronization Primitives
Mutex:
let mutex = Eio.Mutex.create ()
Eio.Mutex.use_rw mutex (fun () -> shared_state := new_value)
Semaphore for rate limiting:
let limiter = Eio.Semaphore.make 10
let with_rate_limit fn =
Eio.Semaphore.acquire limiter;
Fun.protect ~finally:(fun () -> Eio.Semaphore.release limiter) fn
Stream for producer/consumer:
let queue = Eio.Stream.create 100
Eio.Stream.add queue item (* producer *)
let item = Eio.Stream.take queue (* consumer, blocks if empty *)
Condition variables (must check in loop):
let cond = Eio.Condition.create ()
let mutex = Eio.Mutex.create ()
(* Waiter - MUST use while loop *)
Eio.Mutex.use_rw ~protect:false mutex (fun () ->
while not (check_condition ()) do
Eio.Condition.await cond mutex
done)
(* Signaler *)
Eio.Condition.broadcast cond
Integration with bytesrw
Bridge Eio flows to bytesrw for streaming binary parsing:
(* Eio flow → bytesrw reader *)
let reader_of_flow ?(buf_len = 4096) flow =
let cs = Cstruct.create buf_len in
let read () =
match Eio.Flow.single_read flow cs with
| 0 -> Bytesrw.Bytes.Slice.eod
| n ->
let buf = Cstruct.to_bytes (Cstruct.sub cs 0 n) in
Bytesrw.Bytes.Slice.make buf ~first:0 ~length:n
| exception End_of_file -> Bytesrw.Bytes.Slice.eod
in
Bytesrw.Bytes.Reader.make read
(* Then use with Binary.Reader *)
let r = Binary.Reader.of_reader (reader_of_flow flow)
let frame = Tc_frame.parse r (* effects propagate through *)
Note: This involves a copy from Cstruct (Bigarray) to bytes (heap). Unavoidable until OCaml has non-moving bytes.
RNG Initialization
Critical for crypto: Initialize RNG before any crypto operations.
(* For Eio applications *)
Eio_main.run @@ fun env ->
Mirage_crypto_rng_eio.run (module Mirage_crypto_rng.Fortuna) env @@ fun () ->
(* RNG now available *)
let iv = Mirage_crypto_rng.generate 12 in
...
(* For Unix applications (simpler but less integrated) *)
Mirage_crypto_rng_unix.initialize (module Mirage_crypto_rng.Fortuna)
Failure to initialize results in predictable random numbers, breaking crypto security.
Error Handling
Errors use Eio.Io (err, context) with nested error codes:
try
Eio.Net.connect ~sw net addr
with
| Eio.Io (Eio.Net.E (Connection_failure _), _) ->
(* Specific error *)
Error `Connection_failed
| Eio.Io (Eio.Net.E _, _) ->
(* Any network error *)
Error `Network_error
| Eio.Io _ ->
(* Any Eio error *)
Error `Io_error
Add context when re-raising:
Eio.Exn.reraise_with_context exn "while connecting to %s" host
For tests, hide backend details:
Eio.Exn.Backend.show := false
Testing with Eio_mock
Library: eio.mock (not eio_mock)
Test Setup Pattern
let setup_test f () =
Mirage_crypto_rng_unix.use_default (); (* or initialize RNG *)
Eio_main.run @@ fun env ->
Eio.Switch.run @@ fun sw ->
let fs = Eio.Stdenv.fs env in
let tmp = Eio.Path.(fs / Filename.get_temp_dir_name () / "test-dir") in
(try Eio.Path.rmtree tmp with _ -> ());
Eio.Path.mkdirs ~exists_ok:true ~perm:0o755 tmp;
Fun.protect
~finally:(fun () -> try Eio.Path.rmtree tmp with _ -> ())
(fun () -> f ~sw tmp)
let test_something = setup_test @@ fun ~sw tmp ->
(* test code here *)
Mock Flow
let test_api_call () =
Eio_main.run @@ fun _env ->
let flow = Eio_mock.Flow.make "response" in
(* IMPORTANT: Always end with `Raise End_of_file *)
Eio_mock.Flow.on_read flow [
`Return "{\"ok\": true}";
`Raise End_of_file;
];
(* use flow *)
Simulating Chunked Data
let test_partial_reads () =
Eio_main.run @@ fun _env ->
let flow = Eio_mock.Flow.make "chunked" in
Eio_mock.Flow.on_read flow [
`Return "\x00\x01"; (* First 2 bytes *)
`Return "\x02\x03"; (* Next 2 bytes *)
`Raise End_of_file;
];
(* Parser must handle values spanning chunks *)
Mock Network
let test_network () =
Eio_main.run @@ fun _env ->
let net = Eio_mock.Net.make "mocknet" in
let flow = Eio_mock.Flow.make "conn" in
Eio_mock.Net.on_connect net [`Return flow];
Eio_mock.Flow.on_read flow [`Return "data"; `Raise End_of_file];
(* test network operations *)
Deadlock Detection
Eio_mock.Backend.run automatically detects deadlocks in tests.
Good and Bad Examples
Capability Passing
Bad: Using global/ambient resources
let fetch_data url =
let now = Unix.gettimeofday () in (* Global! *)
let body = Http.get url in (* Where does network come from? *)
{ timestamp = now; data = body }
Good: Explicit capability parameters
let fetch_data ~net ~clock url =
let now = Eio.Time.now clock in
Eio.Switch.run @@ fun sw ->
let body = Http.get ~sw net url in
{ timestamp = now; data = body }
Switch Scope
Bad: Taking switch as argument when not needed
(* Why does this need a switch? Caller must manage lifetime *)
let read_config ~sw ~fs path =
Eio.Path.load (fs / path) (* No resources to manage! *)
Good: Create switch internally when needed
(* No switch needed - just reads a file *)
let read_config ~fs path =
Eio.Path.load (fs / path)
(* Switch needed - manages connection lifetime *)
let with_connection ~sw ~net addr f =
let conn = Eio.Net.connect ~sw net addr in
f conn (* conn closed when sw exits *)
Buffered Reading
Bad: No size limit allows memory exhaustion
let read_body flow =
Eio.Buf_read.(of_flow flow |> take_all) (* Unbounded! *)
Good: Always specify max_size
let read_body flow =
Eio.Buf_read.(of_flow ~max_size:10_000_000 flow |> take_all)
Condition Variables
Bad: Single check can miss wakeups
Eio.Mutex.use_rw ~protect:false mutex (fun () ->
if not (check_condition ()) then (* Single if! *)
Eio.Condition.await cond mutex;
do_work ())
Good: Loop until condition is true
Eio.Mutex.use_rw ~protect:false mutex (fun () ->
while not (check_condition ()) do (* Loop handles spurious wakeups *)
Eio.Condition.await cond mutex
done;
do_work ())
Error Handling
Bad: Catching all Eio errors indiscriminately
let connect addr =
try Eio.Net.connect ~sw net addr
with Eio.Io _ -> failwith "connection failed" (* Loses context! *)
Good: Match specific errors, preserve context
let connect addr =
try Eio.Net.connect ~sw net addr
with
| Eio.Io (Eio.Net.E (Connection_failure reason), _) ->
Error (`Connection_failed reason)
| Eio.Io (Eio.Net.E Connection_refused, _) ->
Error `Refused
| Eio.Io _ as exn ->
Eio.Exn.reraise_with_context exn "connecting to %s" addr
Mock Testing
Bad: Mock flow without End_of_file hangs forever
let test_read () =
Eio_main.run @@ fun _env ->
let flow = Eio_mock.Flow.make "test" in
Eio_mock.Flow.on_read flow [
`Return "data";
(* Missing End_of_file! Test hangs *)
];
read_all flow
Good: Always end mock reads with End_of_file
let test_read () =
Eio_main.run @@ fun _env ->
let flow = Eio_mock.Flow.make "test" in
Eio_mock.Flow.on_read flow [
`Return "data";
`Raise End_of_file; (* Required! *)
];
read_all flow
Cancellation Safety
Bad: Critical cleanup can be cancelled
Eio.Fiber.both
(fun () -> may_fail ())
(fun () ->
do_work ();
flush_and_close connection) (* May be cancelled mid-flush! *)
Good: Protect critical operations
Eio.Fiber.both
(fun () -> may_fail ())
(fun () ->
do_work ();
Eio.Cancel.protect @@ fun () ->
flush_and_close connection) (* Completes even if cancelled *)
Common Gotchas
| Issue | Problem | Solution |
|---|---|---|
| Racing reads | Both reads may complete at kernel level | Don't rely on Fiber.first for mutual exclusion |
| Signal handlers | Most operations risk deadlock | Only Eio.Condition.broadcast is safe |
| Condition spurious wakeup | May wake without signal | Always check condition in while loop |
| Mutex in signal handler | Re-entrancy issues | Use conditions instead |
| Forgetting End_of_file | Mock flow hangs | Always end mock reads with Raise End_of_file |
| Missing RNG init | Predictable crypto | Initialize before any crypto operations |
Library Integration
| Library | Purpose | Notes |
|---|---|---|
| Lwt_eio | Run Lwt + Eio together | Gradual migration path |
| Async_eio | Run Async + Eio together | Experimental |
| bytesrw | Streaming byte parsing | Requires copy (Cstruct→bytes) |
| cohttp-eio | HTTP client/server | Native Eio support |
| tls-eio | TLS connections | Use with cohttp-eio for HTTPS |
| mirage-crypto-rng | Crypto RNG | Use .unix sublibrary for entropy |
Best Practices
| Practice | Description |
|---|---|
| Capability passing | Pass net, clock, fs explicitly |
| Structured concurrency | Use Switch.run, keep scopes small |
| Handle errors at boundaries | Convert Eio.Io to domain errors |
| Buffered reading | Use Buf_read with max_size |
| Parallel with fibers | Fiber.List.map, Fiber.both, Fiber.first |
| Isolate blocking | Eio_unix.run_in_systhread for non-Eio blocking |
| Test with mocks | Eio_mock for deterministic tests |
| Initialize RNG | Before any crypto operations |
References
- Eio repository: https://github.com/ocaml-multicore/eio
- Eio documentation: https://ocaml.org/p/eio/latest/doc/
- cohttp-eio: https://github.com/mirage/ocaml-cohttp
- bytesrw: https://erratique.ch/software/bytesrw
OCaml Fuzz Testing with Crowbar
Core Philosophy
- One fuzz file per module:
fuzz_foo.mltestslib/foo.ml. Keeps tests organized and discoverable. - Roundtrip everything: If you have
encodeanddecode, testdecode(encode(x)) = x. - Crash-safety first: Parsers must never crash on arbitrary input, even malformed data.
- Boundary conditions matter: Test edge cases (0, max values, empty input, overflow).
- State machines need transition coverage: Test all valid and invalid state transitions.
Build Configuration
Simple single-file setup (per-package)
For standalone packages, use one fuzz file per package:
ocaml-foo/
├── lib/
├── fuzz/
│ ├── dune
│ └── fuzz_foo.ml
└── dune-project
fuzz/dune:
(executable
(name fuzz_foo)
(modules fuzz_foo)
(libraries foo crowbar))
; Quick check with Crowbar (no AFL instrumentation)
(rule
(alias fuzz)
(deps fuzz_foo.exe)
(action
(run %{exe:fuzz_foo.exe})))
; AFL-instrumented build target (use with --profile=afl)
(rule
(alias fuzz-afl)
(deps
(source_tree input)
fuzz_foo.exe)
(action
(echo "AFL fuzzer built: %{exe:fuzz_foo.exe}\n")))
Seed corpus: Create fuzz/input/ with sample inputs:
mkdir -p fuzz/input
echo -n "" > fuzz/input/empty
# Add representative samples as seed inputs
fuzz/fuzz_foo.ml:
open Crowbar
let test_parse_crash_safety buf =
ignore (Foo.parse buf);
check true
let () =
add_test ~name:"foo: parse crash safety" [ bytes ] test_parse_crash_safety
Multi-module setup (large codebases)
For larger projects with many modules:
(executable
(name fuzz)
(libraries crowbar borealis)
(modules
fuzz
fuzz_common
fuzz_foo
fuzz_bar))
Main entry point (fuzz/fuzz.ml):
(* Force linking of modules that register tests via side effects *)
let () =
Fuzz_common.run ();
Fuzz_foo.run ();
Fuzz_bar.run ()
Each fuzz module ends with:
let run () = ()
This ensures the module is linked and its add_test calls execute.
Style Guidelines
When writing fuzz tests, follow these conventions:
- Define test functions separately at the top of the file
- Register all tests at the end with grouped
add_testcalls - Use
bytesdirectly instead of custom generators - Use a
truncatehelper to limit input size for protocol messages - Return
()directly - no need forcheck truein most cases - Add
Crypto_rng_unix.use_default ()at the top if crypto is used
Example structure
(** Fuzz tests for Foo module. *)
open Crowbar
open Fuzz_common
(** Decode - must not crash on arbitrary input. *)
let test_decode buf =
let buf = truncate buf in
let _ = Foo.decode (to_bytes buf) in
()
(** Roundtrip - valid values must round-trip. *)
let test_roundtrip buf =
let buf = truncate buf in
match Foo.decode (to_bytes buf) with
| Error _ -> ()
| Ok v ->
let encoded = Foo.encode v in
match Foo.decode encoded with
| Error _ -> fail "re-decode failed"
| Ok v' -> if v <> v' then fail "roundtrip mismatch"
(** Pretty-print - must not crash. *)
let test_pp n =
let v = Foo.of_int (n mod 4) in
let _ = Format.asprintf "%a" Foo.pp v in
()
(* All add_test calls in run function - no side effects at module init *)
let run () =
add_test ~name:"foo: decode crash safety" [ bytes ] test_decode;
add_test ~name:"foo: roundtrip" [ bytes ] test_roundtrip;
add_test ~name:"foo: pp" [ uint8 ] test_pp
Main entry point (fuzz/fuzz.ml):
(* Initialize crypto RNG if needed by any module *)
let () = Crypto_rng_unix.use_default ()
(* Register all fuzz tests *)
let () =
Fuzz_common.run ();
Fuzz_foo.run ();
Fuzz_bar.run ()
Test Patterns
1. Crash-safety test (parsers must not crash)
open Crowbar
open Fuzz_common
(** Decode - must not crash on arbitrary input. *)
let test_decode buf =
let buf = truncate buf in
let _ = Foo.decode (to_bytes buf) in
()
(** Decode with exceptions - must not crash. *)
let test_decode_exn buf =
let buf = truncate buf in
(try ignore (Foo.decode_exn (to_bytes buf)) with _ -> ());
()
let run () =
add_test ~name:"foo: decode crash safety" [ bytes ] test_decode;
add_test ~name:"foo: decode_exn crash safety" [ bytes ] test_decode_exn
Key points:
- Use
bytesgenerator for arbitrary binary input (producesstringtype) - Use
ignoreto discard results without warnings - Use
| exception _ -> ()to catch any exceptions check truesignals test passed
2. Roundtrip test (encode/decode pairs)
(** Roundtrip - valid values must round-trip. *)
let test_roundtrip buf =
let buf = truncate buf in
match Foo.decode (to_bytes buf) with
| Error _ -> () (* Invalid input is fine *)
| Ok original ->
let encoded = Foo.encode original in
match Foo.decode encoded with
| Error _ -> fail "re-decode failed"
| Ok decoded ->
if original <> decoded then fail "roundtrip mismatch"
let run () =
add_test ~name:"foo: roundtrip" [ bytes ] test_roundtrip
Key points:
- If initial decode fails, that's OK (input was invalid)
- If re-decode fails after encode, that's a bug
- Compare original and decoded values
3. Constrained type roundtrip (smart constructors)
(** APID roundtrip - valid values must round-trip. *)
let test_apid_roundtrip n =
match Apid.of_int n with
| None -> if n >= 0 && n <= 2047 then fail "should accept valid value"
| Some apid ->
let n' = Apid.to_int apid in
if n <> n' then fail "roundtrip mismatch"
let run () =
add_test ~name:"apid: roundtrip" [ range 2048 ] test_apid_roundtrip
4. Boundary tests
(** Max valid value. *)
let test_max_valid () =
match Apid.of_int 2047 with
| None -> fail "2047 should be valid"
| Some apid -> if Apid.to_int apid <> 2047 then fail "value mismatch"
(** Min valid value. *)
let test_min_valid () =
match Apid.of_int 0 with
| None -> fail "0 should be valid"
| Some apid -> if Apid.to_int apid <> 0 then fail "value mismatch"
let run () =
add_test ~name:"apid: max_valid" [ const () ] test_max_valid;
add_test ~name:"apid: min_valid" [ const () ] test_min_valid
Key points:
- Use
[ const () ]for tests with no random input - Never use
[]as generator list (causes type error)
5. Invalid input rejection
(** Values above max must be rejected. *)
let test_invalid_above n =
let invalid = 2048 + n in
match Apid.of_int invalid with
| None -> ()
| Some _ -> fail "should reject values > 2047"
(** Negative values must be rejected. *)
let test_invalid_negative n =
let invalid = -(n + 1) in
match Apid.of_int invalid with
| None -> ()
| Some _ -> fail "should reject negative values"
let run () =
add_test ~name:"apid: invalid_above" [ range 1000 ] test_invalid_above;
add_test ~name:"apid: invalid_negative" [ range 1000 ] test_invalid_negative
6. Pretty-printer safety
(** Pretty-print - must not crash. *)
let test_pp buf =
let buf = truncate buf in
match Foo.decode (to_bytes buf) with
| Error _ -> ()
| Ok v -> let _ = Format.asprintf "%a" Foo.pp v in ()
let run () =
add_test ~name:"foo: pp" [ bytes ] test_pp
7. State machine transitions
(** Test valid state transitions. *)
let test_activate_pending kid algo material_buf =
let material = to_bytes material_buf in
if Bytes.length material = 0 then ()
else
let key = Key.v ~kid ~algorithm:algo ~material in
match Key.activate key with
| Error _ -> () (* May fail if material invalid *)
| Ok active_key ->
if Key.state active_key <> Key.Active then fail "wrong state"
(** Test invalid state transitions return errors. *)
let test_activate_empty_fails kid algo =
let key = Key.empty ~kid ~algorithm:algo in
match Key.activate key with
| Ok _ -> fail "should fail on Empty key"
| Error (Key.Invalid_state_transition _) -> ()
| Error _ -> fail "wrong error type"
let run () =
add_test ~name:"key: activate Pending" [ uint8; uint8; bytes ]
test_activate_pending;
add_test ~name:"key: activate Empty fails" [ uint8; uint8 ]
test_activate_empty_fails
8. Unit conversion roundtrips
(** Nanoseconds roundtrip. *)
let test_ns_roundtrip n =
let d = Duration.of_ns n in
let n' = Duration.to_ns d in
if n <> n' then fail "ns roundtrip mismatch"
(** Microseconds to milliseconds conversion. *)
let test_us_to_ms n =
let us = Int64.of_int n in
let d = Duration.of_us us in
let ms = Duration.to_ms d in
let expected = Int64.div us 1000L in
if ms <> expected then fail "us to ms conversion failed"
let run () =
add_test ~name:"duration: ns_roundtrip" [ int64 ] test_ns_roundtrip;
add_test ~name:"duration: us_to_ms" [ range 1000000 ] test_us_to_ms
9. Filestore/resource operations
(** Test create/exists invariant. *)
let test_create_exists name_buf =
let name = Bytes.to_string (to_bytes name_buf) in
if String.length name = 0 then ()
else
let fs = Filestore.in_memory () in
match Filestore.create fs name with
| Error _ -> ()
| Ok () ->
if not (Filestore.exists fs name) then
fail "created file should exist"
let run () =
add_test ~name:"filestore: create_exists" [ bytes ] test_create_exists
Common Module: fuzz_common.ml
(** Common utilities for fuzz tests. *)
open Crowbar
let to_bytes buf =
let len = String.length buf in
let b = Bytes.create len in
Bytes.blit_string buf 0 b 0 len;
b
let catch_invalid_arg f =
try f () with Invalid_argument _ -> check true
let run () = ()
Generators Reference
| Generator | Type | Use for |
|---|---|---|
bytes | string | Arbitrary binary data |
uint8 | int | 0-255 |
int8 | int | -128 to 127 |
int32 | int32 | Full int32 range |
int64 | int64 | Full int64 range |
range n | int | 0 to n-1 |
bool | bool | true/false |
const v | 'a | Fixed value (for no-input tests) |
list gen | 'a list | Lists of generated values |
option gen | 'a option | Some/None |
File Organization
fuzz/
├── fuzz.ml # Main entry, links all modules
├── fuzz_common.ml # Shared utilities
├── fuzz_tc_frame.ml # Tests for lib/frames/tc_frame.ml
├── fuzz_tm_frame.ml # Tests for lib/frames/tm_frame.ml
├── fuzz_apid.ml # Tests for lib/frames/apid.ml
├── fuzz_keyid.ml # Tests for lib/sdls/keyid.ml
└── ...
Naming convention: fuzz_<module>.ml tests lib/**/<module>.ml
Running Fuzz Tests
Without AFL (quick check)
dune exec fuzz/fuzz.exe
# Or use the alias:
dune build @fuzz
With AFL (thorough fuzzing) - Manual
dune build fuzz/fuzz.exe
mkdir -p fuzz/input
echo -n "" > fuzz/input/empty
afl-fuzz -m none -i fuzz/input -o _fuzz -- \
_build/default/fuzz/fuzz.exe @@
With crow (recommended for multiple targets)
Use crow to orchestrate long-running AFL campaigns across multiple targets:
# Initialize workspace (creates dune-workspace with afl profile if needed)
crow init
# Build all fuzz targets with AFL instrumentation
dune build --profile=afl @fuzz-afl
# List discovered fuzz targets
crow list
# Start a campaign with 8 CPUs for 24 hours
crow start --cpus=8 --duration=24h
# Monitor progress
crow status
# Stop the campaign
crow stop
crow automatically:
- Discovers all
*/fuzz/dunefiles with crowbar dependencies - Allocates CPU cores across targets (main + secondary instances)
- Creates/updates
dune-workspacewith AFL profile if missing - Tracks campaign state and aggregates statistics
Check for duplicate test names
grep -h 'add_test ~name:"' fuzz/fuzz_*.ml | \
sed 's/.*~name:"\([^"]*\)".*/\1/' | sort | uniq -d
Coverage Checklist
For each module with a public API (.mli file):
- Crash safety: All
decode_*,parse_*,read_*,of_*functions - Roundtrip: All
encode/decode,to_*/of_*pairs - Boundaries: Min/max valid values, edge cases
- Invalid input: Values outside valid range rejected
- State machines: All transitions (valid and invalid)
- Pretty-printers: All
pp_*functions don't crash - Comparison:
equalandcompareare consistent
Priority Order
When adding fuzz tests to a codebase:
- Security-critical: Crypto primitives, authentication, key management
- Protocol parsers: Wire format decoders, frame parsers
- State machines: Lifecycle transitions, session state
- Constrained types: Smart constructors, ID validators
- Utility functions: Encoding helpers, time conversions
Common Mistakes
Wrong: Empty generator list with function
(* ERROR: This expression should not be a function *)
add_test ~name:"test" [] @@ fun () -> ...
Right: Use const () for no-input tests
add_test ~name:"test" [ const () ] @@ fun () -> ...
Wrong: Ignoring error cases
(* BAD: Only tests happy path *)
add_test ~name:"foo: decode" [ bytes ] @@ fun buf ->
let Ok v = Foo.decode (to_bytes buf) in
check true
Right: Handle both Ok and Error
add_test ~name:"foo: decode" [ bytes ] @@ fun buf ->
(match Foo.decode (to_bytes buf) with
| Ok _ -> ()
| Error _ -> ());
check true
Wrong: Asserting on invalid input
(* BAD: Fails on invalid input *)
add_test ~name:"foo: roundtrip" [ bytes ] @@ fun buf ->
match Foo.decode (to_bytes buf) with
| Error _ -> fail "decode failed" (* Wrong! Invalid input is expected *)
| Ok v -> ...
Right: Accept invalid input gracefully
add_test ~name:"foo: roundtrip" [ bytes ] @@ fun buf ->
match Foo.decode (to_bytes buf) with
| Error _ -> check true (* Invalid input is fine *)
| Ok v -> ...
Expected Outputs
When adding fuzz tests, produce:
- New fuzz file:
fuzz/fuzz_<module>.mlwith comprehensive tests - Update fuzz.ml: Add
Fuzz_<module>.run ()call - Verify build:
dune buildsucceeds - No duplicates: Test names are unique across all fuzz files
- Coverage summary: List of tests added and what they cover
Jsont JSON Encoding/Decoding
Dependencies
(libraries jsont jsont.bytesrw)
Core Patterns
Simple Object Codec
Map a JSON object to an OCaml record using Jsont.Object.map with mem for required fields:
type header = {
message_id : string;
method_ : string;
timestamp : int;
}
let header_codec =
Jsont.Object.map ~kind:"header"
(fun message_id method_ timestamp -> { message_id; method_; timestamp })
|> Jsont.Object.mem "messageId" Jsont.string ~enc:(fun h -> h.message_id)
|> Jsont.Object.mem "method" Jsont.string ~enc:(fun h -> h.method_)
|> Jsont.Object.mem "timestamp" Jsont.int ~enc:(fun h -> h.timestamp)
|> Jsont.Object.finish
Optional Fields
Use opt_mem for optional JSON fields. The constructor receives 'a option:
type config = {
name : string;
timeout : int; (* default if missing *)
}
let config_codec =
Jsont.Object.map ~kind:"config"
(fun name timeout_opt ->
{ name; timeout = Option.value ~default:30 timeout_opt })
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun c -> c.name)
|> Jsont.Object.opt_mem "timeout" Jsont.int ~enc:(fun c -> Some c.timeout)
|> Jsont.Object.finish
Skip Unknown Fields
Use skip_unknown before finish to ignore extra JSON fields (tolerant parsing):
let tolerant_codec =
Jsont.Object.map ~kind:"data" (fun id -> { id })
|> Jsont.Object.mem "id" Jsont.string ~enc:(fun d -> d.id)
|> Jsont.Object.skip_unknown (* ignore extra fields *)
|> Jsont.Object.finish
Nested Objects
Compose codecs for nested structures:
type request = { header : header; payload : payload }
let request_codec payload_codec =
Jsont.Object.map ~kind:"request" (fun header payload -> { header; payload })
|> Jsont.Object.mem "header" header_codec ~enc:(fun r -> r.header)
|> Jsont.Object.mem "payload" payload_codec ~enc:(fun r -> r.payload)
|> Jsont.Object.finish
Lists
Use Jsont.list for JSON arrays:
type response = { items : item list }
let response_codec =
Jsont.Object.map ~kind:"response" (fun items -> { items })
|> Jsont.Object.mem "items" (Jsont.list item_codec) ~enc:(fun r -> r.items)
|> Jsont.Object.finish
String Maps
Use Jsont.Object.as_string_map for objects with dynamic keys:
module String_map = Map.Make(String)
(* JSON: {"key1": "value1", "key2": "value2"} *)
let string_map_codec = Jsont.Object.as_string_map Jsont.string
(* JSON: {"group1": [...], "group2": [...]} *)
let groups_codec = Jsont.Object.as_string_map (Jsont.list item_codec)
Empty Object
For payloads that don't carry data:
let empty_payload_codec : unit Jsont.t =
Jsont.Object.map ~kind:"empty" ()
|> Jsont.Object.skip_unknown
|> Jsont.Object.finish
Custom Value Mapping
Use Jsont.map to transform between types:
type device_type = Sonos | Meross | Other
let device_from_string =
Jsont.map ~kind:"device_type"
~dec:(function "sonos" -> Sonos | "meross" -> Meross | _ -> Other)
~enc:(function Sonos -> "sonos" | Meross -> "meross" | Other -> "other")
Jsont.string
Polymorphic Decoding with any
Handle multiple JSON shapes for backwards compatibility:
(* Device can be string (old format) or object (new format) *)
let device_compat_codec =
Jsont.any ~kind:"device"
~dec_string:device_from_string_codec (* handles "192.168.1.1" *)
~dec_object:device_object_codec (* handles {"ip": "...", "type": "..."} *)
~enc:(fun _ -> device_object_codec) (* always encode as object *)
()
Null Values
Use Jsont.null for endpoints returning null:
(* For DELETE endpoints that return null on success *)
match delete http ~sw token endpoint (Jsont.null ()) with
| Ok () -> ...
Generic JSON
Use Jsont.json to preserve arbitrary JSON:
type characteristic = {
iid : int;
value : Jsont.json option; (* preserve any JSON value *)
}
let char_codec =
Jsont.Object.map ~kind:"char" (fun iid value -> { iid; value })
|> Jsont.Object.mem "iid" Jsont.int ~enc:(fun c -> c.iid)
|> Jsont.Object.opt_mem "value" Jsont.json ~enc:(fun c -> c.value)
|> Jsont.Object.finish
Encoding and Decoding
Use Jsont_bytesrw for string-based encoding/decoding:
(* Decode JSON string to OCaml value *)
let decode codec s = Jsont_bytesrw.decode_string codec s
(* Returns: ('a, Jsont.Error.t) result *)
(* Encode OCaml value to JSON string *)
let encode codec v =
match Jsont_bytesrw.encode_string codec v with
| Ok s -> s
| Error _ -> "{}" (* fallback for encoding errors *)
(* Usage *)
match Jsont_bytesrw.decode_string config_codec json_string with
| Ok config -> (* use config *)
| Error e -> (* handle error *)
match Jsont_bytesrw.encode_string config_codec config with
| Ok json_str -> (* send json_str *)
| Error _ -> (* handle error *)
Common Helpers
Define module-level helpers for cleaner code:
let decode codec s = Jsont_bytesrw.decode_string codec s
let encode codec v =
match Jsont_bytesrw.encode_string codec v with
| Ok s -> s
| Error _ -> ""
Base Types Reference
| OCaml Type | Jsont Codec | JSON Type |
|---|---|---|
string | Jsont.string | string |
int | Jsont.int | number |
float | Jsont.number | number |
bool | Jsont.bool | boolean |
'a list | Jsont.list codec | array |
'a option | Jsont.option codec | value or null |
unit | Jsont.null () | null |
| generic | Jsont.json | any JSON |
Good and Bad Examples
Missing ~kind
Bad: No kind makes error messages unhelpful
let config_codec =
Jsont.Object.map (fun name -> { name }) (* No ~kind *)
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun c -> c.name)
|> Jsont.Object.finish
(* Error: "expected string" - but where? *)
Good: Descriptive kind for clear errors
let config_codec =
Jsont.Object.map ~kind:"config" (fun name -> { name })
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun c -> c.name)
|> Jsont.Object.finish
(* Error: "config: expected string for member 'name'" *)
Strict vs Tolerant Parsing
Bad: Strict parsing breaks when API adds fields
(* API adds "created_at" field, your code breaks *)
let user_codec =
Jsont.Object.map ~kind:"user" (fun id name -> { id; name })
|> Jsont.Object.mem "id" Jsont.int ~enc:(fun u -> u.id)
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun u -> u.name)
|> Jsont.Object.finish (* No skip_unknown! *)
Good: Tolerant parsing ignores unknown fields
let user_codec =
Jsont.Object.map ~kind:"user" (fun id name -> { id; name })
|> Jsont.Object.mem "id" Jsont.int ~enc:(fun u -> u.id)
|> Jsont.Object.mem "name" Jsont.string ~enc:(fun u -> u.name)
|> Jsont.Object.skip_unknown (* Ignore extra fields *)
|> Jsont.Object.finish
Handling Optional Fields
Bad: Nullable field without default causes runtime errors
(* Field missing → decode fails *)
let config_codec =
Jsont.Object.map ~kind:"config" (fun timeout -> { timeout })
|> Jsont.Object.mem "timeout" Jsont.int ~enc:(fun c -> c.timeout)
|> Jsont.Object.finish
Good: Use opt_mem with sensible default
let config_codec =
Jsont.Object.map ~kind:"config"
(fun timeout_opt -> { timeout = Option.value ~default:30 timeout_opt })
|> Jsont.Object.opt_mem "timeout" Jsont.int ~enc:(fun c -> Some c.timeout)
|> Jsont.Object.finish
Codec Composition
Bad: Monolithic codec with duplicated patterns
let request_codec =
Jsont.Object.map ~kind:"request"
(fun msg_id method_ ts payload_id payload_data ->
{ header = { message_id = msg_id; method_; timestamp = ts };
payload = { id = payload_id; data = payload_data } })
|> Jsont.Object.mem "messageId" Jsont.string ~enc:(fun r -> r.header.message_id)
|> Jsont.Object.mem "method" Jsont.string ~enc:(fun r -> r.header.method_)
(* ... lots more fields mixed together *)
Good: Compose small, reusable codecs
let header_codec =
Jsont.Object.map ~kind:"header"
(fun message_id method_ timestamp -> { message_id; method_; timestamp })
|> Jsont.Object.mem "messageId" Jsont.string ~enc:(fun h -> h.message_id)
|> Jsont.Object.mem "method" Jsont.string ~enc:(fun h -> h.method_)
|> Jsont.Object.mem "timestamp" Jsont.int ~enc:(fun h -> h.timestamp)
|> Jsont.Object.finish
let request_codec =
Jsont.Object.map ~kind:"request" (fun header payload -> { header; payload })
|> Jsont.Object.mem "header" header_codec ~enc:(fun r -> r.header)
|> Jsont.Object.mem "payload" payload_codec ~enc:(fun r -> r.payload)
|> Jsont.Object.finish
Encoding Error Handling
Bad: Silently returning empty object on error
let encode codec v =
match Jsont_bytesrw.encode_string codec v with
| Ok s -> s
| Error _ -> "{}" (* Hides the error! *)
Good: Propagate or log encoding errors
let encode codec v =
match Jsont_bytesrw.encode_string codec v with
| Ok s -> Ok s
| Error e ->
Log.err (fun m -> m "JSON encode failed: %a" Jsont.Error.pp e);
Error (`Encode_error e)
Best Practices
- Always use
~kind: Provide descriptive kind names for better error messages - Use
skip_unknownfor external APIs: Be tolerant of extra fields from third-party services - Prefer
opt_memwith defaults: Handle missing fields gracefully withOption.value ~default: - Compose small codecs: Build complex structures from simple, reusable codecs
- Define helper functions: Create
decode/encodehelpers at module level for cleaner usage
OCaml Logs Patterns
The logs library provides structured logging with per-module sources.
Module Setup
Every module that logs should create its own source:
let log_src = Logs.Src.create "project.module_name"
module Log = (val Logs.src_log log_src : Logs.LOG)
This is the standard idiom. Do NOT attempt to abstract or deduplicate this boilerplate.
Log Levels
| Level | Function | Use Case |
|---|---|---|
| App | Log.app | Always shown to user (startup, completion) |
| Error | Log.err | Handled but critical errors |
| Warning | Log.warn | Potential issues, operation continues |
| Info | Log.info | State transitions, progress |
| Debug | Log.debug | Verbose debugging details |
Basic Logging
Log.info (fun m -> m "Processing %d items" count);
Log.err (fun m -> m "Failed to connect: %s" reason);
Log.debug (fun m -> m "Request: %a" Request.pp req)
Structured Tags
Add context with tags for filtering/analysis:
Log.info (fun m ->
m "Event received: %s" event_type
~tags:(Logs.Tag.add "channel_id" channel Logs.Tag.empty))
Reporter Setup (bin/)
In CLI applications, set up the reporter in bin/common.ml:
let setup_log style_renderer level =
Fmt_tty.setup_std_outputs ?style_renderer ();
Logs.set_level level;
Logs.set_reporter (Logs_fmt.reporter ())
open Cmdliner
let setup_log =
Term.(const setup_log
$ Fmt_cli.style_renderer ()
$ Logs_cli.level ())
system_prompt
You are a specialised coding agent for OCaml allocation profiling with memtrace. Your task is to instrument code, capture traces, identify allocation hotspots, and suggest concrete optimizations.
You must:
- Keep tracing gated behind the MEMTRACE environment variable.
- Target specific tests or benchmarks to isolate hotspots.
- Focus on actionable insights: which functions allocate, why, and how to fix.
- Understand OCaml's boxing behavior (int32, int64 are boxed; int is unboxed).
instructions
When to apply this skill
Use this skill when:
- Investigating why a function allocates more than expected
- Identifying boxing overhead (int32, int64, floats in arrays)
- Optimizing hot paths in parsing/serialization code
- Comparing allocation behavior before and after changes
Do not use this skill for:
- Exact allocation counting (memtrace is statistical)
- Performance timing (use
Sys.timeor benchmarks for that) - Memory leak debugging (memtrace shows allocations, not leaks)
Instrumentation pattern
Add to the main entrypoint, before any work begins:
let () =
Memtrace.trace_if_requested ();
(* rest of program *)
For Alcotest test suites:
(* test/test.ml *)
let () =
Memtrace.trace_if_requested ();
Alcotest.run "suite-name" [
Test_foo.suite;
Test_bar.suite;
]
Rules:
- Call once, at program start
- No
~contextargument needed for simple cases - Never enable tracing unconditionally
Build configuration
Add memtrace to the test executable in dune:
(test
(name test)
(libraries memtrace alcotest ...))
Or for a standalone executable:
(executable
(name main)
(libraries memtrace ...))
Running with memtrace
Basic usage:
MEMTRACE=trace.ctf dune exec -- path/to/exe
For Alcotest, target a specific test to isolate allocations:
# Run specific test suite
MEMTRACE=trace.ctf dune exec -- test/test.exe test "binary"
# Run specific test by index within suite
MEMTRACE=trace.ctf dune exec -- test/test.exe test "binary" 68
# List available tests first
dune exec -- test/test.exe test list
The trace file (.ctf) is binary but contains embedded strings showing:
- Source file paths and line numbers
- Function names and call stacks
- Allocation counts and sizes
Analyzing traces
With memtrace-viewer (GUI):
memtrace-viewer trace.ctf
# Opens browser at http://localhost:8080
With memtrace-hotspot (CLI):
opam install memtrace-hotspot
memtrace-hotspot trace.ctf
Reading raw trace output:
The MEMTRACE environment produces summary output showing:
- Total allocations in bytes
- Top allocation sites by percentage
- Call stacks leading to allocations
Example output:
76.3 MB total allocations
30.2% lib/binary.ml:194 Bytes.get_int32_be
15.1% lib/binary.ml:210 Bytes.get_int64_be
...
Common hotspots and fixes
1. Int32/Int64 boxing
Problem: Bytes.get_int32_be returns int32 which is always boxed.
(* SLOW: boxes on every call *)
let v = Bytes.get_int32_be buf off
Fix: Read bytes individually, box only at the end:
(* FAST: single box at the end *)
let read_uint32_be buf off =
let b0 = Bytes.get_uint8 buf off in
let b1 = Bytes.get_uint8 buf (off + 1) in
let b2 = Bytes.get_uint8 buf (off + 2) in
let b3 = Bytes.get_uint8 buf (off + 3) in
Int32.of_int ((b0 lsl 24) lor (b1 lsl 16) lor (b2 lsl 8) lor b3)
2. Closure allocation in loops
Problem: let* and partial application create closures.
(* SLOW: closure per iteration *)
List.iter (fun x -> process key x) items
Fix: Inline or use direct recursion:
(* FAST: no closure *)
let rec loop = function
| [] -> ()
| x :: xs -> process key x; loop xs
in loop items
3. Array bounds checking
For proven-safe indices, use unsafe access:
(* Lookup table - indices always valid *)
Array.unsafe_get table ((byte lsr 4) land 0xF)
Optimization workflow
- Baseline: Run benchmark with memtrace, note total allocations
- Identify: Find top allocation sites (>10% of total)
- Analyze: Determine if allocations are necessary or avoidable
- Fix: Apply targeted optimizations (see common fixes above)
- Validate: Re-run with memtrace, compare totals
Example from this codebase:
- Before: 76.3 MB total (Bytes.get_int32_be = 30%)
- After: 53.4 MB total (byte-by-byte reads)
- Reduction: 30%
Considerations for int32/int64 APIs
If your API returns int32 or int64, boxing is unavoidable at the boundary.
Consider:
- Optint.Int63.t: Unboxed on 64-bit platforms, fits in native int
- Returning int: If values fit in 31/63 bits, avoid boxed types entirely
- Streaming APIs: Process data without intermediate boxed values
Check what other libraries do:
bytesrw: Usesintwhere possible,int64only when necessary
Expected outputs
When this skill is invoked, produce:
- Instrumentation patch (single
Memtrace.trace_if_requested ()call) - Dune changes if memtrace not already linked
- Exact command to run targeted benchmark with tracing
- Analysis of trace output identifying top hotspots
- Concrete code changes to reduce allocations
- Before/after comparison showing improvement
Avoiding common mistakes
- Wrong process: Trace the worker, not the test harness
- Too broad: Target specific tests, not entire suites
- Comparing apples to oranges: Same workload, same sampling rate
- Premature optimization: Focus on hotspots >10% of allocations
- Breaking APIs: Don't change public signatures just to avoid boxing
OCaml to NPM Publishing
When to Use This Skill
Invoke this skill when:
- Setting up npm publishing for OCaml projects
- Configuring js_of_ocaml or wasm_of_ocaml
- Discussing browser targets for OCaml
- Creating the npm branch workflow
Branch Structure
main branch - OCaml source code, dune build files, opam packages
npm branch - Built JavaScript/WASM assets, package.json, README for npm
The npm branch is an orphan branch with no shared history.
Dune Build Rules
Library with Browser Bindings
In lib/js/dune:
; Library compiled to bytecode (required for js_of_ocaml)
(library
(name mylib_js)
(public_name mylib-js)
(libraries mylib brr)
(modes byte)
(modules mylib_js))
; Executable compiled to both JS and WASM
(executable
(name mylib_js_main)
(libraries mylib_js)
(js_of_ocaml)
(modes js wasm)
(modules mylib_js_main))
; Friendly filename for JS
(rule
(targets mylib.js)
(deps mylib_js_main.bc.js)
(action (copy %{deps} %{targets})))
; Friendly filename for WASM
(rule
(targets mylib.wasm.js)
(deps mylib_js_main.bc.wasm.js)
(action (copy %{deps} %{targets})))
; Install web assets
(install
(package mylib-js)
(section share)
(files
mylib.js
mylib.wasm.js
(glob_files_rec (mylib_js_main.bc.wasm.assets/* with_prefix mylib_js_main.bc.wasm.assets))))
dune-project Package
(package
(name mylib-js)
(synopsis "Browser library via js_of_ocaml/wasm_of_ocaml")
(depends
(ocaml (>= 5.1.0))
(mylib (= :version))
(js_of_ocaml (>= 5.0))
(js_of_ocaml-ppx (>= 5.0))
(wasm_of_ocaml-compiler (>= 5.0))
(brr (>= 0.0.6))))
Creating the NPM Branch
# Create orphan branch
git switch --orphan npm
# Add npm-specific files
git add package.json README.md LICENSE release.sh .gitignore
git commit -m "Initial npm package setup"
# Switch back
git checkout main
NPM Branch Files
See templates/ for:
package.json.templaterelease.sh.template
package.json
{
"name": "mylib-jsoo",
"version": "1.0.0",
"description": "Description here",
"browser": "mylib.js",
"license": "MIT",
"repository": {
"type": "git",
"url": "git+https://github.com/user/repo.git#npm"
},
"files": [
"mylib.js",
"mylib.wasm.js",
"mylib_js_main.bc.wasm.assets/",
"README.md",
"LICENSE"
]
}
Key points:
- Use
"browser"not"main"(js_of_ocaml is browser-only) - Point repository URL to
#npmbranch - Include WASM assets directory
release.sh
Script to copy built assets from main branch to npm branch.
Workflow Summary
- Develop on
mainbranch (OCaml source) - Build:
dune build @install - Switch to
npmbranch - Run
./release.shto copy built assets - Update version in
package.json - Commit and
npm publish
README for npm
Focus on browser usage:
- Clear browser-only notice
- Installation via npm
- Browser usage with
<script>tags - Both JS and WASM examples
- Browser compatibility requirements
OCaml Documentation (odoc) Skill
When to Use
Use this skill when fixing odoc documentation warnings, typically from dune build @doc.
This skill covers odoc mechanics only. Load the doc-style skill as well
whenever you write or reword the prose of a doc comment.
Prerequisites: This skill covers odoc v3 syntax which is not yet in released versions of dune or odoc. You need:
- dune pinned to https://github.com/jonludlam/dune/tree/odoc-v3-rules-3.21
- odoc pinned to https://github.com/jonludlam/odoc/tree/staging
Reference Syntax
Use path-based disambiguation {!Path.To.kind-Name} rather than {!kind:Path.To.Name}:
(* Correct *)
{!Jsont.exception-Error}
{!Proto.Incoming.t.constructor-Message}
{!module-Foo.module-type-Bar.exception-Baz}
(* Incorrect *)
{!exception:Jsont.Error}
{!constructor:Proto.Incoming.t.Message}
This allows disambiguation at any position in the path.
Reference Kinds
module-for modulestype-for typesval-for valuesexception-for exceptionsconstructor-for variant constructorsfield-for record fieldsmodule-type-for module types
Cross-Package References
When odoc cannot resolve a reference to another package, add a documentation dependency in dune-project:
(package
(name mypackage)
...
(documentation (depends other-package)))
Do NOT convert doc references {!Foo} to code markup [Foo] - this loses the hyperlink.
Cross-Library References (Same Package)
When referencing modules from another library in the same package, use the full path through re-exported modules.
Example: If claude.mli has module Proto = Proto, reference proto modules as {!Proto.Incoming} not {!Incoming}.
Missing Module Exports
If odoc reports "Couldn't find X" where X is the last path component:
- Check if the module is re-exported in the parent module's
.mli - Add
module X = Xto the parent's.mliif missing
Ambiguous References
When odoc warns about ambiguity (e.g., both an exception and module named Error):
{!Jsont.exception-Error} (* for the exception *)
{!Jsont.module-Error} (* for the module *)
@raise Tags
For @raise documentation tags, use the exception path with disambiguation:
@raise Jsont.exception-Error
@raise Tomlt.Toml.Error.exception-Error
Escaping @ Symbols
The @ character is interpreted as a tag marker in odoc. When you need a literal @ in documentation text (e.g., describing @-mentions), escape it with a backslash:
(* Correct - escaped @ *)
(** User was \@-mentioned *)
(** Mentioned via \@all/\@everyone *)
(* Incorrect - will produce "Stray '@'" or "Unknown tag" warnings *)
(** User was @-mentioned *)
(** Mentioned via @all *)
Hidden Fields Warning
When odoc warns about "Hidden fields in type 'Foo.Bar.t': field_name", it means a record field uses a type that odoc can't resolve in the documentation.
Diagnosis:
- Find the field definition in the
.mlifile - Identify what type the field uses (e.g.,
uri : Uri.t) - Check if that type's module is re-exported in the wrapper
.mli
Fix Option 1: Re-export the module in the wrapper .mli:
(** RFC 3986 URI parsing *)
module Uri = Uri
Fix Option 2: If you only want to expose the type (not the whole module), use @canonical:
-
Add a type alias in the wrapper
.mli:type uri = Uri.t -
Add
@canonicalto the original type's documentation:(* In uri.mli *) type t (** A URI. @canonical Requests.uri *)
This tells odoc to link Uri.t to Requests.uri in the generated documentation.
Interpreting Error Messages
| Error Pattern | Meaning | Fix |
|---|---|---|
unresolvedroot(X) | X not found as root module | Check library dependencies, add documentation depends |
Couldn't find "Y" after valid path | Y doesn't exist at that location | Verify module structure, check exports |
Reference to 'X' is ambiguous | Multiple items named X | Add kind qualifier (e.g., exception-X) |
Hidden fields in type ... : field | Field's type not resolvable | Re-export the type's module in wrapper .mli |
Debugging
- Run
dune cleanbeforedune build @docto ensure fresh builds - Check the library's
.mlifile to see what modules are exported - For cross-library refs, trace the module path through re-exports
OCaml Development
Core Philosophy
- Interface-First Design: Design the
.mlifile first. A clean interface matters more than clever implementation. - Modularity: Build small, focused modules that do one thing well. Compose them for larger systems.
- Simplicity (KISS): Prioritize clarity over conciseness. Avoid obscure constructs.
- Explicitness: Make control flow and error handling explicit. Avoid exceptions for recoverable errors.
- NEVER use Obj.magic: It breaks type safety. There is always a better solution.
Build System and Tooling
- Build: Use
duneexclusively - Formatting: Run
dune fmtbefore committing (uses ocamlformat) - Common Libraries:
- Concurrency:
eio - Structured output:
fmt - Logging:
logs - CLI parsing:
cmdliner - JSON:
jsont - HTTP:
cohttp-eio
- Concurrency:
Module Interface Design
Documentation Pattern
Write ocamldoc in the voice of a POSIX manual page. Full sentences, no
extraneous detail, no colons or em dashes joining clauses, and nothing about
the implementation. Load the doc-style skill before writing or changing any
comment. It is the full standard and this section is only its summary.
Every .mli file starts with a synopsis, then a blank line, then the
description.
(** User accounts and profiles.
Users are workspace members. A user is identified by an {!type:id} that is
stable for the lifetime of the account. *)
Function Documentation
Open with the function applied to its arguments, followed by is:
val is_bot : t -> bool
(** [is_bot u] is [true] if [u] is a bot user. *)
val find : id -> t -> user option
(** [find id t] is the user of [t] with identifier [id], or [None] if [t] has
no such user. *)
Reserve an active verb for functions that exist for their effect:
val flush : out_channel -> unit
(** [flush oc] writes the buffered bytes of [oc] to its underlying file. *)
For types, describe what the values represent, never their representation:
type id = string
(** The type for user identifiers. An identifier is unique within a workspace
and stable across renames. *)
Implementation Comments
Implementations carry no comments where the code says it already. Write one
only for a spec citation, a non-local invariant, a deliberate workaround, or a
justification for an unsafe operation. Documentation lives in the .mli, so
an .ml with an .mli has no (** ... *) comments at all.
Standard Interface for Data Types
For modules with a central type t, provide these functions where applicable:
| Function | Purpose |
|---|---|
val v : ... -> t | Pure smart constructor (no I/O) |
val create : ... -> (t, Error.t) result | Constructor with side-effects |
val pp : t Fmt.t | Pretty-printer for logging/debugging |
val equal : t -> t -> bool | Structural equality |
val compare : t -> t -> int | Comparison for sorting |
val of_json : Yojson.Safe.t -> (t, string) result | Parse from JSON |
val to_json : t -> Yojson.Safe.t | Serialize to JSON |
val validate : t -> (t, string) result | Validate data integrity |
Abstract Types
Keep types abstract (type t) when possible. Expose smart constructors and accessors instead of record fields to maintain invariants.
Error Handling
Use result type for recoverable errors. Reserve exceptions for programming errors (e.g., Invalid_argument).
Central Error Type
Define a comprehensive error type in lib/error.ml:
(* In lib/error.mli *)
type t = [
| `Api of string * Yojson.Safe.t
| `Json_parse of string
| `Network of string
| `Msg of string
]
val pp : t Fmt.t
Error Helper Pattern
let err_api code fields = Error (`Api (code, fields))
let err_parse msg = Error (`Json_parse msg)
let find_user_id json =
match Yojson.Safe.Util.find_opt "id" json with
| Some (`String id) -> Ok id
| Some _ -> err_parse "Expected string for user ID"
| None -> err_parse "Missing user ID"
Rules
- Never use
try ... with _ -> .... Match specific exceptions. - For unrecoverable startup errors, use
Fmt.failwith:
let tls_config =
match Tls.Config.client ~authenticator () with
| Ok config -> config
| Error (`Msg msg) -> Fmt.failwith "Failed to create TLS config: %s" msg
Function Design
- Keep functions small: One function, one purpose. Decompose complex logic.
- Avoid deep nesting: More than 2-3 levels of
match/ifsignals need for refactoring. - Prefer purity: Isolate side-effects at edges (
bin/,lib/ui/). - Composition over abstraction: Favor small concrete functions over deep abstractions.
- Data-oriented: Operate on simple, immutable data structures.
- No premature generalization: Solve the problem at hand, avoid unnecessary complexity.
Logging
Use the logs library with per-module log sources:
let log_src = Logs.Src.create "project_name.module_name"
module Log = (val Logs.src_log log_src : Logs.LOG)
Log Levels
| Level | Use Case |
|---|---|
Log.app | Messages always shown to user (startup) |
Log.err | Handled but critical errors |
Log.warn | Potential issues, operation continues |
Log.info | Informational state messages |
Log.debug | Verbose debugging details |
Structured Logging
Log.info (fun m ->
m "Received event: %s" event_type
~tags:(Logs.Tag.add "channel_id" channel_id Logs.Tag.empty))
Naming Conventions
| Element | Convention | Example |
|---|---|---|
| Files | lowercase_underscores | user_profile.ml |
| Modules | lowercase_underscores | user_profile |
| Primary type | t | type t |
| Identifiers | id | type id = string |
| Values | short_descriptive | find_user, create_channel |
Labels
Use labels only when they clarify meaning. Avoid ~f and ~x.
CLI Applications
For bin/ applications using cmdliner:
- Place shared functionality (auth, logging setup) in
bin/common.ml - Provide a shared
runfunction that initializes the main loop and environment (e.g., Eio loop) - All commands should use this function for consistent environment
Commit Messages
Follow Conventional Commits:
Format: type(scope): subject
| Type | Purpose |
|---|---|
feat | New feature |
fix | Bug fix |
docs | Documentation |
style | Formatting |
refactor | Code restructuring |
test | Tests |
chore | Maintenance |
Examples:
feat(api): add support for file uploadsfix(ui): correct channel list rendering bugtest(user): add tests for user profile updates
You are writing code for the OxCaml compiler, a performance-focused fork of OCaml with Jane Street extensions. This guide covers OxCaml-specific features only; standard OCaml is assumed.
Current target: OxCaml 5.4.0-ox9 — oxcaml-compiler.5.4.0-ox9
/ ocaml-variants.5.4.0+ox, on the OCaml 5.4 base
(ocamlopt -version prints 5.4.0+ox for every ox release; the exact
check is opam var oxcaml-compiler:release). The previous target was
5.2.0minus-39 (OCaml 5.2 base).
Migrating a project from minus-39? Follow MIGRATION-39-ox9.md: step-by-step guide, error-message lookup table, before/after code checked on both compilers, forms that build on both.
Change history, newest first: CHANGES-39-ox9.md
(5.2.0minus-39 → 5.4.0-ox9: minus-40, the upstream OCaml 5.4
merge, ox1 … ox9), CHANGES-38-39.md,
CHANGES-31-38.md,
CHANGES-25-31.md,
CHANGES-23-25.md.
Quick Upgrade Flags (minus-39 → ox9)
When a build fails after a bump from minus-39, check these first (most common first; the fix for each and an ordered checklist are in MIGRATION-39-ox9.md):
int64#,int32#,nativeint#,float32#are gone →int64_u,int32_u,nativeint_u,float32_u("The type int64 has no unboxed version. Hint: Did you mean int64_u?"). Literals (#42L),float#/int8#/int#/…, and"%…#…"primitive names are unchanged.int64_u box≠int64.- Rebuild everything, ppx rewriters and tools included (magic numbers
578 → 586); Jane Street libraries move to
v0.18~preview.133.03+642. effectis a keyword → rename identifiers or pass-keywords 5.2.- Tooling gaps: no odoc for ox9 (
dune build @doccannot work);ocamlformat 0.29.0+oxrejects aversion = …line in.ocamlformatand cannot parse| effectpatterns,overwrite_orval poly_; on arm64ocaml_simdneeds aCPATHworkaround to install (MIGRATION-39-ox9.md step 0). fst p/snd pon a local pair in tail position is an error: bind the result, add[@nontail], or useexclave_(section 2).type ('a : any) t = { x : 'a }needs-extension layouts_beta(minus-39 silently narrowed the annotation).- All-void constructors (
A of unit#) need[@immediate_all_void_constructor]. - New default-on warnings: 181
imprecise-kind-annotation, 183/184 kind modifiers, 220redundant-modality(@@ global aliased,mutable f : t @@ aliased); 211 renamedmod-by-top→redundant-modifier(use-211); 189 → 75. Effect.performraises anunsafe_effectsalert → useEffect.Safe.perform.{ t with … }may not implicitly copy an[@atomic]field.- Integer literals at max+1 (
128s,32768S,9223372036854775808L, …) are errors — they used to wrap to the minimum. compiler-libs.commonwas split: addcompiler-libs.frontendforPath/Types/Env/Typedtree/….- SIMD load/store primitives on
float arrayremoved; AVX-512 types need-extension simd_beta. - Runtime 4 retired:
--disable-runtime5is a configure error. - Error messages no longer double-quote identifiers in uncoloured output (matters when grepping compiler output or comparing against older docs) and many were reworded → re-promote expect tests.
- C stubs:
caml_failure_exnremoved (usecaml_exception_failure_value);caml_callback_res/caml_resultsupersede the_exnvariants (which still compile).
Detailed Guides
| Feature | Guide |
|---|---|
| Modes (local, unique, once, portable, contended) | SKILL-MODES.md |
| Stack Allocation (local_, stack_, exclave_) | SKILL-STACK-ALLOCATION.md |
| Unboxed Types (float#, int64_u, mixed blocks) | SKILL-UNBOXED.md |
| Kinds (value, float64, bits32, kind products) | SKILL-KINDS.md |
| Uniqueness (unique/aliased, once/many) | SKILL-UNIQUENESS.md |
| Comprehensions (list/array builders) | SKILL-COMPREHENSIONS.md |
| SIMD (vector types, SSE/AVX intrinsics) | SKILL-SIMD.md |
| Templates (ppx_template, mangling) | SKILL-TEMPLATES.md |
| Zero-Alloc ([@zero_alloc] checking) | SKILL-ZERO-ALLOC.md |
| Base Library (OxCaml extensions) | SKILL-BASE.md |
| Core Library (OxCaml extensions) | SKILL-CORE.md |
1. Modes
Modes track runtime properties of values. Each mode axis is independent.
| Axis | Values | Default | Purpose |
|---|---|---|---|
| Locality | local, global | global | Where value lives (stack vs heap) |
| Uniqueness | unique, aliased | aliased | Number of references |
| Linearity | once, many | many | How often closures can be called |
| Portability | portable, corruptible, shareable, nonportable | nonportable | Cross-thread safety |
| Contention | uncontended, shared, corrupted, contended | uncontended | Thread access patterns |
| Visibility | read_write, read, write, immutable | read_write | Mutable-field access rights |
| Statefulness | stateless, reading, writing, stateful | stateful | Closed-over mutable state |
Portability/contention and visibility/statefulness are 4-element
diamonds (shared/corrupted and read/write are
incomparable). observing is now spelled reading. This table is the
commonly used subset — there are also unyielding/yielding,
forkable/unforkable and static/dynamic axes. No axis or mode
name changed between minus-39 and ox9.
let f (x @ local) = ... (* on a parameter *)
let f (x @ local unique once) = ... (* multiple modes *)
val g : t @ unique once -> t @ aliased many (* in signatures *)
let x = (expr : t @ local) (* on an expression *)
let local_ x = ... (* local_ is the only legacy let
prefix (global is default) *)
type t = { (* record fields: modalities *)
global_ data : int; (* always global *)
shared : int list @@ aliased; (* aliased modality *)
mutable x : int; (* mutable => global many aliased
already; writing them out is
warning 220 *)
}
Subtyping — a more restrictive mode can be used where a less
restrictive one is expected: global ≤ local, unique ≤ aliased,
many ≤ once, portable ≤ shareable/corruptible ≤
nonportable, uncontended ≤ shared/corrupted ≤ contended
(diamonds: the two middle modes are incomparable).
SKILL-MODES.md also covers inference of mode
implications and curry modes, coercions that mode-cross function
returns, and inference-only mode polymorphism (-extension mode_polymorphism_alpha).
2. Stack Allocation (Locality)
Stack-allocated values avoid GC overhead but cannot escape their scope (SKILL-STACK-ALLOCATION.md).
let f () =
let local_ x = (1, 2) in (* stack-allocated tuple *)
let p = stack_ (3, 4) in (* force stack allocation *)
fst x + snd p
(* Return a local value: allocated in the caller's frame *)
let make_pair x y = exclave_ stack_ (x, y)
(* exclave_ is REQUIRED around a local-returning tail call *)
let g () = exclave_ make_pair 1 2
- Local values cannot escape their defining scope (no storing in
globals, no returning without
exclave_). - Local values can reference global values; global values cannot reference local values.
exclave_ends the current region so what follows allocates in the caller's region; it must be at tail position.- A local-returning call in tail position must be under
exclave_("This local-returning application is in a tail position that is not enclosed in an exclave_ expression") — this includesfst p/snd pon a local tuple; bind the result or add[@nontail]instead if you want a global result. - A local value cannot be passed to a tail call ("is local … because
it is an argument in a tail call") — write
f x [@nontail]. - Stdlib functions (
List.iter,Array.fold_left, …) take global arguments (and a closure passed toList.itercannot capture a local): on local data use explicit recursion (let rec go acc (l @ local) = …) or Base's local-aware variants. - Accumulators can be local refs:
let local_ r = ref 0 in …; !r.
3. Unboxed Types
Unboxed types store values directly without heap allocation. A #
suffix or _u name means unboxed (int64#, int32#, nativeint#,
float32# no longer exist — use the _u names); literals use a #
prefix, and a minus sign goes outside: -#1l.
| Type | Description | Kind | Literal |
|---|---|---|---|
float# | 64-bit float | float64 | #3.14 |
float32_u | 32-bit float | float32 | #1.0s |
int32_u | 32-bit int | bits32 | #42l |
int64_u | 64-bit int | bits64 | #100L |
nativeint_u | native int | word | #42n |
int8# | 8-bit int, untagged | bits8 | #42s |
int16# | 16-bit int, untagged | bits16 | #42S |
int# | native int, untagged | untagged_immediate | #42m |
char# | 8-bit char, untagged, same layout as int8# | bits8 | #'x' |
bool# | 8-bit bool | bits8 | #true, #false |
unit# | zero-size | void | #() |
uint8_u,uint16_u,uint32_u,uint64_u,unativeint_uare opaque unsigned types: no literals/operations.- Small numbers also have non-unboxed types:
float32(1.0s),int8(42s),int16(42S). char#patterns take ranges:| #'a'..#'z' -> ….'a boxis the boxed version of an unboxed type:float# box = float;r# box = r(butint64_u box <> int64).
(* Unboxed record - stored inline, not heap-allocated *)
type point = #{ x : float#; y : float# }
let p : point = #{ x = #1.0; y = #2.0 }
let get_x (p : point) = p.#x
(* Unboxed tuple; destructure with a #(...) pattern *)
type pair = #(float# * int32_u)
let first (q : pair) = let #(a, _) = q in a
(* Mixed block: boxed and unboxed fields, unboxed stored flat *)
type mixed = { name : string; value : float#; count : int32_u }
(* or_null: non-allocating option for value types (Null is encoded
without a box). Predefined: type 'a or_null = Null | This of 'a
(don't redeclare). The argument must be a non-null value type:
float# or_null is rejected *)
let find (arr : string array) idx : string or_null =
if idx < Array.length arr then This arr.(idx) else Null
(* Custom or_null types: any two-constructor variant (one nullary,
one unary) can opt into the same non-allocating encoding *)
type 'a maybe = Nope | Yep of 'a [@@or_null]
type no_param = A | B of int [@@or_null] (* payload shape is free *)
- Mixed blocks:
[@atomic]fields (layoutvalue) are allowed;[@@flatten_floats]is optional on records mixingfloatandfloat#. - Arrays of untagged types are packed:
int8# arrayandchar# arrayuse 1 byte per element,int16# array2 bytes,int# arraya native word ([| #0m; #1m |]).int8 arrayandint16 arrayhold tagged immediates: one word each. - Stdlib's
Array.get/set/lengthonly acceptvalueelements, soa.(i)on an unboxed array needsopen Base(layout-polymorphicArray) or[@layout_poly]externals. - SKILL-UNBOXED.md also covers
array#/iarray#, block indices (idx_atomic, …), all-void constructors and C interop.
4. Kinds
Kinds classify types by their runtime representation
(SKILL-KINDS.md). any (any layout) is the top.
Under it: value_or_null (values, possibly null), which contains
value (standard OCaml boxed values), which contains immediate
(int, bool, char, …); and, each directly under any, float64,
float32, bits8, bits16, bits32, bits64, word (native word
size), untagged_immediate, vec128/vec256/vec512 (SIMD
vectors), void (zero-width).
type ('a : float64) container = ... (* on type parameters *)
val f : ('a : value). 'a -> 'a (* on type variables in signatures *)
type t : float64 (* on abstract types *)
type pair : float64 & bits32 (* kind product: unboxed pair of
float# and int32_u *)
type t : value mod global (* mode bound: crosses locality, a local
t can be used as global *)
type t : value mod portable (* always portable *)
Abbreviations such as immediate64, mutable_data and
immutable_data are defined in SKILL-KINDS.md.
- Kind annotations are linted by default: warning 181 if an annotation
is weaker than the inferred kind (
('a : any) … 'a list), 183/184 for redundant/ignored scannable-axis modifiers, 211 for redundantmodbounds (value mod global aliased,value mod local). addressableis a postfix kind modifier.- A field of kind
anyneeds-extension layouts_beta. - Layout-polymorphic
let poly_/val poly_need-extension layout_poly_alpha.
5. Uniqueness
unique: a single reference exists (safe mutation/deallocation);
aliased: multiple references may exist
(SKILL-UNIQUENESS.md).
val free : t @ unique -> unit (* unique parameter: consumed *)
val duplicate : t -> t * t @ aliased (* aliased return *)
val delay_free : t @ unique -> (unit -> unit) @ once
(* once closure: invoked once only *)
(* Aliased modality: container is unique but contents are aliased *)
type 'a aliased_box = { value : 'a @@ aliased } [@@unboxed]
let ok t = match t with Con { field } -> free t
(* OK: match then use uniquely *)
let bad t = match t with (* ERROR: using parts twice *)
| Con { field } ->
free_field field; (* uses field *)
free t (* uses t which contains field *)
let ok t = match t with (* OK: different branches *)
| Con { field } -> if cond then free_field field else free t
6. Comprehensions
List and array builders
(SKILL-COMPREHENSIONS.md). Still a beta
extension: compile with -extension comprehensions.
[ x * 2 for x = 1 to 10 ]
[ x for x = 1 to 100 when x mod 2 = 0 ] (* filter *)
[ String.uppercase_ascii s for s in strings ] (* iterate over list *)
[ x + y for x = 1 to 10 for y = 1 to 10 when x < y when x + y < 15 ]
[| f elem for elem in source_array |] (* array: [| |] *)
[: x for x = 1 to 10 when x mod 2 = 0 :] (* immutable array *)
[ (x, y) for x = 1 to 3 for y = 1 to 3 ] (* 9 elements *)
[ (x, y) for x = 1 to 3 and y = 10 to 12 ] (* 9 elements:
[(1,10); (1,11); (1,12); (2,10); ...] *)
for ... for ... and for ... and ... both produce the Cartesian
product — comprehensions cannot zip. for ... for ... is nested
(inner source re-evaluated each outer iteration; inner iterators may
reference outer variables); with for ... and ... sources are
evaluated once upfront and iterators are independent (cannot reference
each other), which enables exact-size array pre-allocation.
7. SIMD Vector Types
128-bit and 256-bit SIMD vectors (SKILL-SIMD.md;
128-bit also works natively on arm64/NEON). 512-bit vectors and mask
types exist under -extension simd_beta (AVX-512: types and
load/store only — no intrinsics yet). Each type has a boxed and an
unboxed (#) form, e.g. int8x16 / int8x16#. 128-bit: int8x16,
int16x8, int32x4, int64x2, float32x4, float64x2; 256-bit:
int8x32, int32x8, float64x4, etc.; 512-bit: int8x64 …
float64x8, mask, mask#.
(* dune: (libraries ocaml_simd.sse) *)
open Ocaml_simd_sse
let v = Float32x4.set #1.0s #2.0s #3.0s #4.0s (* float32_u, lane 0 first *)
let v = Float32x4.sqrt v
let #(x, y, z, w) = Float32x4.splat v
let v = Int8x16.String.get text ~byte:0 (* load *)
C stubs:
external vec_op : (int8x16[@unboxed]) -> (int8x16[@unboxed]) =
"boxed_stub" "unboxed_stub"
8. Templates (ppx_template)
Generate multiple copies of code with different modes/kinds (SKILL-TEMPLATES.md).
(* Mode template: generates id (global) and id__local *)
let%template[@mode m = (global, local)] id
: 'a. 'a @ m -> 'a @ m
= fun x -> x
(* Instantiate (exclave_ because the local instance returns local) *)
let f (x @ local) = exclave_ (id [@mode local]) x
(* Kind template: generates id (value) and id__float64 *)
let%template[@kind k = (value, float64)] id
: ('a : k). 'a -> 'a
= fun x -> x
(* Exclave conditional: local version gets exclave_ (x, y) *)
let%template[@mode m = (global, local)] make_pair x y =
(x, y) [@exclave_if_local m]
(* ~reasons is needed because (f a, f b) is not a plain allocation of
identifiers/constants *)
let%template[@mode m = (global, local)] map_pair f (a, b) =
((f a, f b) [@exclave_if_local m ~reasons:[ May_return_local ]])
(* Alloc template *)
let%template rec map
: f:('a -> 'b @ m) -> 'a list -> 'b list @ m
= fun ~f list ->
match[@exclave_if_stack a] list with
| [] -> []
| hd :: tl -> f hd :: (map [@alloc a]) ~f tl
[@@alloc a @ m = (heap_global, stack_local)]
(* Kind-polymorphic container (not `box` — that name is the predefined
'a box type) *)
type%template ('a : k) cell = { contents : 'a }
[@@kind k = (value, float64, bits64)]
- Portable/nonportable functor variants, short form:
module%template.portable Make (M : S) : T. - Default floating attributes:
[%%template: [@@@mode.default m = (global, local)] val min : t @ m -> t @ m -> t @ m ]. - Library functions are instantiated the same way (Base):
(List.map [@alloc stack]) lst ~f,(List.fold [@mode local global]) l ~init ~f. - Mangled names follow the
__suffixpattern.
9. Zero-Alloc Checking
Compile-time verification that functions don't allocate.
let[@zero_alloc] fast_add x y = x + y (* must not allocate *)
let[@zero_alloc] with_local_pair x y = (* local/stack allocations
are allowed *)
let p = stack_ (x, y) in
fst p + snd p
let[@zero_alloc opt] complex_func x = ... (* only checked in optimized builds *)
let[@zero_alloc strict] very_strict x = ... (* no allocation even on error paths *)
let[@zero_alloc assume] external_wrapper x = external_func x
(* trusted to be zero-alloc *)
let[@cold][@zero_alloc assume error] handle_error e = ...
(* assume for error paths *)
val[@zero_alloc] f : int -> int (* in signatures; also strict *)
val[@zero_alloc arity 2] h : int -> int -> int
[@@@zero_alloc all] (* file-level: all functions
must be zero-alloc *)
let[@zero_alloc ignore] allowed_to_alloc x = [x] (* opt out *)
On failure, -zero-alloc-checker-details-cutoff -1 prints full
details. See SKILL-ZERO-ALLOC.md.
10. Parallelism & Capsules
Contention and portability modes: section 1 and SKILL-MODES.md.
Spawning work. Domain.spawn carries the do_not_spawn_domains
and unsafe_multidomain alerts. Use the parallel library
(Parallel.fork_join2, Parallel_scheduler.with_parallel; results
are unboxed tuples: let #(x, y, z) = Parallel.fork_join3 par f1 f2 f3) for
structured parallelism, or Multicore.spawn (compiler threads
library) at the low level:
(* dune: (libraries base portable threads) *)
let counter = Portable.Atomic.make 0
let () =
match Multicore.spawn (fun () -> Portable.Atomic.incr counter) () with
| Spawned -> ()
| Failed ((), exn, bt) -> Printexc.raise_with_backtrace exn bt
(The opam compiler is built with --enable-multidomain and
--enable-poll-insertion.)
Capsules (capsule / portable libraries; Core.Capsule)
isolate mutable state so it can be shared safely (examples:
SKILL-CORE.md):
- Read-only sharing — build mutable data, then freeze it:
Capsule.Frozen.create (fun () -> …), thenlet (t @ shared) = Capsule.Frozen.unwrap tableand read with shared-mode instances such as(Array.get [@mode shared]) t i. - Data tied to the current capsule via an access token:
let (P access) = Capsule.Access.current (), thenCapsule.Data.wrap ~access v/Capsule.Data.unwrap ~access d. - Locks live in the
awaitlibrary (Await.Capsule.Sync.With_mutex.with_lock);Capsule.Blocking_syncis deprecated. The low-level key/password API isCapsule.Prim(its*_unique/*_oncevariants are now[@mode …]instances).
Dynamically scoped variables. Stdlib.Dynamic gives fiber-aware,
parallel-safe dynamic binding: Dynamic.make (),
Dynamic.with_temporarily d v ~f:(fun () -> …), and Dynamic.get d
returning Null or This v. Values go in portable and are read
contended portable; unbound reads Null; there is no set.
Signatures and example: CHANGES-39-ox9.md.
Preemption (experimental, opt-in per fiber).
Effect.Deep.Preemptible.match_with/try_with, with ticks from
Domain.Tick.acquire ~interval_usec or the scoped
Domain.Tick.with_ — API and example in
CHANGES-39-ox9.md.
Effect handlers and modes. The 5.4 syntax is available —
match c () with v -> v | effect Poke, k -> Effect.Deep.continue k ()
— with OxCaml caveats:
- a function containing effect cases is forced nonportable and
stateful (you cannot pattern-match on effects inside a
portableorstatelessfunction), and variables used anywhere in such amatch(scrutinee or cases) must be global; Effect.performraises theunsafe_effectsalert: preferEffect.Safe.perform h e, whereh : Effect.Handler.t @ localis handed to the computation byEffect.Deep.Safe.match_with/try_with(or silence with[@@@alert "-unsafe_effects"]);- in a file preprocessed by a ppx,
effectpatterns currently fail ("migration error: effect patterns is not supported before OCaml 5.02") — keep handlers in un-preprocessed files or useEffect.Deep.match_with.
11. Borrowing
borrow_ e is a prefix expression form that cooperates with the
uniqueness analysis. It is valid in exactly three positions —
anywhere else is a hard error ("The borrow_ operator must appear
directly in a valid borrowing context"):
f (borrow_ r) (* common: function argument *)
let y = borrow_ r in ... (* let-binding RHS *)
match borrow_ r with _ -> ... (* match scrutinee *)
Use it where a callee only reads/writes through a unique value
transiently and you want to keep the unique reference after the call.
A borrowed value is local + aliased, so the callee must accept its
argument @ local. Diagnostics: warning 216 use-during-borrowing
("This value is used while being borrowed."); error "This value is
used as unique here, but it is being borrowed." (a conflict between a
borrow and a unique use). See SKILL-MODES.md.
12. Implicit Kinds in Signatures and Structures
A floating [@@@implicit_kind: ...] attribute declares that specific
type-variable names default to a chosen kind, in signatures and in
structures:
module type S = sig
[@@@implicit_kind: ('elt : word)]
type 'elt collection (* 'elt defaults to kind word *)
val singleton : 'elt -> 'elt collection
end
Multiple names at once:
[@@@implicit_kind: ('a : immediate) * ('b : immediate)].
Implicit kinds can't be overridden by an explicit annotation on the
variable, are inherited by nested signatures (which may re-declare
them), don't propagate through include, and apply inside
constraint clauses. See SKILL-KINDS.md.
13. Miscellaneous Extensions
Labeled tuples
let point = ~x:10, ~y:20 (* create *)
type point = x:int * y:int (* type *)
let ~x, ~y = point (* destructure *)
let get_x (p : x:int * y:int) = (* partial match needs a type
annotation *)
let ~x, .. = p in x
val dimensions : image -> width:int * height:int
Immutable arrays
let arr : string iarray = [: "a"; "b"; "c" :] (* : instead of | *)
let first = Iarray.get arr 0 (* Stdlib.Iarray *)
(* [| |] literals and patterns are disambiguated by expected type
(iarray / floatarray) *)
let arr3 : int iarray = [| 1; 2; 3 |]
(* Covariant - allows safe subtyping *)
let arr2 : obj iarray = (arr : sub_obj iarray :> obj iarray)
a.:(0)works only withStdlib_stable.IarrayLabelsopen — the( .:() )operator is not inStdlib.IarrayorStdlib_stable.Iarray.IarrayLabelsalso keeps the*_localvariants.Stdlib.Iarrayhasequal,compare,find_index,find_mapi, which the narrowerStdlib_stable.Iarrayshim lacks — bewareopen Stdlib_stableshadowingIarray.
Include functor — instead of module T = struct … end,
include T, include Comparable.Make(T):
module M = struct
type t = ...
[@@deriving compare, sexp]
include functor Comparable.Make
end
Let mutable — restrictions: cannot escape scope, no closure capture, single variable only.
let triangle n =
let mutable total = 0 in (* mutable local variable - no allocation *)
for i = 1 to n do total <- total + i done;
total
Polymorphic parameters
let create (f : 'a. 'a field -> 'a) = { a = f A; b = f B }
val create : ('a. 'a field -> 'a) -> t
Module strengthening — write S with M instead of
sig type t = M.t end.
Debugging Tips
- Mode errors: check if you're trying to return local data globally. Kind errors: ensure type parameters have correct layout annotations.
- Mangled symbols:
ocamlfilt(installed with the compiler) demangles flat and structured schemes — but only when a line is exactly one symbol:nm x.o | awk '{print $3}' | ocamlfilt - Native debugging: use the OxCaml LLDB build (
21.1.0+oxcaml1);b Module.fnbreakpoints and OCaml-syntax value printing work - Also available (details in CHANGES-39-ox9.md):
flags
-open-cmi,-functorize,-keywords,-i-variance,ocamldep -modules-only;Obj.hash_variant; idle-phase major GC (Xsmall_heap_limit); C APIcaml_region_begin/end,caml_add_blocks_to_heap,OXCAML_RUNTIME.
Library Dependencies
Stdlib(OCaml 5.4 base):Iarray,Pqueue,Pair,Repr,Dynamic(OxCaml),Effect.Safe(OxCaml),Modes, plusDynarray,Atomic.Locstdlib_stable:Float32/Float32_u,Int8/Int8_u,Int16/Int16_u,Int_u,Char_u,Or_null,Idx_imm/Idx_mut/Idx_atomic,Iarray(narrow compat shim),IarrayLabels(section 13)stdlib_upstream_compatible:Float_u,Int32_u,Int64_u,Nativeint_uthreads:Multicore(spawn,spawn_on,max_domains)base: Jane Street's standard library with comprehensive OxCaml mode support — consult SKILL-BASE.md for OxCaml-friendly functions. Mode/alloc instances via ppx_template ((List.map [@alloc stack]),(List.fold [@mode local global])),Modes(modal wrappers),Iarray, layout-polymorphicArray.get/set/lengthcore: extended library with I/O and system features — see SKILL-CORE.mdunboxed:Float_u,Int32_u,Int64_u,Nativeint_u,Float32_uwith full operator sets (open UnboxedgivesF64,F32,I32,I64,Iptr)portable,capsule:Portable.Atomic,Capsule, …parallel,await,concurrent: structured parallelism, locks, concurrency (opam packages;parallelrequires oxcaml-compiler ≥ 5.4.0-ox9)ppx_template: mode/kind polymorphism via code generation — see SKILL-TEMPLATES.md for mangling detailsocaml_simd.ppx(ppx_simd): SIMD shuffle/blend mask generationppx_portable:lazy%portable,let%portable recocaml_simd(opam package; requires oxcaml-compiler ≥ 5.4.0-ox9), with dune librariesocaml_simd.sse(moduleOcaml_simd_sse: 128-bit intrinsics; SSE on amd64, NEON or C stubs on arm64) andocaml_simd.avx(moduleOcaml_simd_avx: AVX/AVX2 intrinsics, 256-bit; C stubs on arm64). On arm64opam install ocaml_simdneeds theCPATHworkaround in SKILL-SIMD.md. Opening either module shadowsInt32,Int64(andStringforOcaml_simd_sse).
OCaml Progress Library
The progress library provides beautiful terminal progress bars, spinners, and multi-line displays for CLI applications.
Installation
Add to dune-project:
(depends
(progress (>= 0.4)))
Add to library/executable dune:
(libraries progress)
Core Concepts
| Type | Purpose |
|---|---|
Progress.Line.t | A single progress line (bar, spinner, text) |
Progress.Multi.t | Multiple lines combined |
Progress.Display.t | Active display that can be updated |
Progress.Reporter.t | Handle to report progress to a line |
Basic Progress Bar
open Progress
let process_items items =
let total = List.length items in
let bar = Line.(list [
spinner ();
bar ~style:`UTF8 ~width:(`Fixed 40) total;
count_to total;
]) in
with_reporter bar (fun report ->
List.iteri (fun i item ->
process_item item;
report (i + 1)
) items)
Output:
⠋ [████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 12/50
Progress Bar with Bytes and Speed
For downloads/uploads, use Int63 for large file sizes:
open Progress
module Int63 = Optint.Int63
let download_line ~total message =
let open Line.Using_int63 in
list [
rpad 20 (const message);
bytes;
const " ";
bytes_per_sec;
const " ";
bar ~style:`UTF8 ~width:(`Fixed 30) total;
const " ";
percentage_of total;
]
let download ~url ~size =
let bar = download_line ~total:(Int63.of_int size) "Downloading..." in
with_reporter bar (fun report ->
fetch_with_progress url (fun bytes_read ->
report (Int63.of_int bytes_read)))
Output:
Downloading... 12.5 MiB 2.3 MiB/s [██████████░░░░░░░░░░░░░░░░░░░░] 42%
Multi-Line Progress Display
For operations with multiple concurrent tasks:
open Progress
let multi_download files =
let lines = List.mapi (fun i file ->
download_line ~total:(file_size file) (file_name file)
) files in
let display = Multi.(list lines) in
with_reporters display (fun reporters ->
(* Each reporter corresponds to one line *)
List.iter2 (fun reporter file ->
download_file file (fun n -> reporter n)
) reporters files)
Dynamic Line Addition
Add lines dynamically during execution:
open Progress
type t = {
display : ((unit -> unit) -> unit, unit) Display.t;
mutable line_count : int;
}
let init () =
let header = Line.(constf "🐫 Processing files...") in
let display = Display.start Multi.(line header) in
{ display; line_count = 0 }
let add_line t bar =
let reporter = Display.add_line t.display bar in
t.line_count <- t.line_count + 1;
reporter
let finalise t =
Display.finalise t.display
Custom Colors
Use hex colors for branded progress bars:
open Progress
(* Gradient color palette *)
let colors = [|
Color.hex "#1996f3"; (* Blue *)
Color.hex "#06aeed";
Color.hex "#10c6e6";
Color.hex "#27dade";
Color.hex "#3dead5";
Color.hex "#52f5cb"; (* Cyan *)
Color.hex "#66fcc2";
Color.hex "#7dffb6";
Color.hex "#92fda9"; (* Green *)
|]
let color_for_index i = colors.(i mod Array.length colors)
let colored_bar ~index ~total message =
let color = color_for_index index in
Line.(list [
rpad 20 (const message);
bar ~color ~style:`UTF8 total;
percentage_of total;
])
Spinners
For indeterminate operations:
open Progress
let with_spinner message f =
let line = Line.(list [spinner (); const (" " ^ message)]) in
with_reporter line (fun _report -> f ())
(* Usage *)
let () =
with_spinner "Connecting to server..." (fun () ->
connect_to_server ())
Integration with Eio
For async progress updates, use a stream to communicate between fibers:
open Progress
type t = {
stream : (unit -> unit) option Eio.Stream.t;
display : ((unit -> unit) -> unit, unit) Display.t;
}
type reporter = {
stream : (unit -> unit) option Eio.Stream.t;
reporter : int Reporter.t option;
}
(* Report progress from any fiber *)
let report r value =
match r.reporter with
| None -> ()
| Some reporter ->
Eio.Stream.add r.stream
(Some (fun () -> Reporter.report reporter value))
(* Process stream updates in display fiber *)
let rec process_stream ~sw stream =
Eio.Switch.check sw;
match Eio.Stream.take stream with
| Some f -> f (); process_stream ~sw stream
| None -> ()
let init ~sw =
let stream = Eio.Stream.create max_int in
let header = Line.(const "Processing...") in
let display = Display.start Multi.(line header) in
Eio.Fiber.fork ~sw (fun () -> process_stream ~sw stream);
{ stream; display }
let finalise t =
Eio.Stream.add t.stream None;
Display.finalise t.display
Line Components Reference
| Component | Description |
|---|---|
bar ~style total | Progress bar (styles: UTF8, ASCII) |
spinner () | Animated spinner |
count_to total | "n/total" counter |
percentage_of total | "42%" percentage |
const s | Static string |
constf fmt | Formatted static string |
elapsed () | Elapsed time |
eta total | Estimated time remaining |
bytes | Byte count (auto-scales to KiB, MiB, etc.) |
bytes_per_sec | Transfer speed |
rpad n line | Right-pad to n characters |
lpad n line | Left-pad to n characters |
spacer n | Fixed-width space |
list lines | Combine multiple components |
(++) | Infix combine: a ++ b |
Bar Styles
(* UTF-8 style (default, looks best) *)
Line.bar ~style:`UTF8 total
(* Output: [████████░░░░░░░░] *)
(* ASCII style (for limited terminals) *)
Line.bar ~style:`ASCII total
(* Output: [########........] *)
(* Custom width *)
Line.bar ~style:`UTF8 ~width:(`Fixed 50) total
Line.bar ~style:`UTF8 ~width:(`Expand) total (* fill available space *)
Complete CLI Example
open Cmdliner
open Progress
let download_files files =
let total_files = List.length files in
let header = Line.(constf "📦 Downloading %d files" total_files) in
let display = Display.start Multi.(line header) in
List.iteri (fun i file ->
let size = Int63.of_int (file_size file) in
let color = color_for_index i in
let bar = Line.Using_int63.(list [
rpad 25 (const (file_name file));
bytes;
bar ~color ~style:`UTF8 ~width:(`Fixed 30) size;
percentage_of size;
]) in
let reporter = Display.add_line display bar in
download_file file (fun bytes ->
Reporter.report reporter (Int63.of_int bytes));
Reporter.finalise reporter
) files;
Display.finalise display;
Fmt.pr "✓ Downloaded %d files@." total_files
let cmd =
let info = Cmd.info "download" ~doc:"Download files with progress" in
Cmd.v info Term.(const download_files $ files_arg)
Tips
- Use
Int63for bytes - Regularintoverflows at 2GB on 32-bit systems - Fork display updates - With Eio, run display in separate fiber
- Finalise reporters - Always call
Reporter.finalisewhen done - Check terminal width - Use
(Expand)` for responsive bars - Provide fallback - Disable progress when stdout isn't a TTY:
let with_progress ~enabled bar f =
if enabled && Unix.isatty Unix.stdout then
with_reporter bar f
else
f (fun _ -> ())
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 accounts.
A user is identified by an email address, which is unique within a
workspace. *)
type t
(** The type for users. *)
val create : name:string -> email:string -> t
(** [create ~name ~email] is a new user called [name] with address [email]. *)
val name : t -> string
(** [name u] is the display name of [u]. *)
val pp : t Fmt.t
(** [pp ppf u] formats [u] on [ppf]. *)
Documentation style: written in the voice of a POSIX manual page. Load the
doc-style skill before writing any of it. In short, a function's doc opens
[f x y] is ..., every doc comment is full sentences ending in a full stop, no
colon or em dash joins clauses, and nothing describes the implementation.
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 errorsLog.warn- Potential issuesLog.info- InformationalLog.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/ # GitHub Actions
├── .gitlab-ci.yml # GitLab CI
└── .tangled/workflows/ # Tangled CI
dune-project
(lang dune 3.21)
(name project_name)
(source (tangled handle/project_name)) ; or (github user/repo)
(license ISC)
(authors "Name <email>")
(generate_opam_files true)
(license ISC)
(authors "Name <email@example.com>")
(maintainers "Name <email@example.com>")
(source (tangled user.domain/project_name))
(package
(name project_name)
(synopsis "Short description")
(description "Longer description")
(depends
(ocaml (>= 5.2))
(alcotest (and :with-test (>= 1.7.0)))))
Source options:
(source (tangled handle/repo))- Tangled hosting (default for monopam)(source (github user/repo))- GitHub hosting(source (gitlab user/repo))- GitLab hosting
Note: Don't add (version ...) - added at release time.
Tangled Source Syntax
For projects hosted on tangled.org, use the succinct source stanza:
(source (tangled user.domain/project-name))
Examples:
(source (tangled anil.recoil.org/ocaml-brotli))(source (tangled user.example.org/my-library))
Tangled CI Configuration
For projects hosted on tangled.org, create .tangled/workflows/build.yml:
when:
- event: ["push", "pull_request"]
branch: ["main"]
engine: nixery
dependencies:
nixpkgs:
- shell
- stdenv
- findutils
- binutils
- libunwind
- ncurses
- opam
- git
- gawk
- gnupatch
- gnum4
- gnumake
- gnutar
- gnused
- gnugrep
- diffutils
- gzip
- bzip2
- gcc
- ocaml
- pkg-config
steps:
- name: opam
command: |
opam init --disable-sandboxing -a -y
- name: repo
command: |
opam repo add aoah https://tangled.org/anil.recoil.org/aoah-opam-repo.git
- name: deps
command: |
opam install . --confirm-level=unsafe-yes --deps-only
- name: build
command: |
opam exec -- dune build
- name: test
command: |
opam install . --confirm-level=unsafe-yes --deps-only --with-test
opam exec -- dune runtest --verbose
Tangled Workflow Syntax
| Field | Description |
|---|---|
when | Trigger conditions: event (push/pull_request) and branch |
engine | Build engine, use nixery for Nix-based builds |
dependencies.nixpkgs | List of Nix packages to include |
environment | Global or per-step environment variables |
steps | Build steps with name and command |
Per-step environment variables:
steps:
- name: test
environment:
MY_VAR: value
command: |
echo $MY_VAR
Templates
See templates/ directory for:
dune-project.templatedune-root.templateci-github.ymlci-gitlab.ymlci-tangled.ymlgitignoreocamlformatLICENSE-ISC.mdLICENSE-MIT.mdREADME.template.md
OCaml Result Patterns
OCaml 5.x provides Result.Syntax for monadic chaining and Result.get_ok/Result.get_error for extraction.
Result.Syntax
Use open Result.Syntax to get let* and let+ bindings:
open Result.Syntax
let process request =
let* req = validate request in
let* auth = authenticate req in
let* _ = authorize auth in
execute req
DO NOT define local let ( let* ) = Result.bind. Use open Result.Syntax instead.
Extracting Values
| Function | Behavior on Error |
|---|---|
Result.get_ok r | Raises Invalid_argument |
Result.get_error r | Raises Invalid_argument |
Result.value r ~default | Returns default |
Use Result.get_ok only when failure is a programming error:
(* Startup/config - crash on failure is intentional *)
let config = Result.get_ok (Config.load ())
(* Test setup - failure means test bug *)
let client = Result.get_ok (Tls.Config.client ~authenticator ())
Custom get_ok
Only define custom get_ok when you need different exception behavior:
(* Raises domain-specific Protocol_error instead of Invalid_argument *)
let get_ok = function
| Ok x -> x
| Error e -> raise (Protocol_error e)
If you just want Invalid_argument, use Result.get_ok directly.
OCaml Project Review
A review in two phases. The interfaces are judged first, on their own, as a user of the library sees them. Only then are the implementations read, one module at a time, by a dedicated subagent each.
Never merge the phases. Reading an implementation before judging its interface is how a bad interface gets rationalised.
Phase 1: Interfaces
What to read
Read only these files.
dune-project- every
dune - every
.mli - every
.mld *.opamif present
Do not open a .ml in this phase. A module with no .mli is itself a
finding. Note the module, record what dune says about it, and move on.
Build the map
From the dune files alone, record:
- Every library and executable, its
public_name, and itslibraries. - Which modules are
(modules ...)of which stanza, and which are private. - Whether libraries are
wrappedand what the wrapper module re-exports. (flags ...), disabled warnings,preprocessstanzas.- Dependency direction between the project's own libraries, and any cycle pressure or layering violation.
State the map back as a short dependency listing before reviewing anything.
Judge each interface
For every .mli, check the following.
Shape
- Does the module do one thing? A module that would need two synopsis sentences is two modules.
- Is there a central
type t, and is it abstract? Exposed records that carry invariants are a finding. - Are the values ordered sensibly, with constructors first, then accessors, then predicates and comparisons, then converters and printers?
- Are
pp,equalandcomparepresent where the type warrants them? - Are the generic names gone?
Util,Helpers,CommonandMiscare findings.
API quality
- Unlabelled booleans and unlabelled same-typed adjacent arguments.
find_*returningoptionandget_*returning a value directly, or the convention broken.- Error handling. Recoverable failure is a
result. An exception in a public signature must be documented and justified. - Values exported only because a test or a sibling module needs them. These
belong behind a private module or an
_intfsplit. - Leaked internals. Types from a dependency in the signature that the caller should not have to depend on.
Documentation
- Judge every doc comment against the
doc-styleskill. That skill is the standard, so load it before reviewing prose. - Missing synopsis, missing value docs,
[f x y] isviolations, colons and em dashes, prose about implementation, banned words.
Deliverable
Produce an interface report with, in order:
- The library and module map.
- Findings, grouped by module, each as
file:lineplus one sentence. - A restructuring plan, if one is warranted. Say which modules split, merge,
move library, or gain an
.mli, and what the API break costs. - A redocumentation plan, if one is warranted. List the files whose
documentation is to be rewritten under
doc-style.
Present this and stop. Restructuring is the user's call. Do not edit an interface, and do not start Phase 2, until the user has responded.
Phase 2: Implementations
Once the user has accepted or amended the plan, review the implementations.
Dispatch
One subagent per implementation module. Group only trivially small modules, never more than three per subagent, and never modules from different libraries.
Launch subagents in parallel, in a single message, up to six at a time. Wait for a batch to return before launching the next.
Give each subagent the module's .ml, its .mli, and the Phase 1 findings
for that module. Use this prompt. The comment rules are spelled out in it
rather than delegated, because a subagent may not have this plugin's skills
available.
Review the implementation of <module> in <path>.ml against its interface in
<path>.mli. Read both files in full, plus any module it calls that you need
in order to judge a finding.
Report only defects you can point at. For each one give file:line, one
sentence of what is wrong, and one sentence of evidence. Do not edit any
file. Do not report style preferences that ocamlformat settles.
Look for, in this order:
1. Logic errors. Wrong base case, off-by-one, a partial match that will
raise, an ignored result, an error path that loses information, a
comparison that disagrees with equal, integer overflow, resource leaked on
an exception path.
2. Dead code. Values never used inside the module and not in the .mli.
Unreachable branches. Parameters never consulted. Types with no inhabitant
constructed. Say for each whether it is safe to delete.
3. Redundancy. Two functions that compute the same thing. A hand-written loop
that is a Stdlib or List function. A reimplementation of something already
in this project's own libraries, which you should check for by name.
4. Optimisation. Quadratic behaviour on a path that takes user-sized input.
Repeated work that could be hoisted. String concatenation in a loop where
a Buffer belongs. An avoidable allocation on a hot path. Say what input
size makes it matter, and skip it if none does.
5. Comments. Any comment inside the implementation that the code already
says, which is to be deleted. Section banners and commented-out code, also
deleted. Any doc comment in the .ml when an .mli exists, since the
documentation belongs in the interface. A comment survives only if it
cites a spec, states an invariant a reader cannot check locally, explains
a deliberate workaround, or justifies an unsafe operation.
6. Interface drift. Behaviour that contradicts what the .mli documents.
Rank your findings by severity, most severe first. If a category is clean,
say so in one line rather than inventing a finding.
Aggregate
When every batch has returned:
- Drop duplicates and anything a subagent could not support with evidence.
- Add the cross-module findings no single subagent could see. The same helper written in three modules. A layering violation. A type converted back and forth across a boundary.
- Rank everything by severity. Correctness first, then dead code, then redundancy, then optimisation, then comments.
- Present the ranked list with
file:line. Apply fixes only when the user asks, and apply them in that order.
Rules
- Phase 1 reads no
.ml. Phase 2 starts only after the user responds. - Every finding cites
file:line. - Subagents review and report. They never edit.
- An optimisation finding without a stated input size is noise. Drop it.
- Do not report anything
ocamlformatordune fmtalready handles. - Warnings that a
dunestanza disables are findings in themselves. - A proposed change that breaks the public API is labelled as such, with the callers it affects.
RFC Integration for OCaml Projects
When to Use This Skill
Invoke this skill when:
- User mentions implementing an RFC
- Adding RFC citations to documentation
- Fetching RFC specifications
- Validating code against RFC requirements
- Discussing internet protocol standards
RFC Fetching and Storage
Fetching RFCs
Always fetch RFCs in plain text format from:
https://datatracker.ietf.org/doc/html/rfcXXXX.txt
Important: Use .txt extension, not .html.
Storage Location
Save RFC files to spec/ directory in project root:
spec/rfc6265.txt
spec/rfc3492.txt
Create spec/ directory if it doesn't exist.
OCamldoc RFC Citation Format
Basic RFC Link
{{:https://datatracker.ietf.org/doc/html/rfcXXXX}RFC XXXX}
Section-Specific Links
{{:https://datatracker.ietf.org/doc/html/rfcXXXX#section-N.M}RFC XXXX Section N.M}
Common Section References
#section-N- Main numbered section#section-N.M- Subsection#appendix-X- Appendix (A, B, C, etc.)
Documentation Patterns
Citations are the one case where a doc comment carries a reference rather than
behaviour. Everything else follows the doc-style skill, which you should load
before writing the prose around a citation.
Module-Level Documentation
(** Punycode encoding for internationalised domain names.
Punycode represents Unicode labels in the ASCII subset permitted in host
names. This module implements
{{:https://datatracker.ietf.org/doc/html/rfc3492}RFC 3492}.
{2 References}
{ul
{- {{:https://datatracker.ietf.org/doc/html/rfc3492}RFC 3492} - Punycode}
{- {{:https://datatracker.ietf.org/doc/html/rfc5891}RFC 5891} - IDNA}} *)
Function-Level Documentation
val adapt : delta:int -> numpoints:int -> firsttime:bool -> int
(** [adapt ~delta ~numpoints ~firsttime] is the new bias value.
Implements the bias adaptation algorithm from
{{:https://datatracker.ietf.org/doc/html/rfc3492#section-6.1}RFC 3492 Section 6.1}. *)
Type-Level Documentation
type error =
| Overflow of position
(** Arithmetic overflow. See
{{:https://datatracker.ietf.org/doc/html/rfc3492#section-6.4}
RFC 3492 Section 6.4}. *)
| Invalid_digit of position * char
(** Invalid Punycode digit. See
{{:https://datatracker.ietf.org/doc/html/rfc3492#section-5}
RFC 3492 Section 5}. *)
Constants and Parameters
val base : int
(** The base of the Punycode digit encoding. It is [36].
See {{:https://datatracker.ietf.org/doc/html/rfc3492#section-5}
RFC 3492 Section 5}. *)
Reading and Parsing RFCs
RFC Structure
- Header: RFC number, title, authors, date
- Table of Contents: Section numbers and titles
- Abstract: Brief summary
- Main Body: Numbered sections
- Appendices: Lettered sections
- References: Citations to other documents
Key Sections to Extract
- Introduction - Background and motivation
- Terminology - Key terms (MUST, SHOULD, MAY)
- Algorithm - Core specification
- Security Considerations - Security implications
Validation Workflow
- Read the RFC from
spec/directory - Extract key requirements (MUST, SHOULD, MAY)
- Read implementation code
- Check each requirement is implemented
- Verify error handling matches RFC
- Report gaps or inconsistencies
Best Practices
DO
- Always fetch and save RFC text files to
spec/ - Use section-specific links when possible
- Link error types to their RFC requirements
- Document RFC parameters and constants
- Keep citations consistent across related functions
DON'T
- Link to HTML versions of RFCs
- Assume RFC sections without checking
- Omit section numbers in citations
- Duplicate RFC text verbatim (summarize instead)
Handling RFC Updates
When an RFC obsoletes another:
(** Implements {{:https://datatracker.ietf.org/doc/html/rfc6265}RFC 6265}
which obsoletes {{:https://datatracker.ietf.org/doc/html/rfc2965}RFC 2965}. *)
Multiple RFC References
(** IDNA-compatible encoding combining
{{:https://datatracker.ietf.org/doc/html/rfc5891}RFC 5891} (IDNA Protocol)
with {{:https://datatracker.ietf.org/doc/html/rfc3492}RFC 3492} (Punycode). *)
OCaml Security Audit
Systematic security hardening through vulnerability research, defensive coding, and comprehensive testing.
Core Philosophy
- Study the attacks first: Research CVEs in equivalent C/Rust/Go/Python libraries before writing tests
- Assume hostile input: Every parser, decoder, and protocol handler receives adversarial data
- Fail explicitly: Reject malformed input early with clear errors, never silently corrupt
- Test the boundaries: Edge cases at min/max values, empty input, and overflow points
- Defense in depth: Multiple validation layers, even when one seems sufficient
Workflow
Phase 1: CVE Research
Before writing any tests, research known vulnerabilities in equivalent implementations.
1. Identify comparable libraries:
OCaml library → Research in
─────────────────────────────────────
PNG/image parser → libpng, image-rs, Pillow
TLS/crypto → OpenSSL, BoringSSL, rustls
HTTP parser → http-parser, hyper, httptools
JSON parser → json-c, serde_json, ujson
XML parser → libxml2, quick-xml, defusedxml
Archive (zip/tar) → libarchive, zip-rs, tarfile
DNS resolver → c-ares, trust-dns, dnspython
Compression → zlib, miniz, flate2
YAML parser → libyaml, serde_yaml, PyYAML
PDF parser → poppler, pdf-rs, PyPDF2
ASN.1/X.509 → OpenSSL, ring, pyasn1
2. Search for CVEs:
# Search NVD database
curl "https://services.nvd.nist.gov/rest/json/cves/2.0?keywordSearch=libpng+buffer+overflow" | jq '.vulnerabilities[].cve.descriptions[0].value'
# Search CVE Details
# https://www.cvedetails.com/vulnerability-search.php
# Search GitHub Security Advisories
gh api graphql -f query='{ securityAdvisories(first:10, ecosystem:PIP, keyword:"pillow") { nodes { summary description severity } } }'
# Check OSV database
curl "https://api.osv.dev/v1/query" -d '{"package": {"name": "pillow", "ecosystem": "PyPI"}}'
3. Document findings - track CVEs and map to tests. See references/vulnerability-classes.md.
Phase 2: Vulnerability Classes
For each vulnerability class, add targeted tests.
Integer Handling
(** Test integer overflow in length calculations.
CVE pattern: libpng, zlib, many image libraries *)
let test_length_overflow () =
let huge_width = Int.max_int in
let huge_height = 1 in
match Image.create ~width:huge_width ~height:huge_height with
| Error `Overflow -> ()
| Error _ -> Alcotest.fail "wrong error type"
| Ok _ -> Alcotest.fail "should reject overflow"
(** Test signed/unsigned confusion.
Signed length interpreted as huge unsigned value. *)
let test_negative_length () =
let data = Bytes.create 4 in
Bytes.set_int32_be data 0 (-1l); (* 0xFFFFFFFF *)
match Parser.read_with_length data with
| Error (`Invalid_length _) -> ()
| _ -> Alcotest.fail "should reject negative length"
Buffer Boundaries
(** Test out-of-bounds read.
Claimed length exceeds actual data. *)
let test_oob_read () =
let header = "\x00\x00\x00\x10" in (* Claims 16 bytes *)
let data = header ^ "short" in (* Only 5 bytes of payload *)
match Parser.decode data with
| Error (`Truncated _) -> ()
| Error _ -> Alcotest.fail "wrong error"
| Ok _ -> Alcotest.fail "should reject truncated data"
(** Test empty input handling. *)
let test_empty_input () =
match Parser.decode "" with
| Error _ -> () (* Any error is acceptable *)
| Ok _ -> Alcotest.fail "should reject empty input"
Denial of Service
(** Test resource exhaustion - deeply nested structures.
CVE pattern: ujson, many JSON parsers *)
let test_deep_nesting () =
let depth = 10000 in
let nested = String.concat "" (List.init depth (fun _ -> "[")) ^
String.concat "" (List.init depth (fun _ -> "]")) in
match Json.parse nested with
| Error (`Nesting_too_deep _) -> ()
| Error _ -> () (* Resource errors are acceptable *)
| Ok _ -> Alcotest.fail "should limit nesting depth"
(** Test exponential expansion (billion laughs).
CVE pattern: XML entity expansion *)
let test_entity_expansion () =
let malicious = "<!DOCTYPE x [<!ENTITY a \"aaa...(1000 chars)\">]><x>&a;&a;&a;...</x>" in
match Xml.parse malicious with
| Error _ -> ()
| Ok _ -> Alcotest.fail "should reject entity expansion"
Phase 3: Fuzz Testing
Add fuzz tests for all parsers and encoders. See the fuzz skill for patterns.
Priority targets:
- Binary protocol parsers (highest risk)
- Text format parsers (JSON, XML, config files)
- Cryptographic operations
- Compression/decompression
- Character encoding conversions
(** Fuzz test: parser must not crash on any input. *)
let test_decode_crash_safety buf =
let buf = truncate buf in
let _ = Parser.decode (to_bytes buf) in
()
(** Fuzz test: encoder output must be parseable. *)
let test_roundtrip buf =
let buf = truncate buf in
match Parser.decode (to_bytes buf) with
| Error _ -> ()
| Ok v ->
let encoded = Parser.encode v in
match Parser.decode encoded with
| Error _ -> fail "encoded data failed to parse"
| Ok v' -> if v <> v' then fail "roundtrip mismatch"
Phase 4: CVE Regression Tests
For each applicable CVE, write a targeted regression test.
(** CVE-2023-XXXX regression test.
Reference: https://nvd.nist.gov/vuln/detail/CVE-2023-XXXX
Integer overflow when calculating buffer size from untrusted
width/height values. *)
let test_cve_2023_xxxx () =
let malicious_input = Bytes.of_string "\xff\xff\xff\xff\x00\x00\x00\x01" in
match Image.decode malicious_input with
| Error _ -> ()
| Ok _ -> Alcotest.fail "CVE-2023-XXXX: should reject overflow"
Defensive Coding Patterns
Validate Early, Fail Fast
let decode buf =
(* Check minimum size before any parsing *)
if Bytes.length buf < header_size then
Error (`Truncated { expected = header_size; got = Bytes.length buf })
else
let length = Bytes.get_int32_be buf 0 |> Int32.to_int in
(* Validate length before allocating *)
if length < 0 then
Error (`Invalid_length length)
else if length > max_message_size then
Error (`Message_too_large { size = length; max = max_message_size })
else if Bytes.length buf < header_size + length then
Error (`Truncated { expected = header_size + length; got = Bytes.length buf })
else
parse_body buf length
Safe Integer Arithmetic (Hacker's Delight style)
Overflow detection without branches where possible, using bit manipulation.
(** Detect signed addition overflow (Hacker's Delight, 2-13).
Overflow iff both operands have same sign and result has different sign. *)
let add_overflow a b =
let sum = a + b in
(* (a ^ sum) & (b ^ sum) is negative iff overflow *)
(a lxor sum) land (b lxor sum) < 0
(** Detect signed multiplication overflow (Hacker's Delight, 2-13).
For non-negative operands: a * b overflows iff a > max_int / b *)
let mul_overflow a b =
if b = 0 then false
else if b = -1 then a = Int.min_int (* Special case: min_int * -1 *)
else if b > 0 then a > Int.max_int / b || a < Int.min_int / b
else (* b < -1 *) a > Int.min_int / b || a < Int.max_int / b
(** Safe addition with overflow check. *)
let safe_add a b =
if add_overflow a b then Error `Overflow
else Ok (a + b)
(** Safe multiplication with overflow check. *)
let safe_mul a b =
if mul_overflow a b then Error `Overflow
else Ok (a * b)
(** Unsigned comparison for signed integers (Hacker's Delight, 2-12).
Interprets both values as unsigned. *)
let unsigned_lt a b =
(a lxor Int.min_int) < (b lxor Int.min_int)
(** Check if value fits in n bits unsigned. *)
let fits_in_bits n v =
v >= 0 && v < (1 lsl n)
(** Use in size calculations. *)
let calculate_buffer_size ~width ~height ~bytes_per_pixel =
let open Result.Syntax in
let* row_size = safe_mul width bytes_per_pixel in
let* total = safe_mul row_size height in
if total > max_buffer_size then Error `Buffer_too_large
else Ok total
Safe Integer Narrowing
(** Safe conversion from int to int32. *)
let int_to_int32 n =
if n < Int32.(to_int min_int) || n > Int32.(to_int max_int) then
Error `Overflow
else
Ok (Int32.of_int n)
(** Safe conversion from int64 to int. *)
let int64_to_int n =
if n < Int64.of_int Int.min_int || n > Int64.of_int Int.max_int then
Error `Overflow
else
Ok (Int64.to_int n)
(** Convert length field to int, rejecting values that don't fit. *)
let length_field_to_int len_field =
let open Result.Syntax in
let* n = int64_to_int len_field in
if n < 0 then Error (`Invalid_length n)
else Ok n
Constant-Time Comparison
(** Constant-time string comparison for secrets.
Prevents timing side-channels when comparing MACs, tokens, etc. *)
let constant_time_equal a b =
let len_a = String.length a in
let len_b = String.length b in
let result = ref (len_a lxor len_b) in
for i = 0 to min len_a len_b - 1 do
result := !result lor (Char.code a.[i] lxor Char.code b.[i])
done;
!result = 0
Resource Limits
type limits = {
max_depth : int;
max_string_length : int;
max_array_length : int;
max_total_size : int;
}
let default_limits = {
max_depth = 100;
max_string_length = 10_000_000;
max_array_length = 100_000;
max_total_size = 100_000_000;
}
let parse ?(limits = default_limits) input =
parse_with_limits ~limits input
Security Checklist
Before releasing any parser, encoder, or protocol handler:
Input Validation
- Empty input rejected or handled correctly
- Minimum size checked before parsing
- Maximum size limits enforced
- Length fields validated before use
- Negative lengths rejected
Integer Safety
- Multiplication overflow checked in size calculations
- Addition overflow checked in offset calculations
- No signed/unsigned confusion in lengths
- Cast results checked when narrowing
Resource Limits
- Nesting depth limited
- Collection sizes limited
- Total memory usage bounded
- Recursion depth bounded
Fuzz Testing
- Crash-safety test with arbitrary bytes
- Roundtrip test for encode/decode pairs
- AFL campaign run for 24+ hours
- No crashes or hangs found
CVE Coverage
- CVEs in similar libraries researched
- Regression tests written for applicable CVEs
- Tests documented with CVE references
References
references/vulnerability-classes.md- Detailed patterns for each vulnerability class- fuzz skill - Comprehensive fuzz testing patterns
- ocaml-testing skill - Unit test organization
OCaml Testing
Test Directory Structure
Use test/ directory with:
test.ml- Main runner controlling initialization ordertest_x.ml- One file per modulex.mlbeing tested, exportssuite
lib/
├── foo.ml
└── bar.ml
test/
├── dune
├── test.ml # Main runner
├── test_foo.ml # suite : (string * unit Alcotest.test_case list) list
└── test_bar.ml
For single-module libraries, a single test_foo.ml as runner is acceptable.
Dune Configuration
(test
(name test)
(libraries mylib alcotest logs logs.fmt fmt.tty))
Main Runner Pattern (test.ml)
The main test.ml controls initialization order for side effects:
(* 1. Initialize RNG before any test module is loaded *)
let () = Crypto_rng_unix.use_default ()
(* 2. Set up logging *)
let () = Fmt_tty.setup_std_outputs ()
let () = Logs.set_reporter (Logs_fmt.reporter ())
let () = Logs.set_level (Some Logs.Debug)
(* 3. Run all test suites *)
let () = Alcotest.run "mylib" Test_foo.suite
For multiple modules:
let () = Crypto_rng_unix.use_default ()
let () = Alcotest.run "mylib" (Test_foo.suite @ Test_bar.suite)
Module Test File Pattern (test_x.ml)
Each module exports a suite value. Do not initialize RNG or run Alcotest here.
(** Tests for Foo module. *)
let test_basic () =
let result = Foo.process "input" in
Alcotest.(check string) "expected output" "output" result
let test_empty () =
let result = Foo.process "" in
Alcotest.(check string) "empty input" "" result
let suite =
[
( "process",
[
Alcotest.test_case "basic" `Quick test_basic;
Alcotest.test_case "empty" `Quick test_empty;
] );
]
Lazy State for Module-Level Values
If a test module needs RNG at load time, use lazy evaluation:
let key = lazy (Crypto_rng.generate 32)
let key () = Lazy.force key
let test_encrypt () =
let ciphertext = Foo.encrypt ~key:(key ()) plaintext in
...
This defers RNG use until tests actually run, after test.ml initializes the RNG.
Alcotest Patterns
Custom Testables
let result_testable ok_t =
Alcotest.result ok_t Alcotest.string
let my_type_testable =
Alcotest.testable My_type.pp My_type.equal
Common Checks
Alcotest.(check int) "count" 42 actual
Alcotest.(check string) "name" expected actual
Alcotest.(check bool) "flag" true actual
Alcotest.(check (list int)) "items" [1;2;3] actual
Alcotest.(check (option string)) "maybe" (Some "x") actual
Alcotest.(check (result int string)) "result" (Ok 42) actual
Testing Exceptions
let test_raises () =
Alcotest.check_raises "should fail" (Invalid_argument "bad")
(fun () -> Foo.parse "bad")
Initialization Order
Always initialize in test.ml before Alcotest.run:
- RNG -
Crypto_rng_unix.use_default ()orMirage_crypto_rng_unix.use_default () - Logging -
Logs.set_reporterandLogs.set_level - Other global state - Environment setup, temp directories
This ensures deterministic test ordering and proper side-effect sequencing.
Test Logging
Set up logging in tests using the standard Logs library:
let () = Fmt_tty.setup_std_outputs ()
let () = Logs.set_reporter (Logs_fmt.reporter ())
let () = Logs.set_level (Some Logs.Debug)
Default behaviour: Logs at Debug level. Alcotest captures output to a file by default, so verbose logging doesn't clutter the terminal. Output is shown only when tests fail.
Per-Source Overrides
For per-source control, set levels after the reporter:
let () = Logs.Src.set_level Conpool.src (Some Logs.Debug)
let () = Logs.Src.set_level Requests.src (Some Logs.Warning)
Why Default to Debug?
- Alcotest captures output: Verbose logs don't clutter terminal
- Shown on failure: When a test fails, you see all the debug info
- No re-running needed: Debug output is already captured
Core Philosophy
- Unit Tests First: Prioritize unit tests for individual modules and functions.
- 1:1 Test Coverage: Every module in
lib/should have a corresponding test module intest/. - Isolated Tests: Each test should be independent and not rely on external state.
- Clear Test Names: Test names should describe what they test, not how.
- Test Inclusion: All test suites must be included in the main test runner.
Naming Conventions
- Test suite names: lowercase, single words (e.g.,
"users","commands","process") - Test case names: lowercase with underscores, concise but descriptive (e.g.,
"basic","empty_input","parse_error")
Writing Good Tests
Function Coverage: Test all public functions exposed in .mli files, including success, error, and edge cases.
Test Data: Use helper functions to create test data:
let make_user ?(name = "test") ?(id = 1) () = User.v ~name ~id
Property-Based Testing: For complex logic, consider property-based testing with QCheck:
let test_roundtrip =
QCheck.Test.make ~count:1000
~name:"encode then decode is identity"
QCheck.string
(fun s -> Codec.decode (Codec.encode s) = s)
End-to-End Testing with Cram
Cram tests verify CLI executable behavior.
Use Cram Directories: Every Cram test should be a directory ending in .t (e.g., my_feature.t/).
Create Actual Test Files: Avoid embedding code within run.t using heredocs. Create real source files within the test directory.
test/
└── my_feature.t/
├── run.t # The cram test script
├── input.txt # Test input file
└── expected.json # Expected output
Running Tests
# Run all tests
dune test
# Run tests and watch for changes
dune test -w
# Run a specific test
dune exec test/test.exe -- test "suite_name"
# Run tests with coverage
dune test --instrument-with bisect_ppx
bisect-ppx-report summary
OCaml Tutorial Creation
When to Use This Skill
Invoke this skill when:
- Creating tutorials for OCaml libraries
- Working with .mld documentation format
- Setting up MDX for executable examples
- Discussing interactive documentation
Overview
Prose in .mld pages and in the doc comments a tutorial quotes follows the
doc-style skill. Load it before writing them. A tutorial may address the
reader and explain motivation, which reference documentation may not, but the
sentences are still complete and free of filler.
OCaml tutorials should:
- Introduce concepts gently
- Use executable code examples via MDX
- Progress from simple to complex
- Include practical patterns and use cases
File Structure
Required Components
- doc/ directory in project root
- tutorial.mld - Main tutorial content
- index.mld - Documentation index
- dune - Build rules
doc/dune Configuration
(mdx
(files tutorial.mld)
(libraries your_library_name))
(documentation
(package your_package_name)
(mld_files index tutorial))
dune-project Updates
Enable MDX:
(using mdx 0.4)
Add MDX as doc dependency:
(package
(name your_package)
(depends
...
(mdx :with-doc)
(odoc :with-doc)))
.mld Format
Document Structure
{0 Topic Name Tutorial}
Introduction text.
{1 Section Title}
Section content.
{2 Subsection Title}
Subsection content.
Executable Code Blocks
Use {@ocaml[...]} for executable examples:
{@ocaml[
# let x = 1 + 1;;
val x : int = 2
]}
- Lines starting with
#are input - Following lines are expected output
- MDX verifies output at build time
- Use
;;to terminate expressions
Non-Executable Code
Use {v ... v} for verbatim blocks:
{v
name: Alice
age: 30
v}
Cross-References
{!Library.function_name} - Function reference
{!Library.Module.type_name} - Type reference
{{!Library}API reference} - Link with custom text
Lists
{ul
{- Item one}
{- Item two}
}
{ol
{- First item}
{- Second item}
}
Formatting
{b bold text}
{i italic text}
Tutorial Content Guidelines
Structure
- Setup - How to load the library
- Basic Usage - Simplest examples
- Core Concepts - Main types and functions
- Common Patterns - Real-world usage
- Advanced Features - Complex functionality
- Error Handling - How errors work
- Summary - Quick reference
Setup Section
{1 Setup}
{@ocaml[
# #require "library_name";;
# open Library;;
]}
Best Practices
- Show output - Include expected output in examples
- Use consistent naming - Variables carry through examples
- Build complexity gradually - Each example builds on previous
- Explain the "why" - Not just syntax, but when to use features
- Reference documentation - Link to API docs
Verification
dune build @check # Verify syntax
dune build @doc # Build documentation
dune runtest # Run MDX tests (if configured)
Common Issues
Unresolved References
Use fully qualified names: {!Library.of_string} not {!of_string}
MDX Not Found
Enable in dune-project: (using mdx 0.4)
Output Mismatch
Run code manually, update expected output. Use <abstr> for abstract values.
Commands 5
Add RFC
This command fetches an IETF RFC specification and integrates it into the project.
Arguments
RFC number: $ARGUMENTS (required, e.g., "6265" for HTTP cookies)
Process
1. Fetch the RFC
Fetch from IETF in plain text format:
https://datatracker.ietf.org/doc/html/rfc<NUMBER>.txt
Important: Always use .txt extension, not .html.
2. Save to spec/ Directory
Create spec/ directory if it doesn't exist and save:
spec/rfc<NUMBER>.txt
3. Parse RFC Structure
Extract key information:
- RFC title and abstract
- Table of contents (sections)
- Key terminology definitions
- Related RFCs (obsoletes, updates, references)
4. Generate OCamldoc Citation Templates
Provide ready-to-use citations for:
Module-level:
(** RFC <NUMBER> <Title>.
This module implements <description> as specified in
{{:https://datatracker.ietf.org/doc/html/rfc<NUMBER>}RFC <NUMBER>}.
{2 References}
{ul
{- {{:https://datatracker.ietf.org/doc/html/rfc<NUMBER>}RFC <NUMBER>} - <Title>}} *)
Section-specific:
(** Implements {{:https://datatracker.ietf.org/doc/html/rfc<NUMBER>#section-N}RFC <NUMBER> Section N}. *)
5. Suggest Integration Points
Search the codebase for:
- Functions that might implement RFC sections
- Existing RFC references that could be improved
- Types that represent RFC concepts
Output
Provide:
- Confirmation of RFC download
- Summary of RFC contents (title, sections)
- OCamldoc citation templates, worded under the
doc-styleskill - Suggestions for where to add citations in existing code
Example Usage
/add-rfc 6265
/add-rfc 3492
Success Output
Fetched RFC 6265: HTTP State Management Mechanism
Saved to: spec/rfc6265.txt
RFC Summary:
Title: HTTP State Management Mechanism
Obsoletes: RFC 2965
Sections:
1. Introduction
2. Conventions
3. Overview
4. Server Requirements
5. User Agent Requirements
6. Implementation Considerations
7. Privacy Considerations
8. Security Considerations
OCamldoc Templates:
Module-level:
(** RFC 6265 HTTP State Management Mechanism.
This module implements HTTP cookie handling as specified in
{{:https://datatracker.ietf.org/doc/html/rfc6265}RFC 6265}. *)
Section references:
- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-4}RFC 6265 Section 4} - Server Requirements
- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5}RFC 6265 Section 5} - User Agent Requirements
- {{:https://datatracker.ietf.org/doc/html/rfc6265#section-5.2}RFC 6265 Section 5.2} - The Set-Cookie Header
Related RFCs you might also need:
- RFC 2616 - HTTP/1.1 (obsoleted by RFC 7230-7235)
- RFC 7230 - HTTP/1.1 Message Syntax and Routing
Initialize OCaml Project
This command creates a new OCaml project with all standard files and configuration.
Arguments
Project name: $ARGUMENTS (defaults to current directory name if not provided)
Configuration
Read user configuration from ~/.claude/ocaml-config.json. If it doesn't exist, prompt the user for:
- Author name
- Author email
- Preferred license (ISC, MIT, Apache-2.0)
- CI platform (github, tangled, gitlab)
- Git hosting (github.com/user, tangled.org/@user, gitlab.com/user)
- OCaml version minimum (default: 5.2.0)
Offer to save configuration to ~/.claude/ocaml-config.json for future use.
Files to Create
Essential Files
- dune-project - Build configuration with opam generation
- dune (root) - With
(data_only_dirs third_party) - .opam - Generated by dune (do not create manually)
- .ocamlformat - Code formatting (version 0.28.1)
- .gitignore - Standard OCaml ignores + third_party/
- LICENSE.md - Based on configured license
- README.md - Project documentation template
CI Configuration (based on ci_platform setting)
- github:
.github/workflows/build.yml - tangled:
.tangled/workflows/build.yml - gitlab:
.gitlab-ci.yml
Source Files
- lib/dune - Library stanza
- lib/.ml - Main module with license header
- lib/.mli - Interface with documentation, written under the
doc-styleskill, which you should invoke before writing any doc comment
Test Files
- test/dune - Test configuration
- test/test_.ml - Basic test skeleton with Alcotest
Workflow
- Check if directory is empty or confirm overwrite
- Read or prompt for configuration
- Determine project name from argument or directory
- Create all files using templates from the ocaml-project-setup skill
- Run
dune build @checkto verify setup - Report success and suggest next steps
Template Variables
Replace these in templates:
{{PROJECT_NAME}}- Project name (snake_case){{PROJECT_NAME_KEBAB}}- Project name (kebab-case){{AUTHOR_NAME}}- From config{{AUTHOR_EMAIL}}- From config{{YEAR}}- Current year{{LICENSE}}- License identifier{{OCAML_VERSION}}- Minimum OCaml version{{GIT_URL}}- Full git URL based on hosting config{{SOURCE_STANZA}}- dune source stanza based on hosting:- tangled:
(source (tangled handle/{{PROJECT_NAME_KEBAB}})) - github:
(source (github user/{{PROJECT_NAME_KEBAB}})) - gitlab:
(source (gitlab user/{{PROJECT_NAME_KEBAB}}))
- tangled:
Example Usage
/init-ocaml my-library
/init-ocaml
Success Output
Created OCaml project: my-library
Files created:
- dune-project
- dune
- .ocamlformat
- .gitignore
- LICENSE.md
- README.md
- .github/workflows/build.yml
- lib/dune
- lib/my_library.ml
- lib/my_library.mli
- test/dune
- test/test_my_library.ml
Next steps:
1. Run `opam install . --deps-only` to install dependencies
2. Run `dune build` to build the project
3. Run `dune runtest` to run tests
OCaml NPM Setup
This command sets up the npm publishing workflow for OCaml projects compiled to JavaScript/WASM.
Arguments
None - operates on the current directory.
Prerequisites
- Existing OCaml project with dune
- js_of_ocaml or wasm_of_ocaml dependencies configured
- Git repository initialized
Two-Branch Workflow
main branch - OCaml source code, dune build files, opam packages
npm branch - Built JavaScript/WASM assets, package.json, README for npm
Process
1. Analyze Project
Determine:
- Project name from dune-project
- Existing JS build targets
- Whether to support JS, WASM, or both
2. Create/Update Dune Build Rules
Add or update lib/js/dune (or appropriate location):
(library
(name <project>_js)
(public_name <project>-js)
(libraries <project> brr)
(modes byte)
(modules <project>_js))
(executable
(name <project>_js_main)
(libraries <project>_js)
(js_of_ocaml)
(modes js wasm)
(modules <project>_js_main))
; Friendly filenames
(rule
(targets <project>.js)
(deps <project>_js_main.bc.js)
(action (copy %{deps} %{targets})))
(rule
(targets <project>.wasm.js)
(deps <project>_js_main.bc.wasm.js)
(action (copy %{deps} %{targets})))
; Install rules
(install
(package <project>-js)
(section share)
(files
<project>.js
<project>.wasm.js
(glob_files_rec (<project>_js_main.bc.wasm.assets/* with_prefix <project>_js_main.bc.wasm.assets))))
3. Update dune-project
Add -js package if not present:
(package
(name <project>-js)
(synopsis "Browser library via js_of_ocaml/wasm_of_ocaml")
(depends
(ocaml (>= 5.1.0))
(<project> (= :version))
(js_of_ocaml (>= 5.0))
(js_of_ocaml-ppx (>= 5.0))
(wasm_of_ocaml-compiler (>= 5.0))
(brr (>= 0.0.6))))
4. Create npm Branch
Create orphan branch with:
package.jsonREADME.md(browser-focused)LICENSErelease.sh.gitignore
5. Generate release.sh Script
#!/bin/bash
# Release script for npm package
set -e
INSTALL_DIR="_build/install/default/share/<project>-js"
# ... copy JS, WASM loader, and assets
Files Created
On main branch:
lib/js/dune(or updates existing)- Updates to
dune-project
On npm branch (new orphan):
package.jsonREADME.mdLICENSErelease.sh.gitignore
Example Usage
/ocaml-npm
Success Output
Set up npm publishing workflow for: my-library
Main branch updates:
- Created lib/js/dune with JS/WASM build rules
- Updated dune-project with my-library-js package
Created npm branch with:
- package.json (name: my-library-jsoo)
- README.md (browser usage documentation)
- LICENSE
- release.sh (copies built assets)
- .gitignore
Workflow:
1. Develop on main branch
2. Build: opam exec -- dune build @install
3. Switch to npm: git checkout npm
4. Copy assets: ./release.sh
5. Publish: npm publish
Current branch: main
To switch to npm branch: git checkout npm
Port to Dune
This command migrates an OCaml project from ocamlbuild/topkg to dune.
Arguments
None - operates on the current directory.
Prerequisites
The command expects to find ocamlbuild artifacts:
_tags- ocamlbuild compilation flags*.mllibfiles - module lists for librariespkg/pkg.ml- topkg package description (optional)pkg/META- findlib metadata (optional)opam- package dependencies
Migration Process
1. Analyze Existing Build
Read and parse:
_tags- Extract package dependencies, compiler flags, thread usage*.mllib- Identify libraries and their modulespkg/pkg.ml- Find optional libraries and conditionspkg/META- Get public library namesopam- Current dependencies
2. Create dune-project
(lang dune 3.20)
(name <package-name>)
(generate_opam_files true)
; ... rest from existing opam metadata
3. Create Library dune Files
For each library identified 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 Special Cases
Warning suppression (if needed):
(flags (:standard -w -27))
Toplevel init files (excluded from library):
(library
(name lib_name)
(modules lib_module)
(libraries deps))
(install
(package pkg)
(section lib)
(files lib_top_init.ml))
5. Create Test dune Files
(test
(name test_name)
(libraries lib_name alcotest))
6. Update opam File
- Rename
opamto<package>.opam - Remove ocamlbuild/topkg dependencies
- Add dune dependency
- Update build commands
7. Cleanup
List files to delete (don't delete automatically):
_tags.merlinpkg/pkg.mlpkg/META*.mllibfiles*.itargetfiles
Mapping Reference
| ocamlbuild | dune |
|---|---|
_tags: package(foo) | (libraries foo) |
_tags: thread | (libraries threads) |
foo.mllib | (library (name foo)) |
pkg/pkg.ml: Pkg.mllib ~cond:x | (library ... (optional)) |
pkg/META | Auto-generated by dune |
Workflow
- Search for ocamlbuild artifacts
- Parse each file to understand project structure
- Create dune-project at root
- Create dune files for each directory with sources
- Update opam file
- Run
dune build @checkto verify - List cleanup actions for user to confirm
Example Usage
/port-to-dune
Success Output
Analyzed ocamlbuild project structure:
- Found 3 libraries: logs, logs_fmt, logs_browser
- Found 2 optional libraries: logs_fmt, logs_browser
- Found test executable: test_logs
Created dune files:
- dune-project
- src/dune
- src/fmt/dune
- src/browser/dune
- test/dune
Updated:
- logs.opam (renamed from opam, updated build commands)
Files to delete manually:
- _tags
- pkg/pkg.ml
- pkg/META
- src/logs.mllib
- src/logs_fmt.mllib
- src/logs_browser.mllib
Run `dune build` to verify the migration.
Tidy OCaml Code
This command analyzes and refactors OCaml code to make it more idiomatic, maintainable, and concise.
Arguments
Optional file or directory path: $ARGUMENTS (defaults to current directory)
Before You Start
Invoke the doc-style skill. Comments and documentation are part of tidying,
and that skill is the standard for both.
Analysis Categories
1. Option and Result Patterns
Look for:
- Verbose match expressions that could use combinators
- Nested Option/Result handling without let*/let+
- Direct pattern matching where
Option.map,Option.bind, etc. would be clearer
Transform:
(* Before *)
match get_value () with
| Some x -> Some (x + 1)
| None -> None
(* After *)
Option.map (fun x -> x + 1) (get_value ())
2. Monadic Syntax
Look for:
- Deeply nested match expressions on Result/Option
- Manual error propagation chains
Transform:
(* Before *)
match fetch_user id with
| Ok user ->
(match fetch_perms user with
| Ok perms -> Ok (user, perms)
| Error e -> Error e)
| Error e -> Error e
(* After *)
let open Result.Syntax in
let* user = fetch_user id in
let+ perms = fetch_perms user in
(user, perms)
3. Pattern Matching vs Conditionals
Look for:
- Nested if/then/else chains
- Boolean condition checking that could be pattern matching
Transform:
(* Before *)
if x > 0 then
if x < 10 then "small"
else "large"
else "negative"
(* After *)
match x with
| x when x < 0 -> "negative"
| x when x < 10 -> "small"
| _ -> "large"
4. Code Duplication
Look for:
- Repeated error message patterns
- Similar function implementations
- Copy-pasted code blocks
Suggest:
- Helper functions
- Parameterized abstractions
- Shared error constructors
5. Module Hygiene
Look for:
- Generic module names (Util, Helpers, Common)
- Exposed record types without abstract
type t - Missing pretty-printers for main types
- Unlabeled boolean parameters
6. Comments and Documentation
Look for:
- Comments inside an implementation that restate the code
- Section banners and commented-out code
- Doc comments in an
.mlthat has an.mli - Doc comments that describe the implementation rather than the behaviour
- Function docs that do not open
[f x y] is ... - Colons and em dashes joining clauses, and filler such as
This function,Note that,simply,helper for
Transform: delete the first three outright. Rewrite the rest under the
doc-style skill.
7. Modern OCaml Patterns
Suggest:
- Labeled arguments for clarity
- Local opens for syntax extensions
- Explicit type annotations on public interfaces
Workflow
- If a specific file is given, analyze that file
- Otherwise, find all
.mland.mlifiles - Analyze each file for improvement opportunities
- Prioritize by impact:
- Code duplication (highest)
- Verbose monadic code
- Module structure issues
- Nested conditionals
- Present findings with before/after examples
- Apply changes with user confirmation
Output Format
Analysis of lib/parser.ml:
1. OPTION COMBINATORS (3 occurrences)
Line 45: Replace match with Option.map
Line 89: Replace match with Option.bind
Line 123: Replace match with Option.value
2. MONADIC SYNTAX (1 occurrence)
Lines 156-178: Use let*/let+ for cleaner Result chaining
Before:
[code snippet]
After:
[refactored snippet]
3. CODE DUPLICATION (2 occurrences)
Lines 34, 67: Duplicate error construction
Suggestion: Create helper function `parse_error`
Apply changes? [y/n/select]
Example Usage
/tidy
/tidy lib/parser.ml
/tidy src/
Success Output
Analyzed 12 OCaml files in lib/
Improvements found:
- 8 Option/Result patterns to simplify
- 3 monadic chains to use let*/let+
- 2 code duplication instances
- 1 module naming issue
Applied 13 changes:
- lib/parser.ml: 5 changes
- lib/types.ml: 3 changes
- lib/utils.ml: 5 changes (renamed to lib/string_ext.ml)
Reduced total lines: 847 -> 762 (-10%)
Suggestions not applied (require manual review):
- Consider abstracting User.t type (lib/user.ml:12)
- Add pp function to Config module (lib/config.ml)
Sponsors
Details
- Marketplace
- avsm/ocaml-claude-marketplace
- Source
- plugins/ocaml-dev
- Author
- Anil Madhavapeddy
- Category
- Development