Dune
Last Updated: 27, July 2020 at 09:35:49
Overview
Dune is a build tool that has been widely adopted in the OCaml world - it plays nicely with lots of other tools like opam and mdx. The documentation is very thorough - but do checkout the key concepts to get a high-level overview of how dune works and how to get started building your OCaml project.
Welcome to dune's documentation! - dune documentation
Key Concepts
Compositional Builds
Dune builds projects in a modular way generally based on file structure. This is somewhat different to say how npm would build Javascript projects more or less only based on the package.json at the root of the project. Looking at Typical Project Layout the compositionality is portrayed by the dune files in each directory. Each part is doing something different (building tests, the library, the unix version of the library etc.).
Declarative
Unlike say Makefiles, dune is declarative. You tell it what you want and dune handles the nitty-gritty details but provides escape-hatches and a lot of customisability in your dune file to build complex projects.
This allows dune to be a great build tool no matter what your project size or complexity is.
Build Types
There tend to be three main types of builds that will suffice for most projects: executables, libraries and tests. Each has its own stanza reference. The executable stanza will by default build a binary that you can run in the _build/default folder. Libraries are units of reusable code for other projects to benefit from packaged up under a module.
Typical Project Layout
The following file structure is taken from ocaml-yaml and has been trimmed to show only the relevant dune-related parts and still be readable.
.
|-- CHANGES.md
|-- LICENSE.md
|-- README.md
|-- dune
|-- dune-project
|-- fuzz
| |-- dune
| `-- fuzz.ml
|-- lib
| |-- dune
| |-- stream.ml
| |-- types.ml
| |-- yaml.ml
| `-- yaml.mli
|-- tests
| |-- dune
| |-- test.ml
| |-- test_emit.ml
| |-- test_parse.ml
| `-- yaml
|-- unix
| |-- dune
| |-- yaml_unix.ml
| `-- yaml_unix.mli
`-- yaml.opam
In the Wild
Dune is used in a lot of OCaml projects thanks to its flexibility, integration with opam and lightweightness. Below are just a few projects using dune:
Related Workflows
Starter
- Starting a new Project - Build the scaffolding for your solution to a problem
Environment
- Checking Code Coverage - Use the Bisect tool to discover how much of your code is being tested
Coding
- Running OCaml in your Browser - Use js_of_ocaml to run OCaml code in the browser and interoperate with Javascript libraries from OCaml
- Compiling for Y on X - Compile code to run on different computer architectures
Testing
- Adding Unit Tests to your Project - Write tests to check the functionality of your code using Alcotest
Publishing
- Publishing a Package on Opam - Share your libraries or applications with the community
- Documenting your Project - Write maintainable and useful documentation for your library
Misc
- Using Tools Written in OCaml - Run tools built with OCaml
- Incorporating non-OCaml Code into your Project - Add C code to your OCaml project
- Fixing Bugs in 3rd Party Packages - Track down and fix bugs in libraries that you use
- Profiling your Project - Profile the memory and performance of your application