OCaml 平台路线图

本文档概述了 OCaml 平台的三年路线图（2024 年至 2026 年）。它定义了我们希望在未来几年实现的开发者体验。

OCaml 平台是一组工具，每个工具都旨在促进不同的开发工作流程。每个工具都有其独特的愿景和路线图。本文档的目的是不是要绘制这些路线图，而是为它们提供一个总体的指导方针，确保各个工具的路线图与 OCaml 开发体验的更大愿景相一致。

本文档的核心目标是阐明我们，OCaml 平台团队和更广泛的 OCaml 社区，旨在提供的开发者体验。在这样做的过程中，我们努力保持以用户为中心的视角，只有在必要时才深入技术细节。

本路线图的结构以 OCaml 平台旨在支持的开发工作流程为基础。每个工作流程都定义为一系列我们希望在未来三年内实现的陈述。这种格式的设计具有双重目的：首先，让读者清楚地了解他们在未来使用 OCaml 时可以预期的开发者体验；其次，让平台维护者和贡献者能够轻松地将路线图转换为针对不同平台工具的可操作任务或项目。

愿景和目标

我们对 OCaml 平台的总体愿景是为每种开发工作流程创造无缝的体验。

我们设想一个开发环境，其中每个开发任务都得到支持并最大程度地优化，并且在尽可能的情况下，不需要任何人工干预。我们在 指导原则中为工具制定了这些具体指南。

在本节中，我们确定了未来三年的三个主要关注领域。

(G1) Dune 是 OCaml 平台的前端

遵循 (P5)（工具独立，但统一），Dune 成为用户使用 OCaml 进行开发所需的唯一工具。

Dune 已经与大多数平台工具集成以创造一致的体验，但它缺少两个值得注意的集成，这些集成迫使用户同时使用多个工具：包管理和包发布。它应该与 opam 和 opam-publish/dune-release 集成以提供这些工作流程。

它还应该与任何新孵化的平台工具集成作为实验性工具。

由于 Dune 是 OCaml 平台的前端，因此它成为用户使用 OCaml 入门的唯一工具。使用 OCaml 入门的推荐方法是通过系统包管理器安装 Dune。安装 OCaml 变得像 apt install dune 一样简单。

遵循 (P2)（体验是多功能的，但无缝的），Dune 应该为所有支持的平台开发工作流程提供一个最小且直观的 CLI。特别是，它应该协调它们并在需要时自动安装它们。最终，Dune 用户应该不需要知道他们正在使用一个单独的工具。

(G2) 支持新的开发工作流程

遵循 (P2)（体验是多功能的，但无缝的），未来三年的首要任务是填补当前开发体验中的空白。

目标是孵化新的平台工具来支持最重要的缺失开发工作流程。根据 OCaml 生态系统现状和社区反馈，我们计划为以下工作流程孵化工具（或在适当的情况下扩展现有工具）

• 代码风格检查：使用一组预定义的代码风格检查规则检查 OCaml 项目。
• 基准测试：执行 OCaml 项目的基准测试以测试性能改进/回归。
• 形式验证：在常规测试工作流程中运行形式规范验证。
• 生成安装程序：生成特定于平台的安装程序，例如 .msi 或 .deb，以轻松分发 OCaml 项目。
• 代码审计：使用已知安全漏洞数据库审计 OCaml 项目。

(G3) 使现有工作流程成熟

最后，我们将继续使支持的开发工作流程成熟。用户反馈表明，当前的开发体验可以改进。一些常见的请求示例包括能够从 Dune CLI 运行单个测试；能够将依赖于其他包的依赖项合并到项目中而无需合并那些依赖项；Merlin 查询以执行代码重构，例如重命名值和函数；等等。

工作流程部分将更详细地介绍我们计划在未来几年改进的工作流程，但我们重点介绍三个非常重要的工作流程

• 安装 OCaml：安装完整的 OCaml 开发环境无疑是采用 OCaml 的重要障碍。随着 Dune 成为平台的前端，安装 OCaml 应该像 apt install dune 或 winget install dune 一样简单。
• 调试：OCaml 编译器提供了使用 ocamldebug 进行调试的支持。为了使调试 OCaml 程序更容易；但是，用户应该能够从 Dune 或他们的编辑器运行调试器。OCaml 平台应该提供一个 调试器适配器协议 实现以支持编辑器集成，Dune 应该与 ocamldebug 集成以提供 Dune 项目的直观调试工作流程。
• 生成文档：OCaml 包的高质量文档的可用性仍然是 OCaml 开发人员报告的主要痛点之一，也是该语言采用的主要障碍。最近改善这种情况的努力包括 OCaml.org 上新的中央包文档。但是，可用的文档生成工具不适合创建用户手册。为了激励开发人员为他们的包编写高质量的文档，一个优先事项是改进工具以支持这种用例。

工作流程

为了清楚起见，我们将工作流程分为以下用例

• 入门：安装 OCaml 开发环境
• 开发：创建和开发软件
• 检查：检查和理解代码
• 编辑：使用代码编辑器开发 OCaml
• 维护：维护项目并确保代码质量
• 分享：与世界分享软件

入门

OCaml 平台提供了多种使用 OCaml 入门的方法，具体取决于用例和用户类型。

(W1) 从命令行

要从命令行驱动您的工作流程，您可以安装 dune

# On Ubuntu
sudo apt install dune
# On macOS
brew install dune
# On Windows
winget install dune

Dune 二进制文件在所有 Tiers-1 支持的环境中都打包好了。它也可以作为二进制文件下载到其他环境中

bash < <(curl -sL https://ocaml.org.cn/setup.sh)

安装完成后，您可以下载 OCaml 项目并使用以下命令运行它

git clone [email protected]:ocaml/foo.git
cd foo
dune exec my-cli

或者运行

dune fmt # To format your code
dune doc # To generate your documentation
dune test # To run the project's tests

在幕后，Dune 将 OCaml 平台工具用作库或通过驱动它们的二进制文件来使用它们。但是，这对用户来说是隐藏的。如果 Dune 需要一个工具来执行特定的开发工作流程，它会为用户安装它。

(W2) 从编辑器

上述设置适合那些熟悉命令行并希望保持控制的人。其他用户，例如语言爱好者 (U4)，他们想要快速入门，可以在他们最喜欢的编辑器上打开并安装 OCaml 扩展

code --install-extension ocaml.vscode-ocaml # On VSCode
M-x package-install ocaml-mode # On Emacs
Plug 'ocaml/ocaml.vim' # On Vim

编辑器的扩展将在用户系统上安装 Dune（如果尚未安装），Dune 本身会按需安装编辑器扩展所需的每个工具，以提供开箱即用的完整编辑体验，遵循设计原则 (P1) 和 (P5)。

所有编辑器的扩展都与 OCaml LSP 服务器交互。除了 LSP 协议提供的全部功能（包括语法高亮、错误报告、语法补全等）之外，扩展还提供特定于 OCaml 平台的功能，例如，推广差异、运行 Dune 可执行文件等。

(W3) 使用开发容器

开发容器是与编辑器集成的 Docker 容器，尤其是可以与 VSCode 的开发容器扩展和 GitHub Codespaces 无缝使用。

这是一个特别适合教师 (U5) 的工作流程，他们必须为学生提供完全不同的环境支持。

为了允许用户使用开发容器设置项目，项目本身必须将 devcontainers 配置文件提交到存储库。像 VSCode 这样的编辑器就可以获取配置，并通过 Docker 容器提供所有编辑器的功能。

OCaml 平台提供包含完整开发环境的官方开发容器。

开发

(W4) 构建项目

检查完现有项目后，能够构建项目是开发人员首先需要做的事情。

一个唯一的命令

在 OCaml 中，只需运行以下唯一命令即可

dune build

这会自动安装项目的所有依赖项，这些依赖项是通过读取项目的元数据（在 dune-project 或 dune-workspace 文件中找到）推断出来的。它会安装包依赖项和库，并设置所需的编译器版本。它还会根据用户的系统输出相应的包管理器命令来安装系统依赖项，从而提示用户如何安装系统依赖项。Dune 的缓存是在多个项目之间共享的，因此设置可以非常快。

一个用于设置和构建项目的单一命令，适用于所有使用 Dune 的 OCaml 项目，这使得新贡献者更容易快速加入并提高生产力，无论是小型项目还是大型项目，都符合 (P1) 和 (P3)。

Dune 还可以与非 Dune 包作为依赖项一起使用。它通过读取 .opam 文件并将其嵌入其构建图中来计算缺失的元数据和构建指令。

在开发过程中，支持两种工作流程来构建项目：在命令行中和通过编辑器。两种工作流程都是兼容的，可以一起使用。

监视模式

Dune 提供了一种监视模式，任何文件修改都会触发重新构建。由于 Dune 的缓存，只有受更改影响的部分才会被重新编译。

监视模式明确显示了它运行的目标（@runtest 或 @install），开发人员可以并行重新运行测试或调用其他目标（通常，可以在监视模式下运行构建，并在另一个终端中以监视模式运行测试）。

编辑器集成

与直接通过编辑器安装 Dune 类似，也可以在不离开编辑器的情况下驱动 Dune。

编辑器通过专用的 UI 支持构建和运行项目。可以从编辑器中查看 Dune 报告的任何信息，例如列出项目范围的错误、跳转到报告的位置等。编辑器使用处于监视模式下的 Dune 实例，这意味着对文件的任何修改都会触发重新构建和对报告错误的更新。

所有这些对于用户来说都是透明的，他们只需要设置自己的编辑器。

在不同上下文中工作

Dune 可以使用不同的配置集来构建项目，这些配置集称为上下文。上下文包括有关所使用的 OCaml 编译器、编译标志、环境变量等信息。它具有足够的表达能力，可以通过提供要使用的源代码的 URL 来定义编译器版本，例如，用于在编译器的特定分支上进行测试。

用户可以为不同的目的定义多个上下文，例如测试、发布和基准测试。

上下文在 dune-workspace 文件中定义。要使用哪个上下文的选择是通过向构建命令传递一个参数来完成的，以避免任何全局状态。这提高了可重复性，并避免了跟踪当前使用的上下文，从而导致更简单的思维模型 (P3)。

(W5) 管理依赖项

依赖项的真相来源是提交到存储库中的元数据文件（即 dune-project 文件）。项目是使用从 dune-project 生成的锁文件构建的。

要更新项目的依赖项，用户可以直接编辑文件，运行 dune lock 并重新构建项目。这在监视模式下也很好用：Dune 检测到项目依赖项发生变化时，会重新生成锁文件，并执行一个包含先前状态和新状态之间差异的构建图。

此外，opam 存储库包含每个包中库的映射。这使 Dune 和其他 opam 客户端能够在当前工作区中没有可用库时向用户提供提示。通过查看包及其库的列表，Dune 能够建议安装特定包以使用库。

(W6) 供应商依赖项

对于库和应用程序开发人员 ((U1) 和 (U2))，在开发过程中，通常需要对项目的依赖项进行操作，无论是为了修复在开发过程中发现的错误，还是需要对项目及其依赖项进行更改。

Dune 提供了一种供应商依赖项的方法

dune vendor <dependency>

这会将依赖项的源代码从构建目录复制到项目的源代码树中。

供应商依赖项的行为与它们在构建目录中的行为相同，只是它们的源代码可以由用户修改 (P3)。通常，供应商依赖项不会与作为来自其他包的传递依赖项发生冲突：具有该依赖项的包将链接到供应商版本。

(W7) 生成项目

看看其他社区，项目生成对于新手开始项目来说是最有益的事情之一。

对于简单的项目，它向用户展示了 OCaml 项目所需的简单样板。

对于更复杂的项目，它允许用户从具有所有已编码约定和配置的工作应用程序开始。对于初学者来说，阅读代码库并对其进行扩展要容易得多，而不是必须学习创建任何东西所需的所有必要部分。

Dune 提供了一个 dune init 命令来生成项目。

它可以生成包含库、可执行文件和测试的简单项目 (R1、R4)。

它还可以从远程模板生成项目，例如，托管在 GitHub 存储库中 (P1)。

项目模板是可配置的，dune init 提供了一个向导来设置配置。例如，dune init 可以询问用户他们希望使用哪种许可证。

从模板生成项目后，dune init 允许用户通过生成新组件来扩展他们的项目。组件可以是通用的，例如库、测试，但也可以是模板特有的，例如 Web 应用程序中的身份验证模块。

(W8) 格式化代码

Dune 提供了一个 dune fmt 命令来格式化项目中的代码。

在幕后，它与不同的格式化程序集成，以格式化 OCaml 项目中的不同文件。Dune 的内部格式化程序用于 Dune 文件，OCamlFormat 用于 OCaml 文件，Refmt 用于 Reason 文件等。

用户无需配置格式化程序即可格式化他们的代码：有一些良好的默认设置，以惯用方式格式化代码 (P1)。

但是，这些工具是完全可配置的，用户 (U1 和 U2) 可以自定义他们想要如何格式化代码 (P1)。Dune 为此提供了一个节，在驱动各种工具时将其作为配置传递。

此外，代码格式化是向后兼容的 (P4)。要么工具本身是向后兼容的，并且它们知道如何使用特定版本的工具进行格式化，要么 Dune 本身会安装正确版本的工具以保持向后兼容性。

(W9) 代码 lint

虽然 OCaml 编译器提供了一些关于代码的断言，特别是由于静态类型系统，但它并不能防止所有错误和问题。

通常，编译器不会通知用户文件描述符从未关闭。

它也不会提供有关项目采用的约定的提示，以确保代码质量。例如，Dune 代码库鼓励开发人员为每种类型创建一个模块，而不是在一个模块中有多种类型。或者 OCaml LSP 代码库鼓励用户将模式匹配中最短的子句放在首位。

为此，Dune 通过与 OCaml 代码 lint 器的集成提供了 lint 功能。

Dune 还可以仅通过 dune lint 命令 (R1) 执行 lint 管道。

与格式化配置类似，lint 配置和配置文件可以在 dune-project 中指定。

Dune 在构建过程中将 lint 失败报告为警告，并且这些错误会报告给编辑器，这得益于 OCaml LSP 和 Dune RPC 的集成。

(W10) 打开 REPL

包含 REPL 的语言的优势之一是，您可以以非常交互的方式进行编程，并立即从解释器那里收到关于正在计算的值的反馈。这对于语言爱好者 (U4) 来说尤其有趣，他们希望在不创建文件的情况下尝试语言，并且重视解释器提供的额外信息。

可以使用以下命令打开具有良好 UX、历史记录、自动补全和行编辑功能的 REPL

dune repl

虽然打开包含所有公共模块的 REPL 是默认设置，但 Dune 为库用户提供了更多选项 (P1、P3)。它可以打开一个 REPL，对包含的模块有更多控制，例如，只包含指定的模块或所有模块，包括私有模块。它还可以包含不受其签名文件限制的模块。

最后，打开 REPL 与编辑器很好地集成。人们可以轻松地获得一个与当前打开的其中一个文件相对应的环境，并在那里执行一段代码进行测试。

(W11) 交叉编译

Dune 利用 OCaml 编译器的头等交叉编译支持来支持二进制文件的交叉编译。

可以将目标添加到 dune-workspace 文件中

(context
  (default
    (targets native windows android)))

这使得 Dune 为当前系统、Windows 和 Android 生成目标。

用户还可以使用 dune build -x <target> 为特定目标生成目标。

由于编译器对交叉编译的原生支持，Dune 中的交叉编译独立于依赖项使用的构建系统：如果用户依赖于使用不同构建系统的包，Dune 仍然能够为外部平台编译可执行文件。

Dune 在编译时原生支持动态或静态链接，包括在进行交叉编译时。

Dune 支持交叉编译到以下平台：Windows、macOS、iOS、Android。

(W12) 编译到 MirageOS

MirageOS 是一个库操作系统，它构建适用于各种云计算和移动平台的安全的、高性能的网络应用程序的微内核。

除了允许交叉编译到 Windows、macOS、iOS 和 Android 等原生平台之外，Dune 还支持 MirageOS 微内核作为交叉编译目标

dune build -x mirage

此工作流程不需要使用任何第三方 opam 存储库。

(W13) 编译到 JavaScript

OCaml 生态系统的一个重要特性是能够将 OCaml 代码编译成 Javascript。这目前是通过从字节码 (Js_of_ocaml) 编译或直接从 OCaml 源代码 (Melange) 编译来实现的。

这允许用户直接在 OCaml 中编写 JavaScript 应用程序。这包括动态部分，作为 Javascript 的替代，但也包括前端，例如，使用 Tyxml，它也可以从 FRP 中获益。最后，前端和后端的代码使用相同的语言，允许共享代码，并使值的通信更容易。

在 Dune 中将目标语言从原生代码更改为 Javascript 只需要在 dune 文件中添加一行

(executable
  ...
  (modes js melange))

(W14) 编译到 WebAssembly

对 WebAssembly 的编译以类似于 JavaScript 编译的方式支持：用户可以在他们的 dune 文件中添加 wasm 模式，以在其构建的一部分中生成 WebAssembly 编译的目标

(executable
  ...
  (modes wasm))

(W15) 插件可扩展性

遵循 (P6)（平台是凝聚的，但可扩展的），Dune 允许外部工具通过插件系统扩展其语言以添加新的构建规则。

这些插件不会违反 Dune 的可组合性原则。特别是，插件之间应该没有耦合，或者最多是松耦合。

此外，为了尊重（P5）（工具独立，但统一），这些插件可以独立于 Dune 使用。

Dune 插件系统背后的理念是，新的工具可能需要数年才能集成到 Dune 中。为了更好地适应工具的生命周期，Dune 插件系统允许在工具处于预孵化和孵化阶段时快速迭代，并保持松散的向后兼容性，直到工具进入活跃阶段并作为一等公民集成到 Dune 中。

(W16) 与其他构建系统集成

虽然 Dune 是 OCaml 项目的推荐选择，但开发人员可能出于各种原因选择或需要使用不同的构建系统。大型组织，如 Meta 或 Google，通常为了保持一致性和规模而强制使用特定系统（分别为 Buck2 和 Bazel）。独立开发人员也可能根据其独特需求（如 Nix 的可重复性功能）拥有偏好。

为了确保 OCaml 生态系统对所有这些用户来说始终可访问和可用，无论他们选择哪个构建系统，Dune 都提供支持将构建计划导出为机器可读格式。这使得第三方工具能够使用导出的构建计划并将其转换为其他构建系统的规范。

我们注意到，先前的讨论对于是否存在一个足够好的解决方案来导出 Dune 的构建计划没有达成一致。需要与 obazel 等转换工具的维护者以及其他构建系统的用户进行进一步的讨论和调查，以确定如何改进与这些平台的集成。

探索

(W17) 调试

使用 OCaml 进行调试可以通过命令行和编辑器完成。

要使用命令行调试，只需运行

dune debug

这会使用调试支持编译项目，并在终端中启动一个调试会话。

另一种调试程序的方法是通过编辑器。调试器和编辑器之间的通信使用 调试适配器协议 进行。

(W18) 基准测试

与创建测试套件的方式类似，OCaml 用户可以为其项目创建基准测试。Dune 为基准测试提供了头等支持。用户可以使用一个基准测试库，该库生成一个遵循特定格式的文件，该文件可以被工具（如 current-bench）解释。基准测试采用使用该库的普通 OCaml 文件的形式，并通过 bench 节添加到 Dune 中，其行为类似于 test 节

(bench
 (name ...)
 (libraries ...))

在 Dune 中添加基准测试后，用户可以运行 dune bench，这将运行所有基准测试以生成输出文件。在本地，它随后将启动一个基准测试仪表板，其中包含用户生成的不同的基准测试结果。

在将代码推送到存储库时，用户可以选择通过 GitHub 应用程序在存储库上启用基准测试。启用后，该应用程序将监听存储库上的拉取请求 (PR)，并运行基准测试。

然后，基准测试将通过 GitHub 拉取请求提供。

编辑

(W19) 代码导航

代码导航将常见的交互式开发工作流程分组，包括

• 显示类型签名和符号文档
• 跳转到类型、值或模块的定义
• 查找类型、值或模块的所有引用
• 从声明切换到定义
• 使用语义信息在文件内导航光标

代码导航发生在三个地方

• 在本地，在编辑器中，用户通常从文件到文件导航，可以获取值或模块的引用，跳转到定义等。
• 在线，当使用基于浏览器的编辑器时
• 在线，当使用 VCS 时，例如，当审查 GitHub 或 Gitlab PR 或浏览托管代码时
• 在线，当使用 OCaml Playground 时

本地编辑器代码导航由 OCaml LSP 服务器中所有适当 LSP 请求的实现支持。基于浏览器的编辑器由 OCaml VSCode 扩展的 Web 版本支持，该版本依赖于 Merlin 的 JavaScript 版本。OCaml Playground 同样使用 Merlin 的 JavaScript 版本来支持代码导航功能。

(W20) 代码重构

两个值得注意的代码重构任务包括

• 重命名一个值或模块及其所有引用
• 提取一个值或模块

OCaml 平台通过 Merlin 查询以及对 OCaml LSP 服务器中相关 LSP 请求和代码操作的支持来支持这些功能。

维护

(W21) 运行测试

Dune 提供了一个 dune test 命令，该命令运行在项目中定义的测试。测试使用 (test) 节定义。

Dune 拥有一个用户友好、直观的用户界面来运行测试。测试可以从命令行单独运行，Dune 提供了 shell 自动完成功能来探索 CLI 语法并发现给定上下文或目录中可用的测试。

测试运行器还与观察模式很好地集成，以支持测试驱动开发 (TDD) 工作流程。

编辑器也与 Dune 集成，以提供一个 UI 来探索和执行测试。通常，VSCode 扩展提供一个类似于官方 Python 扩展 的测试资源管理器。

此外，Dune 可以生成测试覆盖率报告：当运行测试时，代码会被检测以识别访问过的代码路径，并用于衡量覆盖率。

(W22) 正式验证

Gospel 是 OCaml 程序的行为规范语言。它为开发人员提供了一种非侵入式且易于使用的语法，用正式的契约来注释他们的模块接口，这些契约描述了类型不变式、可变性、函数前置条件和后置条件、效果、异常等等！

它的设计是为了提供一个与工具无关的前端，将形式化方法引入 OCaml 生态系统。

为了为用户提供一种正式验证其 OCaml 程序的方法，OCaml 平台提供了一个工具，该工具使用 Gospel 规范验证 OCaml 函数的实现。

当定义函数的正式规范时，dune test 会向用户报告任何正式验证失败，并通过扩展，这些失败会通过 LSP 服务器作为错误报告给编辑器。

(W23) 安全建议

OCaml 用于行业中，为关键基础设施组件提供动力。在这些情况下，安全性至关重要。

OCaml 平台提供了一个安全建议数据库（类似于 Rust 的建议数据库），针对发布在 opam-repository 上的 OCaml 包提交。

该数据库由一组安全专家维护，社区可以在发现或解决新的安全问题时做出贡献。

与 linting 工作流程类似，Dune 使用建议数据库来警告用户在构建项目时项目的安全问题。

dune audit 命令还可以根据项目锁文件与建议数据库的匹配结果生成安全审计报告。

安全警告和错误通过 OCaml LSP 和 Dune RPC 的集成报告给编辑器。

最后，OCaml 平台提供 CI 管道，这些管道会监视安全建议数据库，并在从项目锁文件中检测到新的安全问题时，向项目存储库打开 PR 或问题。

分享

(W24) 文本编程

文本编程是一种编程实践，它颠倒了代码和注释的优先级。默认情况下，编译时会忽略任何文本，代码必须放在特殊分隔符内。文本编程非常适合教学目的，因为它侧重于解释，但它也可以用作鼓励文档化大型代码库的一种方式。

在 OCaml 中，文本编程支持由 odoc 工具提供。odoc 通常用于生成文档，但它也可以执行文档中的代码块。

此行为是选择加入的，可以使用 Dune 节进行配置，例如

(documentation
  (execute_code_blocks true))

可以在上述节中提供其他选项，例如选择对哪些文件运行 odoc 或包含哪个库。

代码块执行支持 odoc 支持的每个文档文件，包括 .md、.mli 和 .mld 文件。

.mli 和 .mld 文件中嵌入代码块的语法支持指定执行嵌入代码生成的输出。这使我们能够将输出解释为更丰富的格式，例如表格、图像、图表等，然后可以由编辑器显示或由 odoc 适当地嵌入到 HTML 中。

Dune 允许我们运行（文本）程序并检查运行程序的输出是否与文件中预期的输出一致

dune test

如果实际输出与预期输出不匹配，Dune 会引发错误并提议进行差异。

odoc 还支持使用 JavaScript 顶层生成具有交互式代码块的 HTML 文档。

(W25) 生成文档

文档可以从源代码中存在的特殊注释以及专用文档文件（.mld 和 .md 文件）生成，例如通过运行

dune doc

Dune 驱动 odoc 以 HTML 格式生成文档，并在文档的开头打开一个浏览器标签（P3）。生成的文档包含项目依赖项的文档。

odoc 使用的标记足够表达，可以编写丰富的文档和手册。特别是，odoc 支持以下功能

• 源代码渲染，以便在阅读文档时检查函数的代码
• 全局导航，用于在整个 API 和独立文档页面之间导航。
• 搜索栏，用于搜索文档。
• 最常见的标记功能的特殊语法（例如表格、图像等）
• 支持独立文档页面的 Markdown
• 代码块可以生成丰富的输出（例如图像、图表等）和任意标记。

文档生成和浏览与代码编辑器很好地集成。用户可以快速从编辑器跳转到他们选择的模块的渲染文档。编辑器有助于编写文档，提供语法高亮、引用检查和对代码片段的通常检查。

(W26) 包发布

OCaml 包发布在 opam-repository 上。要发布一个包，用户可以创建一个 opam 文件，其中包含有关包的信息，例如其依赖项和 depexts，以及允许 Dune 或其他构建系统构建包的构建说明。

opam 文件还定义了包的源代码可以从哪里下载。使用 GitHub、GitLab 或其他 VSC 平台托管包含包源代码的 tarball 是常见的做法。

Dune 提供了一个 dune release 命令来发布包到 opam-repository。它自动执行创建 opam 文件、源代码 tarball、将 tarball 上传到 VCS 以及在 opam-repository 上打开 PR 的过程。

Dune 知道如何从 Dune 项目中合成 opam 文件，并可以生成一个包含源代码和元数据的压缩包，这些元数据是将软件包发布到 opam-repository 所必需的。生成的压缩包只包含 opam 所需的文件。

此工作流程与开发最佳实践相集成，并读取项目的变更日志以创建发布存档和 opam-repository 的 PR。

(W27) 生成安装程序

将应用程序分发给最终用户的一种常见方法是生成一个安装程序，其中包含应用程序、其所有依赖项以及安装二者的脚本。

安装文件因用户系统而异。基于 Debian 的 Linux 发行版具有 .deb 文件，Windows 具有 .msi 和 setup.exe 文件，而 macOS 具有 .app 文件。

OCaml 平台提供了一个工具，可以从 OCaml 项目生成安装程序，而 Dune 提供了一个用户友好的界面来生成它们。

例如，运行

dune build @installer-msi

会生成一个 .msi 安装程序，可以将其分发给 Windows 用户以安装项目的可执行文件。