CircleCI便捷镜像 => Clojure

一个专注于持续集成的Clojure Docker镜像，专为在CircleCI上运行而构建。

![CircleCI构建状态]([] ![软件许可证]([] ![Docker拉取次数]([] ![CircleCI社区]([]

此镜像旨在替代原始的CircleCI Clojure镜像 circleci/clojure。

cimg/clojure 是由CircleCI创建的Docker镜像，专为持续集成构建设计。每个标签包含Clojure版本、JVM以及在CircleCI环境中成功完成构建所需的所有二进制文件和工具。

目录

• 快速开始
• 镜像工作原理
• 开发指南
• 贡献指南
• 其他资源
• 许可证

快速开始

此镜像可与CircleCI的 docker 执行器配合使用。例如：

yaml
jobs:
  build:
    docker:
      - image: cimg/clojure:1.10.3
    steps:
      - checkout
      - run: lein version

在上述示例中，CircleCI Clojure Docker镜像被用作主容器。具体来说，使用了标签 1.10.3，这意味着Clojure版本为1.10.3。现在你可以在此作业的步骤中使用Clojure。

镜像工作原理

此镜像包含通过 clj 安装的Clojure编程语言以及 Leiningen（Clojure构建工具）。这些Clojure镜像默认包含OpenJDK 17，同时正在开发支持OpenJDK 8（及可能更多版本）的替代版本。

Babashka（Clojure脚本工具）已预装。请注意，Babashka版本更新频繁，而CircleCI仅在 upstream 项目发布新版本时才更新Clojure镜像，因此预装的Babashka版本可能有时会落后于最新版本。

父标签与父标识

父标签提供了选择特定版本的能力。结合父标识，Clojure镜像现在支持选择OpenJDK版本，格式为 parentSlug-parentTag，例如 openjdk-8.0（表示OpenJDK 8.0）。

变体版本

变体镜像通常包含相同的基础软件，但有少量额外修改。

Node.js变体

Node.js变体与基础Clojure镜像相同，但额外安装了Node.js。可通过在现有 cimg/clojure 标签后添加 -node 来使用，例如：

yaml
jobs:
  build:
    docker:
      - image: cimg/clojure:1.10.3-node
    steps:
      - checkout
      - run: node --version

浏览器变体

浏览器变体包含基础Clojure镜像的所有内容，并通过apt预装了Node.js、Selenium及浏览器依赖。可通过在现有 cimg/clojure 标签后添加 -browser 来使用。此变体旨在与 CircleCI浏览器工具orb 配合使用，该orb可帮助你在构建中安装特定版本的Google Chrome和/或Firefox。镜像包含使用浏览器及其驱动所需的所有支持工具。

yaml
orbs:
  browser-tools: circleci/browser-tools@1.1
jobs:
  build:
    docker:
      - image: cimg/clojure:1.10.3-browsers
    steps:
      - browser-tools/install-browser-tools
      - checkout
      - run: |
          node --version
          google-chrome --version

标签方案

此镜像采用以下标签格式：

cimg/clojure:<clojure-version>[-openjdk-version][-variant]

• <clojure-version>：指定Clojure版本。可以是完整的SemVer点版本（如 1.10.1）或次要版本（如 1.10）。使用次要版本标签时，将自动指向Clojure团队发布的后续补丁更新。例如，标签 1.10 目前指向Clojure 1.10.1，当新版本发布后，将自动指向1.10.2。

• <openjdk-version>：指定OpenJDK版本。注意：默认标签 cimg/clojure:<clojure-version>[-variant] 将使用最新OpenJDK版本（如17.0）。

• [-variant]：可选的变体标签。例如，Node.js变体可表示为 cimg/clojure:1.10-node。

开发指南

可通过本仓库在本地构建和运行镜像。需满足以下要求：

• Linux（已测试Ubuntu）或macOS本地机器
• 新版Bash（v4+）
• 新版Docker Engine（v19.03+）

社区用户克隆（无仓库写入权限）

在GitHub上 Fork 此仓库。获取克隆URL后，需添加 --recurse-submodules 参数以拉取仓库中包含的Git子模块，命令如下：

bash
git clone --recurse-submodules <我的克隆URL>

如果已克隆但未拉取子模块，可运行 git submodule update --recursive 补拉。之后可选择将此仓库添加为上游仓库：

bash
git remote add upstream [***]

维护者克隆（有仓库写入权限）

使用以下命令克隆项目以拉取子模块：

bash
git clone --recurse-submodules ***:CircleCI-Public/cimg-clojure.git

生成Dockerfile

可使用 gen-dockerfiles.sh 脚本为特定Clojure版本生成Dockerfile。例如，要生成Clojure 1.10.3的Dockerfile，从仓库根目录运行：

bash
./shared/gen-dockerfiles.sh 1.10.3#1.10.3.1058

其中，1.10.3 是Clojure版本，1.10.3.1058 是版本参数（Clojure版本+构建号）。构建号可从 Clojure Linux安装说明 获取，即该页面示例中版本的最后部分。

生成的Dockerfile位于 ./1.10/<parent-tag>/Dockerfile，变体版本的Dockerfile位于 ./1.10/<parent-tag>/<variant>/Dockerfile。

要本地构建并测试镜像（以OpenJDK 8.0为例）：

bash
cd 1.10
docker build -t test/clojure:1.10.1-openjdk-8.0 .
docker run -it test/clojure:1.10.1-openjdk-8.0 bash

使用默认版本（最新）时，可运行：

bash
cd 1.10
docker build -t test/clojure:1.10.1 .
docker run -it test/clojure:1.10.1 bash

# 或显式指定OpenJDK 17.0
docker build -t test/clojure:1.10.1-openjdk-17.0 .
docker run -it test/clojure:1.10.1-openjdk-17.0 bash

构建Docker镜像

要像本仓库一样本地构建Docker镜像，需先生成Dockerfile，然后运行 build-images.sh 脚本：

bash
./build-images.sh

正式发布CircleCI镜像时，此脚本将在CircleCI流水线中运行，而非本地。

发布***镜像（仅限维护者）

上述脚本可用于创建镜像所需文件，之后可创建新Git分支、提交更改等。仓库包含发布脚本以简化流程。例如，要发布Clojure 9.9.9（示例版本），从仓库根目录运行：

bash
./shared/release.sh 9.9.9#9.9.9.1234

其中 9.9.9 是Clojure版本，9.9.9.1234 是版本参数（Clojure版本+构建号）。构建号获取方式同上。

此命令将自动创建新Git分支、生成Dockerfile、暂存更改、提交并推送到GitHub。之后需：

• 等待CircleCI构建完成
• 审核PR
• 合并PR

主分支构建将自动发布版本。

变更整合

变更的整合方式取决于其来源：

构建脚本：./shared 子模块中的变更在其 独立仓库 中进行。要使这些变更影响本镜像，需更新子模块：

bash
cd shared
git pull
cd ..
git add shared
git commit -m "更新子模块以支持XX功能"

父镜像：设计上，父镜像变更不会影响现有Clojure镜像（以确保构建确定性，避免破坏用户构建）。新Clojure镜像将自动继承父镜像变更。若需将父镜像变更合并到现有Clojure镜像，需将其作为新镜像版本构建（生成新Dockerfile并发布）。

Clojure特定变更：通过编辑本仓库的 Dockerfile.template 文件修改Clojure镜像。本地查看变更需重新运行 gen-dockerfiles.sh 脚本（见上文）。

贡献指南

我们欢迎提交 issues 和 pull requests，但为尊重你的时间，请注意：

1. 并非所有工具都会被纳入镜像。工具需满足：维护活跃且对大多数Clojure开发者有用。每个工具都会增加镜像大小并降低所有用户的构建速度，因此需严格筛选。

2. PR欢迎，但大型PR建议先开issue讨论，确保其价值。

3. Issues用于报告bug或请求增减工具。镜像使用问题请访问 CircleCI Discuss。

其他资源

CircleCI文档 - CircleCI文档网站。
CircleCI配置参考 - 文档中最实用的页面之一，列出了 .circleci/config.yml 支持的所有键和值。
Docker文档 - 简单项目可能无需，但深入学Docker的优质资源。

许可证

本仓库采用MIT许可证。详见 LICENSE。