ocaml/rwo

Real World OCaml v2

镜像概述和主要用途

本项目是《Real World OCaml》第二版的源代码，目前仍处于开发阶段。原版由Yaron Minsky、Anil Madhavapeddy和Jason Hickey编写，修订版由Yaron Minsky和Anil Madhavapeddy主导，Ashish Agarwal、Jeremy Yallop、Frederic Bour和Sander Spies在工具链方面做出了重要贡献。在线开发版本可通过[***]

该项目用于构建《Real World OCaml》第二版的在线HTML网站，包含书籍内容、代码示例及相关构建和测试工具，支持代码片段的自动评估与插入。

核心功能和特性

仓库结构

• 多仓库协作：包含三个主要仓库
  • https://github.com/realworldocaml/scripts%EF%BC%9A%E6%8F%90%E4%BE%9B%60rwo%60 opam包，包含构建和依赖分析工具，需通过opam pin到v2分支
  • https://github.com/realworldocaml/examples%EF%BC%9A%E5%AD%98%E5%82%A8%E4%B9%A6%E7%B1%8D%E4%B8%AD%E7%9A%84%E4%BB%A3%E7%A0%81%E7%89%87%E6%AE%B5%EF%BC%8C%E4%BD%BF%E7%94%A8https://github.com/realworldocaml/mdx%E8%A7%A3%E6%9E%90%E5%99%A8%E8%AF%84%E4%BC%B0%EF%BC%8C%E5%B7%A5%E4%BD%9C%E5%88%86%E6%94%AF%E4%B8%BA%60master%60
  • https://github.com/realworldocaml/book%EF%BC%9A%E5%BD%93%E5%89%8D%E4%BB%93%E5%BA%93%EF%BC%8C%E6%95%B4%E5%90%88scripts%E5%92%8Cexamples%E7%94%9F%E6%88%90HTML%E7%BD%91%E7%AB%99

技术特性

• HTML生成：通过OCaml脚本将pandoc markdown格式的章节内容转换为HTML
• 代码片段管理：使用自定义<link>标签插入并评估代码示例
• 测试框架：支持代码示例的自动化测试，区分确定性和非确定性测试场景
• 版本依赖：所有代码和示例基于OCaml 4.07.1构建

使用场景和适用范围

• 书籍作者/贡献者：构建和测试在线书籍版本，验证代码示例正确性
• 读者：查看开发中的书籍内容，获取可运行的代码示例
• OCaml学习者：通过实际代码示例学习OCaml编程

详细使用方法和配置说明

前提条件

• 熟悉[***]
• 已安装OCaml 4.07.1环境

安装依赖

bash
# 固定rwo包（当前仓库根目录执行）
opam pin add rwo . -n
# 安装所有依赖
opam install rwo --deps-only

生成HTML

书籍内容分为两部分：

• 章节内容：使用https://pandoc.org/MANUAL.html#markdown-variants%E7%BC%96%E5%86%99
• 代码示例：可独立检出供读者构建

生成HTML命令：

bash
make

生成的HTML文件位于_build/default/static/目录，通过_build/default/static/index.html访问构建后的书籍。

测试代码示例

确定性测试

验证shell脚本和.ml文件的预期行为：

bash
make test

此命令在"确定性模式"下运行所有测试，适用于CI环境，会显示预期结果与实际结果的差异。

接受测试结果变更：

bash
make promote

非确定性测试

针对基准测试等非确定性示例：

bash
make test-all

接受非确定性测试结果变更：

bash
make promote