OCaml Onboarding: 深入解析 Dune 构建系统

背景

OCaml 生态系统的入门门槛长期以来被部分开发者视为挑战。尽管 OCaml 语言本身强大且类型系统严谨，但对于新加入的开发者（Camleers）而言，从环境配置到项目构建的初始阶段往往缺乏直观的指引。

本文档旨在解决这一痛点，作为一系列新手引导文章的延续，重点聚焦于 OCaml 项目构建的核心工具链——Dune。虽然前文《Opam 103: 使用 opam 引导新项目》已经详细阐述了如何使用 opam 进行包管理和项目结构规划，但许多开发者在接触实际代码时，往往对底层的构建机制感到陌生。

Dune 是 OCaml 生态系统中事实标准的构建系统。它取代了早期复杂的 Makefile 或 OMake 方案，提供了声明式、高性能且易于理解的构建体验。理解 Dune 的工作机制，是任何开发者在 OCaml 领域实现高效生产力的关键一步。本文将以一个名为 helloer 的最小化示例项目为基础，拆解 Dune 的核心组件及其工作原理。

核心内容

1. 项目元数据与构建规范文件

在 Dune 驱动的项目中，根目录下的配置文件是构建流程的入口。

dune-project 文件

这是每个 Dune 项目的必备文件，位于项目根目录。它充当项目的元数据入口，告诉 Dune 项目的结构、版本以及与其他工具（如 opam）的交互方式。

• 核心作用：定义项目元数据，包括 Dune 语言版本、项目 URL、许可证、文档配置以及自动生成 .opam 文件的规则。
• 关键约束：第一行必须是 (lang dune X.Y)，其中 X.Y 是版本号（例如 3.15）。该行不得包含注释或额外空白，它决定了 Dune 识别哪些特性和语法。
• 示例内容：

  (lang dune 3.15)
  (package (name helloer))
  (cram enable)
  

  注：cram enable 启用了集成测试功能。

dune 文件

这是具体的构建规范文件，通常每个子目录对应一个 dune 文件，描述该目录下代码的编译规则。在扁平结构的示例项目中，该文件位于根目录。

• 核心作用：声明如何编译 OCaml 代码，定义库、可执行文件和测试目标。
• 示例内容：

  (library
    (name helloer_lib)
    (modules helloer_lib)
  )
  (executable
    (public_name helloer)
    (name helloer)
    (libraries cmdliner helloer_lib)
    (modules helloer)
  )
  (test
    (name test)
    (libraries alcotest helloer_lib)
    (modules test)
  )
  

2. 关键构建块（Stanzas）详解

在 Dune 中，Stanza 指的是配置块，用于声明要构建的工件类型（如库、可执行文件、测试等）。以下是三种核心 Stanza 的解析：

Library Stanza（库声明）

用于将一组模块编译为可复用的包。

• 配置项：
  • name：库的名称（如 helloer_lib）。
  • modules：参与编译的模块列表。
• 逻辑说明：
  • 默认情况下，每个 .ml 文件定义一个同名模块。因此，modules helloer_lib 意味着 Dune 会寻找 helloer_lib.ml。
  • 注意：仅列出希望作为公共 API 暴露给其他部分或外部代码的模块。未列出的模块将被视为内部实现细节。

Executable Stanza（可执行文件声明）

用于将代码打包为可运行的二进制文件。

• 配置项：
  • name：内部构建名称（如 helloer）。
  • public_name：对外发布的名称，用于 dune install 或 opam 安装后的命令名。
  • libraries：依赖的外部库（如 cmdliner 用于 CLI 解析）和内部库（如 helloer_lib）。
  • modules：构成该可执行文件的源文件模块。
• 逻辑说明：public_name 确保了安装后用户可以直接通过命令名调用该程序，而无需关心内部构建路径。

Test Stanza（测试声明）

用于定义测试目标。

• 配置项：
  • name：测试目标名称。
  • libraries：测试所需的库，通常包括测试框架（如 alcotest）和被测试的内部库。
  • modules：测试代码所在的模块。
• 逻辑说明：
  • 声明测试后，它会自动注册到 runtest 别名规则中。
  • 执行 dune runtest 或 dune test 时，Dune 会自动编译并运行这些测试。

3. 构建与运行流程

完成配置后，开发者可以使用 Dune 命令行工具进行构建。

• 构建命令：dune build @all

  • @all 是一个别名，代表所有可构建的目标（包括库、可执行文件、测试、文档等）。这是执行完整构建以确保所有代码均能编译的标准做法。
  • 也可以自定义别名，如 @doc 或 @runtest。

• 构建产物结构： 执行构建后，项目根目录会生成 _build 目录，其结构如下：

  .
  ├── _build
  │   ├── default
  │   │   ├── helloer.exe      # 可执行文件
  │   │   ├── helloer_lib.cmxs # 编译后的库文件
  │   │   ├── test.exe         # 测试可执行文件
  │   │   └── [...]
  │   ├── install
  │   └── log
  ├── dune
  ├── dune-project
  ├── helloer_lib.ml
  ├── helloer.ml
  ├── helloer.opam
  └── test.ml
  

  • _build/default：存放编译后的中间文件和最终二进制文件。
  • _build/install：存放安装后的文件结构。
  • 源代码文件保持原样，构建过程是非侵入式的。

关键要点

• Dune 是 OCaml 的标准构建系统：它简化了项目设置、编译和依赖管理，是进入 OCaml 生态系统的必备技能。
• dune-project 定义元数据：必须包含 (lang dune X.Y) 以指定语法版本，并配置项目基本信息及与 opam 的集成。
• dune 文件定义构建逻辑：通过 Stanza（块）声明库、可执行文件和测试。
  • library 块定义可复用模块，仅列出公共 API 模块。
  • executable 块定义二进制文件，需指定 public_name 以便安装和调用。
  • test 块定义测试，集成到 dune runtest 流程中。
• 模块与文件名匹配：OCaml 模块名默认与 .ml 文件名一致，Dune 据此自动关联源文件。
• 构建产物隔离：所有编译产物位于 _build 目录，保持源代码目录整洁，支持增量构建和并行编译。
• 推荐学习路径：虽然可以使用 dune init 自动生成项目结构，但建议先手动编写 dune 文件以深入理解其底层机制，从而能更自信地调试和定制构建流程。

意义与影响

对于 OCaml