OCaml Docker基础镜像文档

镜像概述与主要用途

OCaml Docker基础镜像是预安装opam包管理器及特定OCaml编译器版本的Docker镜像。该镜像主要用于OCaml生态的持续测试系统，同时也可作为OCaml项目的开发基础镜像（注：作为开发镜像使用时可能存在部分使用限制，详见注意事项）。

⚠️ 以下仓库已停止更新：ocaml/opam2、ocaml/opam2-staging、ocurrent/opam 和 ocaml/ocaml。如需获取最新镜像，请使用当前仓库 ocaml/opam。

镜像每周通过OCurrent 流水线自动更新，其构建日志可通过Web界面查看。

核心功能与特性

核心组件

• 预安装最新opam：包含最新版本的OCaml包管理器opam。
• 全局opam环境：预配置与镜像标签对应的OCaml编译器版本的全局opam switch。
• 本地opam仓库快照：内置镜像构建时的opam-repository本地快照。
• 默认用户opam：镜像默认以非root用户opam运行，UID/GID为1000。

关键特性

• 多架构支持：支持32位/64位系统及arm、x86、ppc等架构。
• 多发行版覆盖：包含Debian、Arch Linux、Ubuntu（含LTS版本）及Windows（MinGW-w64/MSVC）。
• OCaml配置选项：提供特殊配置的OCaml环境，如启用flambda优化或frame pointers。
• 自动更新：每周通过OCurrent流水线更新，确保依赖与编译器版本最新。

标签格式

镜像标签遵循特定命名规则，用于标识发行版、版本及OCaml配置。以下为详细说明：

完整标签格式

最详细的标签包含发行版版本与OCaml版本，格式为：
ocaml/opam:<distro>-<version>-ocaml-<ocaml-version>
例如：ocaml/opam:debian-10-ocaml-4.12

标签别名规则

• 发行版别名：基础发行版标签（如debian、ubuntu）自动指向该发行版的最新版本与最新OCaml编译器。
  示例：若最新Debian为11，最新OCaml为4.14，则ocaml/opam:debian等价于ocaml/opam:debian-11-ocaml-4.14。
• OCaml版本别名：OCaml主版本标签（如ocaml-4.11）指向该主版本的最新补丁版（如4.11.X）。
• 特殊配置标签：包含OCaml配置选项的标签格式为<distro>-ocaml-<version>-<option>，例如debian-ocaml-4.14-flambda（启用flambda）。

发行版特定标签规则

标签生成与查看

镜像标签通过ocaml-version和ocaml-dockerfile工具生成。所有标签可在Docker Hub查看。

镜像内容与权限说明

内置组件

• opam：最新稳定版opam包管理器。
• 全局opam switch：预配置与标签对应的OCaml编译器（如ocaml-base-compiler.4.14.1）。
• 本地opam-repository：镜像构建时的opam仓库快照，路径为/home/opam/opam-repository。
• 默认用户：opam（UID/GID 1000），镜像默认以此用户执行命令。

权限注意事项

由于默认用户为opam，在Dockerfile中操作文件时需注意权限：

• 复制文件：使用COPY --chown=opam <src> <dst>确保opam用户有权访问。
• 切换用户：如需root权限，可通过USER root切换，操作完成后建议切回opam。

使用场景与适用范围

主要适用场景

• OCaml持续测试：作为OCaml官方测试系统（如ocaml-ci、opam-repo-ci）的基础镜像。
• 开发环境：快速搭建标准化OCaml开发环境，避免本地环境配置差异。
• 自动化构建：在CI/CD流水线中用于编译、测试OCaml项目（如GitHub Actions、GitLab CI）。

使用方法

基本使用（docker run）

通过以下命令启动交互式容器：

# 使用最新Debian与OCaml
docker run -it ocaml/opam:debian

# 使用特定版本（如Debian 11 + OCaml 4.14）
docker run -it ocaml/opam:debian-11-ocaml-4.14

# 使用Windows MinGW环境（需Docker支持Windows容器）
docker run -it ocaml/opam:windows-mingw-2022

Dockerfile示例

以下为基于该镜像构建OCaml项目的Dockerfile示例：

# 基础镜像：最新Ubuntu LTS + OCaml
FROM ocaml/opam:ubuntu-lts

# 切换到root用户安装系统依赖
USER root
RUN apt-get update && apt-get install -y libssl-dev

# 切换回opam用户，复制项目文件（确保权限）
USER opam
WORKDIR /home/opam/my-project
COPY --chown=opam . .

# 安装依赖并构建项目
RUN opam install . --deps-only -y && dune build

在CI中使用特定镜像

为确保构建一致性，可通过镜像SHA256哈希指定具体版本（可在Docker Hub标签页获取）：

# GitLab CI示例
build:
  image: ocaml/opam@sha256:abc123...  # 替换为实际SHA256哈希
  script:
    - opam install . --deps-only
    - dune test

注意事项

旧仓库迁移

以下仓库已停止更新，请勿使用：

• ocaml/opam2、ocaml/opam2-staging
• ocurrent/opam、ocaml/ocaml

开发镜像使用提示

作为开发镜像时可能存在部分限制，建议：

• 遇到问题可在OCaml Discuss论坛提问。
• 提交bug或功能请求至docker-base-images issue tracker。

标签版本变更

• 发行版标签（如ubuntu）会随发行版更新自动指向新版本，若需固定环境，建议使用完整版本标签（如ubuntu-22.04-ocaml-4.14）。
• Windows镜像需Docker Desktop支持Windows容器，且仅在特定Docker版本中可用。