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 儲存庫(Java 生態系統中的標準儲存庫管理員)擷取程式庫成品。程式庫會下載為 .jar 檔案,並儲存在 Maven 本機儲存庫快取中(預設位於 ~/.m2/repository,或以:mvn/local-repo覆寫)。其他基於 JVM 的工具也可能會使用此快取。

Maven 程式庫會使用「Maven 座標」位於 Maven 儲存庫中,通常為 groupId、artifactId 和版本(有時也縮寫為 GAV)。在 deps.edn 中,程式庫名稱會解析為 groupId/artifactId,而版本則取自 :mvn/version。有些 Maven 成品也有一個「分類器」,這是特定成品的變體。在 Maven 採購者中,分類器會包含在程式庫名稱的結尾,並以 $ 分隔,格式如下:groupId/artifactId$classifier

目前僅支援 jar 成品。未來可能會新增對其他成品類型(特別是材料清單 pom)的支援。

請注意,相依性或傳遞相依性中宣告的 Maven <repositories> 會被忽略。所有相依性全套所需的儲存庫都必須使用:mvn-repos在專案 deps.edn 中宣告。

: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(可從程式庫名稱推論,詳見下方)

  • :git/sha - 必填,可提供完整的 40 字元 sha 或 sha 前綴,並與標籤合併使用(:sha 也接受,以維持向後相容性)

  • :git/tag - 可選,git 標籤名稱(僅能與 :git/sha 結合使用,:tag 接受,以維持向後相容性)

git url 必須提供或從程式庫名稱推論。如果提供,:git/url 優先。程式庫轉換 url 的慣例如下

程式庫格式 推論的 :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"

以下是一個包含兩個有效 git 依賴項的 deps.edn 範例,第一個具有推論的 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 會從程式庫名稱推論,否則必須提供。

最常見的 git url 協定是 https 和 ssh。https 儲存庫將匿名存取,不需要額外的驗證資訊。建議將此方法用於您不控制的公開儲存庫。ssh 儲存庫可以是公開或私人,並使用您的 ssh 身分識別。

有關建立金鑰和使用 ssh-agent 管理 ssh 身分識別的更多資訊,GitHub 提供了絕佳的資訊

其他協定(包括本機和檔案)應該可以正常運作,但並不常見。

:git/tag

:git/tag 是個可選的 coord 金鑰,透過指定標籤來表示 sha 的語意。如果提供 :git/tag:git/sha 可以是短的 sha,而不是完整的 40 個字元的 sha。

:git/sha

:git/sha 是個必填的 coord 金鑰。如果提供 :git/tag,它可以是 sha 前綴(它們必須解析為相同的 commit),否則它應該是完整的 40 個字元的 sha。

從 sha A 和 sha B 之間選擇版本時,其中 B 是 A 的祖先,則會優先選擇 B(「最晚代」)。如果 A 和 B 沒有祖先/後代關係(例如平行分支中的 commit),這是一個錯誤,類別路徑建立會失敗。

本機依賴項

本機 deps 指的是磁碟上的目錄或 jar 檔案。:local/root 屬性是必要的,可以是絕對路徑或相對路徑。

:local/root

對於本機專案目錄,:local/root 應為目錄路徑,可以是專案目錄位置的絕對路徑或相對路徑。

對於 jar 檔案,:local/root 應為 jar 檔案的絕對路徑或相對路徑。如果 jar 檔案包含 pom.xml 檔案,將會使用它來尋找傳遞依賴項

共用 dep 屬性

:exclusions

:exclusions 屬性會取得一個 lib 符號向量,將其排除為此依賴項的傳遞依賴項。此屬性可用於任何依賴項。

:deps/root

:deps/root 屬性表示在基於檔案的 dep 中搜尋清單檔案的相對目錄路徑。它通常與單一存放庫樣式的專案搭配使用,以指定儲存庫根目錄下方目錄中的 dep 根目錄。

: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 提供一組預設座標版本,供在未指定座標時使用。預設 deps 可用於一組共用專案,作為依賴項管理系統

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

:deps / :replace-deps

:deps:replace-deps 是同義詞,定義一個 deps 地圖,用來取代專案的 :deps。其值是一個 lib 到 coordinate 的地圖。

:extra-paths

:extra-paths 用於包含標準來源路徑以外的來源路徑,例如包含測試來源的目錄

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

請注意,外部路徑應位於專案根目錄或其下 (deps.edn 檔案的位置)。

:paths / :replace-paths

:paths:replace-paths 是同義詞,定義一個字串路徑集合,用來取代專案的 :paths

:classpath-overrides

:classpath-overrides 指定一個位置,用於提取在依存關係解析期間找到的路徑所覆寫的依存關係,例如用一個本機除錯版本取代一個依存關係。這些用例中的許多用例會讓您忍不住將 classpath 預置到「覆寫」其他內容

{: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 函式時提供的鍵值對。這些 kv 對實際上會優先提供,因此可以被命令列上的後續 kv 對覆寫。

:jvm-opts

:jvm-opts 是一組字串 JVM 選項,在使用 -M、-X、-T 或 repl 執行 Clojure CLI 時提供。

:main-opts

:main-opts 是提供給使用 -M 在 Clojure CLI 上啟動的程式的一組字串選項。如果合併多個提供主參數的別名,則只會使用最後一個別名的參數(它們不會累積或合併)。可以在命令列中 -M 之後提供其他主選項。

採購者設定

Maven

Maven 採購者使用 Maven 解析器和 Maven 儲存庫系統來下載人工製品。這在 Maven deps 區段中有更進一步的說明。有些選項可以在 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 工具可以在其 deps.edn 中使用 :tools/usage 鍵提供預設工具設定。所有工具使用者都會在安裝工具時取得此設定。

: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 呼叫的函式