Clojure

deps.edn 参考

概述

deps.edn 文件是一个数据文件,它指定了形成项目类路径所需的所有信息,包括依赖项、路径和外部依赖项仓库信息。deps.edn 文件格式由 tools.deps 库Clojure CLI 使用。

如果你正在构建一个希望利用 deps.edn 的工具,请创建知名命名空间的 :aliases 作为传达工具配置的一种方式,而不是在 deps.edn 数据中的其他地方添加新的任意标签 - 这些标签可能不会在处理过程中保留或传达。工具可以在运行时通过基础访问别名数据,或者通过 tools.deps 以编程方式访问。

所有属性的索引
{;; Project paths
 :paths ["relative/path1" :path-alias]

 ;; Project dependencies
 :deps {
   ;; Maven lib
   groupId/artifactId$classifier {:mvn/version "1.2.3"
                                  :exclusions [lib1 lib2]}

   ;; Git lib
   gitlib/name {:git/url "https://example.com/repo"
                :git/tag "dev"
                :git/sha "123abcd"
                :deps/root "sub/dir"
                :deps/manifest :pom
                :exclusions [lib1 lib2]}

   ;; Local directory
   localdir/name {:local/root "path/to/dir"
                  :deps/manifest :pom
                  :exclusions [lib1 lib2]}

   ;; Local jar
   localjar/name {:local/root "path/to.jar"
                  :exclusions [lib1 lib2]}}

 ;; Aliases give a name to any set of edn data
 :aliases {
   :alias-name {
     :extra-deps {lib coord}
     :override-deps {lib coord}
     :default-deps {lib coord}
     :deps {lib coord}
     :replace-deps {lib coord}

     :extra-paths ["p1" "p2"]
     :paths ["p1" "p2"]
     :replace-paths ["p1" "p2"]
     :classpath-overrides {lib "path"}

     :ns-default namespace
     :ns-aliases {alias namespace}

     :exec-fn afn/symbol
     :exec-args {key val}

     :jvm-opts ["opt1" "opt2"]
     :main-opts ["opt1" "opt2"]}}

 ;; Procurer config
 :mvn/local-repo "path/to/local-repo"
 :mvn/repos {"repo" {:url "https://..."
                     :releases {:enabled true
                                :update :daily
                                :checksum true}
                     :snapshots {#_same_as_releases}}}

 ;; Tool publishing
 :tools/usage {:ns-default namespace
               :ns-aliases {alias namespace}}

 ;; Lib that requires preparation (compilation) before use
 :deps/prep-lib {:ensure "target/classes"
                 :alias :build
                 :fn compile}}

:paths

路径指定项目中应该放在项目类路径上的目录,包括源代码和资源。

路径在顶级键 :paths 中声明,并且是字符串路径或别名集合。别名引用别名中定义的路径集合(这可以用于重用)。

路径应该是相对于项目根目录的子目录,例如 "src""resources"。支持绝对路径,但应仅在特殊情况下使用。项目根目录之外的路径将触发警告消息 - 这些路径已弃用,将来可能会删除。

如果使用,别名应该引用别名数据中的路径向量。

{:paths [:clj-paths :resource-paths]
 :aliases
 {:clj-paths ["src/clj" "src/cljc"]
  :resource-paths ["resources"]}}

路径始终包含在类路径的开头,按照扩展的 :paths 集合中提供的顺序。

:deps

依赖项在 deps.edn 中使用顶级键 :deps 声明 - 从库到坐标的映射。

库名称是限定符号。非限定符号被视为 name/name,但这种用法已弃用。坐标(以及在某种程度上库名称)特定于以下坐标类型。

依赖项从这组顶级依赖项中 扩展,以包含所有传递依赖项。通常,会选择最新版本(除非有其他约束 - 请参阅文档)。依赖项将在任何路径之后放在类路径上,按照 a) 从根目录的深度和 b) 某个深度依赖项的字母顺序排序。此顺序应该稳定。

示例

{:deps
 {;; example maven dep
  org.clojure/tools.reader {:mvn/version "1.1.1"}

  ;; example git dep
  io.github.sally/awesome {:git/tag "v1.2.3" :git/sha "123abcd"}

  ;; example local dep
  my.dev/project {:local/root "../project"}

  ;; example local jar
  my.driver/jar {:local/root "../libs/driver.jar"}
 }}

Maven 依赖

Maven 获取器使用限定符 mvn,用于从 Maven 仓库 获取库工件,Maven 仓库是 Java 生态系统中的标准仓库管理器。库被下载为 .jar 文件,并存储在 Maven 本地仓库缓存中(默认情况下位于 ~/.m2/repository,或者使用 :mvn/local-repo 覆盖)。其他基于 JVM 的工具也可能使用此缓存。

Maven 库位于 Maven 仓库中,使用“Maven 坐标”,通常是 groupId、artifactId 和 version(有时也缩写为 GAV)。在 deps.edn 中,库名称被解析为 groupId/artifactId,版本取自 :mvn/version。一些 Maven 工件还具有“分类器”,它是特定工件的变体。在 Maven 获取器中,分类器包含在 lib 名称的末尾,以 $ 分隔,格式如下:groupId/artifactId$classifier

目前,只支持 jar 工件。将来可能会添加对其他工件类型(尤其是物料清单 pom)的支持。

请注意,依赖项或传递依赖项中声明的 Maven <repositories> 被忽略。所有依赖项所需的仓库都必须在项目 deps.edn 中使用 :mvn-repos 声明。

:mvn/version

所有 Maven 依赖项都需要,它以字符串形式指定版本。

示例

  • "1.2.3"

  • "1.2.3-SNAPSHOT"

Git 依赖

git 获取器支持直接使用托管在 Git 仓库中的基于源代码的库。默认情况下,Git 库被下载到 ~/.gitlibs 目录。工作树被签出并为每个作为依赖项包含的 sha 缓存。

要将 git 库指定为依赖项,必须知道两条信息 - Git 仓库 url 和特定的 sha。不支持使用分支名称等可移动引用。

Git 坐标具有以下属性

  • :git/url - 可选,Git url(可以从 lib 名称推断,见下文)

  • :git/sha - 必需,可以是完整的 40 个字符的 sha,也可以是与标签结合使用的 sha 前缀(:sha 也被接受,用于向后兼容)

  • :git/tag - 可选,git 标签名称(只能与 :git/sha 结合使用,:tag 被接受,用于向后兼容)

Git url 必须提供或从 lib 名称推断。如果提供,:git/url 优先。Lib 到 url 约定如下

Lib 格式 推断的 :git/url

io.github.ORG/PROJECT

"https://github.com/ORG/PROJECT.git"

com.github.ORG/PROJECT

"https://github.com/ORG/PROJECT.git"

io.gitlab.ORG/PROJECT

"https://gitlab.com/ORG/PROJECT.git"

com.gitlab.ORG/PROJECT

"https://gitlab.com/ORG/PROJECT.git"

io.bitbucket.ORG/PROJECT

"https://bitbucket.org/ORG/PROJECT.git"

org.bitbucket.ORG/PROJECT

"https://bitbucket.org/ORG/PROJECT.git"

io.beanstalkapp.ORG/PROJECT

"https://ORG.git.beanstalkapp.com/PROJECT.git"

com.beanstalkapp.ORG/PROJECT

"https://ORG.git.beanstalkapp.com/PROJECT.git"

ht.sr.ORG/PROJECT

"https://git.sr.ht/~ORG/PROJECT"

这是一个示例 deps.edn,其中包含两个有效的 git 依赖项,第一个使用推断的 git url、git 标签和 sha 前缀,第二个使用显式的 git url 和完整的 sha

{:deps
 {;; implied git url, tag + sha prefix
  io.github.clojure/tools.deps.graph {:git/tag "v1.1.68" :git/sha "6971bb4"}

  ;; explicit git url, full sha
  org.clojure/tools.build {:git/url "https://github.com/clojure/tools.build.git"
                           :git/sha "ba1a2bf421838802e7bdefc541b41f57582e53b6"}}}

:git/url

如果使用上面描述的格式,:git/url 会从 lib 名称中推断出来,否则必须提供。

最常见的 git url 协议是 https 和 ssh。https 仓库将以匿名方式访问,不需要其他身份验证信息。对于你无法控制的公共仓库,推荐这种方法。ssh 仓库可以是公共的或私人的,并使用你的 ssh 身份。

有关创建密钥和使用 ssh-agent 管理 ssh 身份的更多信息,GitHub 提供了很好的信息

其他协议(包括本地和文件)应该可以工作,但并不常用。

:git/tag

:git/tag 是一个可选的坐标键,它通过指定标签来指示 sha 的语义。如果提供了 :git/tag,则 :git/sha 可以是短 sha,而不是完整的 40 个字符的 sha。

:git/sha

:git/sha 是一个必需的坐标键。如果提供了 :git/tag,则它可以是前缀 sha(它们必须展开到同一个提交),否则它应该是完整的 40 个字符的 sha。

在从 sha A 和 sha B 之间选择版本时,如果 B 是 A 的祖先,则优先选择 B(“最下级”)。如果 A 和 B 没有祖先/后代关系(例如并行分支中的提交),则这是一个错误,类路径构建将失败。

本地依赖

本地依赖项引用磁盘上的目录或 jar 文件。:local/root 属性是必需的,可以是绝对路径或相对路径。

:local/root

对于本地项目目录,:local/root 应该是目录路径,可以是绝对路径,也可以是相对于项目目录位置的相对路径。

对于 jar 文件,:local/root 应该是 jar 文件的绝对路径或相对路径。如果 jar 包含 pom.xml 文件,它将被用于查找传递依赖项。

共享依赖属性

:exclusions

:exclusions 属性接受一个 lib 符号向量,用于从该依赖项中排除作为传递依赖项。此属性可以用于任何依赖项。

:deps/root

:deps/root 属性指示基于文件的依赖项中要搜索清单文件的相对目录路径。它通常与 monorepo 样式的项目一起使用,以指定仓库根目录下的目录中的依赖项根目录。

:deps/manifest

当包含 git 或本地项目时,项目类型会根据清单文件 deps.edn 和 pom.xml 自动检测。如果两者都存在,则优先使用 deps.edn。

:deps/manifest 属性指定项目清单类型,并覆盖自动检测,有用的值是 :deps:pom。(其他值为 :mvn:jar,但不需要指定。)

:aliases

别名给数据结构起了一个名字,Clojure CLI 本身或其他 deps.edn 消费者可以使用它。它们在配置文件的 :aliases 部分定义。

:extra-deps

:extra-deps 是最常见的修改 - 它允许您向基本依赖集添加额外的依赖项。该值是库到坐标的映射。

{:extra-deps {criterium/criterium {:mvn/version "0.4.4"}}}

:override-deps

:override-deps 覆盖版本解析选择的坐标版本,以强制使用特定版本。该值是库到坐标的映射。

{:override-deps {org.clojure/clojure {:mvn/version "1.9.0"}}}

:default-deps

:default-deps 提供一组默认坐标版本,如果未指定坐标,则使用这些版本。默认依赖项可在多个共享项目中使用,充当依赖项管理系统。

{:default-deps {org.clojure/core.cache {:mvn/version "0.6.4"}}}

:deps / :replace-deps

:deps:replace-deps 是同义词,并定义了一个 deps 映射,该映射替换项目 :deps。该值是 lib 到坐标的映射。

:extra-paths

:extra-paths 用于除了标准源路径之外还包含源路径,例如包含测试源目录。

{:extra-paths ["test" "resources"]}

请注意,外部路径应位于项目根目录(deps.edn 文件所在位置)或其下。

:paths / :replace-paths

:paths:replace-paths 是同义词,并定义一组字符串路径来替换项目 :paths

:classpath-overrides

:classpath-overrides 指定一个位置来提取一个依赖项,该依赖项将覆盖在依赖项解析期间找到的路径,例如用本地调试版本替换一个依赖项。许多这样的用例是您可能想将类路径预置到“覆盖”其他东西的用例。

{:classpath-overrides
 {org.clojure/clojure "/my/clojure/target"}}

:ns-default

:ns-default 属性是一个命名空间符号,它将用作提供非限定符号的属性的默认命名空间,最重要的是 :exec-fn

:ns-aliases

:ns-aliases 属性是别名符号到命名空间符号的映射,它将用于解析限定符号,最重要的是 :exec-fn

:exec-fn

:exec-fn 符号定义了在 Clojure CLI 中使用 -X 函数执行时要调用的默认函数。

;; deps.edn
{:aliases
 {:my-fn
  {:exec-fn my.qualified/fn
   :exec-args {:my {:data 123}
               :config 456}}}}

:exec-fn 符号根据以下规则解析。

  • 如果函数是非限定的,则使用 arg 映射中 :ns-default 键的命名空间(如果没有,则这是一个错误)。

  • 如果函数是限定的,并且限定符是 arg 映射中 :ns-aliases 下的别名,则使用该命名空间。

  • 否则使用完全限定的函数符号。

:exec-args

:exec-args 映射指定在 Clojure CLI 中使用 -X 或 -T 执行 :exec-fn 函数时提供的键值对。这些键值对实际上首先提供,因此可以在命令行上被后续的键值对覆盖。

:jvm-opts

:jvm-opts 是使用 -M、-X、-T 或 repl 执行 Clojure CLI 时提供的字符串 JVM 选项的集合。

:main-opts

:main-opts 是使用 Clojure CLI 上的 -M 启动的程序提供的字符串选项的集合。如果合并了提供主参数的多个别名,则只使用最后一个别名的参数(它们不会累积或合并)。可以在命令行上 -M 之后提供其他主选项。

获取器配置

Maven

Maven 获取器使用 Maven 解析器和 Maven 存储库系统来下载工件。这在 Maven 依赖项 部分中有更详细的说明。一些选项可以在 deps.edn 中配置。

:mvn/local-repo

默认情况下,Maven 使用 ~/.m2/repository 目录作为下载的 pom 和 jar 的本地缓存。:mvn/local-repo 是一个字符串路径,指向用作本地 Maven 缓存的备用目录。

:mvn/repos

Maven 获取器始终使用两个内置存储库,它们始终按以下顺序检查。

{"central" {:url "https://repo1.maven.org/maven2/"}
 "clojars" {:url "https://repo.clojars.org/"}}

您可以在 :mvn/repos 键中以存储库名称到附加存储库属性映射的映射形式提供附加存储库,如下所述。存储库名称是任意的。:url 属性是必需的,所有其他属性都是可选的。在依赖项 pom 或 deps.edn 中声明的存储库不会被使用 - 所有必要的存储库都必须在使用的顶级 deps.edn 文件中定义。

:url

:url 是一个指向存储库根目录的字符串 URL。

默认情况下不支持 http:// URL,但请参见 clojure_cli 以获取有关 CLOJURE_CLI_ALLOW_HTTP_REPO 的信息(如果您需要它)。

:releases 和 :snapshots

:releases 属性是可选的,但可以用来覆盖发行版(非快照工件)的默认存储库配置。

{:mvn/repos
 {"my-releases" {:url "https://example.com/releases"
                 :snapshots {:enabled false}
                 :releases {:enabled true
                            :update :daily
                            :checksum :fail}}}}

:snapshots 属性与 :releases 属性相同,但应用快照工件的存储库策略。

存储库属性

  • :enabled 是一个布尔值,默认为 true。有时它用于仅针对发行版或快照来定位存储库。

  • :update 是一个标志,用于确定多久检查一次存储库以获取更新,有效值为 :daily(默认)、:always:never 或以分钟为单位的间隔(整数)。

  • :checksum 是一个用于校验和验证的标志,其中一个是 :warn(默认)、:fail:ignore

另请参见 Maven 获取器配置 以了解 Clojure CLI 中的附加配置。

Git

另请参见 Git 获取器配置 以了解 Clojure CLI 中的附加配置。

本地

本地获取器没有配置选项。

工具定义

从 Github 或本地目录加载的 Clojure CLI 工具可以使用 :tools/usage 键在其 deps.edn 中提供默认工具配置。所有工具用户在安装工具时都会获得此配置。

:tools/usage

基于 deps.edn 的工具的 exec arg 映射,其中可能包含以下属性。

准备库

:deps/prep-lib

包含 Clojure 源代码的源库可以立即添加到使用它的项目的类路径中。但是,一些源库需要在添加之前进行一些准备工作,例如由于需要 Java 编译,或复制/替换资源文件等。Clojure CLI 现在将检测需要准备的项目,并防止程序从源代码运行,除非准备步骤已完成。

如果您的库需要准备,请将 :deps/prep-lib 键添加到您的 deps.edn 中。

{:paths ["src" "target/classes"]
 :deps/prep-lib
 {:ensure "target/classes"
  :alias :build
  :fn compile-java}}

:ensure

:ensure 是相对于项目的目录路径,其存在决定是否需要准备(如果存在,则表示准备工作已完成)。

:alias

:alias 是在准备期间使用 -T 调用的关键字别名。

:fn

:fn 是在准备期间使用 -T 调用的函数。