Clojure

deps.edn リファレンス

概要

deps.edn ファイルは、deps、パス、外部依存リポジトリ情報など、プロジェクトのクラスパスを形成するために必要なすべての情報を指定するデータファイルです。deps.edn ファイル形式は、tools.deps ライブラリClojure CLIで使用されます。

deps.edn を活用するツールを構築する場合は、deps.edn データ内の他の場所に新しい任意のタグを追加するのではなく、ツール設定を伝達する手段として、よく知られた名前空間付きの:aliasesを作成してください。これらは処理中に保持または伝達されない場合があります。ツールは、実行時に基盤を介して、またはプログラム的に 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で deps.edn で宣言されます。これは、ライブラリから座標へのマップです。

ライブラリ名は修飾されたシンボルです。修飾されていないシンボルはname/nameとして扱われますが、この使用法は非推奨です。座標(およびある程度のライブラリ名)は、以下の座標タイプに固有です。

依存関係は、このトップレベルの deps セットから展開され、すべての推移的な deps が含まれるようになります。一般に、最新バージョンが選択されます(他の制約がない場合 - ドキュメントを参照してください)。依存関係は、パスの後にクラスパスに配置され、a) ルートからの深さと b) 特定の深さにある deps のアルファベット順にソートされます。この順序は安定している必要があります。

{: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 deps

Maven プロキュアラーは、修飾子mvnを使用し、Maven リポジトリ(Java エコシステムの標準リポジトリマネージャー)からライブラリアーティファクトを取得するために使用されます。ライブラリは .jar ファイルとしてダウンロードされ、Maven ローカルリポジトリキャッシュ(デフォルトで ~/.m2/repository に配置され、:mvn/local-repoで上書き)に保存されます。他の JVM ベースのツールもこのキャッシュを使用する場合があります。

Maven ライブラリは、通常、groupId、artifactId、およびバージョン(場合によっては GAV と略されることもあります)である「Maven 座標」を使用して Maven リポジトリに配置されます。deps.edn では、ライブラリ名はgroupId/artifactIdとして解析され、バージョンは:mvn/versionから取得されます。一部の Maven アーティファクトには、「分類子」と呼ばれる特定のアーティファクトのバリアントもあります。Maven プロキュアラーでは、分類子は lib 名の末尾に、この形式で$で区切って含まれます。groupId/artifactId$classifier

現在、jarアーティファクトのみがサポートされています。他のアーティファクトタイプ(特に Bill of Materials poms)のサポートは、将来追加される可能性があります。

依存関係または推移的依存関係で宣言された Maven <repositories> は無視されることに注意してください。依存関係の完全なセットに必要なすべてのリポジトリは、:mvn-reposを使用してプロジェクト deps.edn で宣言する必要があります。

:mvn/version

すべての Maven 依存関係に必須であり、バージョンを文字列として指定します。

  • "1.2.3"

  • "1.2.3-SNAPSHOT"

Git deps

gitプロキュアラーは、Git リポジトリでホストされているソースベースのライブラリの直接使用をサポートします。Git ライブラリは、デフォルトで~/.gitlibsディレクトリにダウンロードされます。ワーキングツリーはチェックアウトされ、依存関係として含まれる各 sha に対してキャッシュされます。

git lib を依存関係として指定するには、Git リポジトリの URL と特定の sha の 2 つの情報がわかっている必要があります。ブランチ名のような移動可能な参照の使用はサポートされていません。

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"

これは、2 つの有効な git deps を含む deps.edn の例です。1 つ目は、推測された git url、git タグ、および sha 接頭辞を使用し、2 つ目は、明示的な 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 ID を使用します。

キーの作成と ssh-agent を使用して ssh ID を管理する方法の詳細については、GitHub に優れた情報が記載されています。

他のプロトコル(ローカルやファイルを含む)も機能しますが、一般的には使用されません。

:git/tag

:git/tagは、タグを指定することにより sha のセマンティクスを示すオプションの座標キーです。:git/tagが提供されている場合、:git/shaは完全な 40 文字の sha の代わりに短い sha にすることができます。

:git/sha

:git/shaは必須の座標キーです。:git/tagが提供されている場合、接頭辞 sha にすることができます(同じコミットにアンピールする必要があります)。それ以外の場合は、完全な 40 文字の sha にする必要があります。

sha A と sha B の間からバージョンを選択する場合、B は A を祖先として持つ場合、B が優先されます(「最も子孫」のバージョン)。A と B が祖先/子孫関係を持たない場合(たとえば、並行ブランチのコミット)、これはエラーであり、クラスパスの構築は失敗します。

ローカル deps

ローカル deps は、ディスク上のディレクトリまたは jar ファイルを参照します。:local/root属性は必須であり、絶対パスまたは相対パスのいずれでもかまいません。

:local/root

ローカルプロジェクトディレクトリの場合、:local/rootはディレクトリパスである必要があります。これは、プロジェクトディレクトリの場所に対する絶対パスまたは相対パスです。

jarファイルの場合、:local/root はjarファイルへの絶対パスまたは相対パスのいずれかである必要があります。jarにpom.xmlファイルが含まれている場合、推移的な依存関係を見つけるために使用されます。

共有依存関係属性

:exclusions

:exclusions 属性は、この依存関係からの推移的な依存関係として除外するライブラリシンボルのベクターを受け取ります。この属性は、どの依存関係にも使用できます。

:deps/root

:deps/root 属性は、ファイルベースの依存関係内でマニフェストファイルを検索するための相対ディレクトリパスを示します。これは、モノレポスタイルのプロジェクトで、リポジトリルートより下のディレクトリにある依存関係ルートを指定するためによく使用されます。

: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 を置き換える依存関係マップを定義します。値は、ライブラリから座標へのマップです。

: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 シンボルは、次のルールで解決されます。

  • 関数が非修飾の場合、引数マップの :ns-default キーの名前空間を使用します(ない場合はエラーになります)。

  • 関数が修飾されており、修飾子が引数マップの :ns-aliases の下にあるエイリアスである場合は、その名前空間を使用します。

  • それ以外の場合は、完全修飾関数シンボルを使用します。

:exec-args

:exec-args マップは、Clojure CLI で -X または -T を使用して :exec-fn 関数を実行するときに提供されるキーと値のペアを指定します。これらの kv ペアは事実上最初に提供されるため、コマンドライン上の後続の kv ペアでオーバーライドできます。

:jvm-opts

:jvm-opts は、Clojure CLI を -M、-X、-T、または repl で実行するときに提供される文字列 JVM オプションのコレクションです。

:main-opts

:main-opts は、Clojure CLI で -M で開始されたプログラムに提供される文字列オプションのコレクションです。複数のエイリアスがマージされてメイン引数が提供される場合、最後のエイリアスの引数のみが使用されます(それらは累積または結合されません)。追加のメインオプションは、コマンドラインで -M の後に提供できます。

プロキュア構成

Maven

Maven プロキュアは、Maven リゾルバーと Maven リポジトリシステムを使用してアーティファクトをダウンロードします。これについては、Maven deps セクションで詳しく説明します。いくつかのオプションは、deps.edn で構成できます。

:mvn/local-repo

デフォルトでは、Maven は ~/.m2/repository ディレクトリをダウンロードした pom および jar のローカルキャッシュとして使用します。:mvn/local-repo は、ローカル Maven キャッシュとして使用する代替ディレクトリへの文字列パスです。

:mvn/repos

Maven プロキュアは、常にこの順序で最初にチェックされる2つの組み込みリポジトリを使用します。

{"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_ALLOW_HTTP_REPO の詳細についてclojure_cliを参照してください。

: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 のいずれかです。

Clojure CLI の追加の構成については、Maven プロキュア構成も参照してください。

Git

Clojure CLI の追加の構成については、Git プロキュア構成も参照してください。

ローカル

ローカルプロキュアには構成オプションはありません。

ツール定義

Github またはローカルディレクトリからロードされた Clojure CLI ツールは、:tools/usage キーを使用して、deps.edn でデフォルトのツール構成を提供できます。ツールのすべてのユーザーは、ツールインストールの一部としてこの構成を取得します。

:tools/usage

deps.edn ベースのツールの実行引数マップ。次の属性を含めることができます。

Prep lib

:deps/prep-lib

Clojureソースを含むソースライブラリは、それを使用するプロジェクトのクラスパスにすぐに追加できます。ただし、一部のソースライブラリでは、Javaコンパイルやリソースファイルのコピー/置換など、追加する前に準備が必要になる場合があります。Clojure CLIは、準備が必要なプロジェクトを検出し、準備ステップが完了するまで、ソースからプログラムが実行されないようにします。

ライブラリに準備が必要な場合は、deps.edn:deps/prep-lib キーを追加します。

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

:ensure

:ensure は、準備が必要かどうかを決定するプロジェクトに対する相対ディレクトリパスです(存在する場合、準備は完了しています)。

:alias

:alias は、準備中に -T で呼び出すキーワードエイリアスです。

:fn

:fn は、準備中に -T で呼び出す関数です。