deps.edn 레퍼런스

deps.edn 레퍼런스 (deps.edn Reference)

deps.edn 파일은 프로젝트 클래스패스를 형성하는 데 필요한 모든 정보(의존성, 경로, 외부 의존성 저장소 정보)를 지정하는 데이터 파일이에요. deps.edn 파일 형식은 tools.deps 라이브러리와 Clojure CLI에서 사용돼요.

deps.edn을 활용하려는 도구를 만든다면, 도구 설정을 전달하는 수단으로 잘 알려진 네임스페이스화된 :aliases를 만들되, deps.edn 데이터의 다른 곳에 새 임의 태그를 추가하지 마세요 — 그것들은 처리 중에 보존되거나 전달되지 않을 수 있어요. 도구는 :basis(러닝타임 베이시스)를 통해 런타임에, 또는 tools.deps를 통해 프로그래밍 방식으로 별칭 데이터에 접근할 수 있어요.

출처: deps.edn Reference

본문

deps.edn 속성 인덱스

{;; 프로젝트 경로
 :paths ["relative/path1" :path-alias]

 ;; 프로젝트 의존성
 :deps {
   ;; Maven 라이브러리
   groupId/artifactId$classifier {:mvn/version "1.2.3"
                                  :exclusions [lib1 lib2]}

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

   ;; 로컬 디렉터리
   localdir/name {:local/root "path/to/dir"
                  :deps/manifest :pom
                  :exclusions [lib1 lib2]}

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

 ;; 별칭은 임의의 edn 데이터 집합에 이름을 부여함
 :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) 설정
 :mvn/local-repo "path/to/local-repo"
 :mvn/repos {"repo" {:url "https://..."
                     :releases {:enabled true
                                :update :daily
                                :checksum :warn}
                     :snapshots {#_same_as_releases}}}

 ;; 도구 게시
 :tools/usage {:ns-default namespace
               :ns-aliases {alias namespace}}

 ;; 사용 전 준비(컴파일)가 필요한 라이브러리
 :deps/prep-lib {:ensure "target/classes"
                 :alias :build
                 :fn compile}}

:paths

경로는 프로젝트에서 프로젝트 클래스패스에 놓아야 할 디렉터리(소스와 리소스 모두)를 지정해요.

경로는 최상위 키 :paths에 선언되며, 문자열 경로나 별칭 이름의 컬렉션이에요. 별칭 이름은 별칭에 정의된 경로 컬렉션을 가리켜요(재사용을 위해 그렇게 할 수 있음).

경로는 프로젝트 루트에 상대적인 하위 디렉터리여야 해요, 예: "src" 또는 "resources". 절대 경로는 지원되지만 예외적인 경우에만 사용해야 해요. 프로젝트 루트 밖의 경로는 경고 메시지를 트리거해요 — 이것들은 더 이상 사용되지 않으며(pending deprecated) 미래에 제거될 수 있어요.

사용된다면 별칭 이름은 별칭 데이터의 경로 벡터를 가리켜야 해요:

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

경로는 항상 클래스패스의 앞부분에, 확장된 :paths 컬렉션에서 제공된 순서대로 포함돼요.

:deps

의존성은 deps.edn에서 최상위 키 :deps — 라이브러리에서 좌표로의 맵 — 로 선언돼요.

라이브러리 이름은 한정된(symbol)이에요. 한정되지 않은 symbol은 name/name으로 취급되지만 이 사용법은 더 이상 사용되지 않아요(deprecated). 좌표(그리고 어느 정도 라이브러리 이름)는 아래의 좌표 타입들에 특정적이에요.

의존성은 이 최상위 dep 집합에서 모든 전이 의존성을 포함하도록 확장(expanded)돼요. 일반적으로 가장 새로운 버전이 선택돼요(다른 제약이 없다면 — 문서 참조). 의존성은 어떤 경로 다음에 클래스패스에 놓이며, a) 루트로부터의 깊이로, b) 특정 깊이에서 dep의 알파벳 순으로 정렬돼요. 이 순서는 안정적이어야 해요.

예:

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

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

  ;; 예: 로컬 dep
  my.dev/project {:local/root "../project"}

  ;; 예: 로컬 jar
  my.driver/jar {:local/root "../libs/driver.jar"}
 }}

Maven deps

Maven 조달자(procurer)는 한정자 mvn을 사용하며, Java 생태계의 표준 저장소 관리자인 Maven 저장소에서 라이브러리 아티팩트를 가져와요. 라이브러리는 .jar 파일로 다운로드되어 Maven 로컬 저장소 캐시(기본적으로 ~/.m2/repository, 또는 :mvn/local-repo로 재정의 가능)에 저장돼요. 다른 JVM 기반 도구도 이 캐시를 사용할 수 있어요.

Maven 라이브러리는 "Maven 좌표"(보통 groupId, artifactId, 버전, 때로는 GAV로 줄임)를 사용해 Maven 저장소에 위치해요. deps.edn에서 라이브러리 이름은 groupId/artifactId로 파싱되고 버전은 :mvn/version에서 가져와요. 일부 Maven 아티팩트에는 특정 아티팩트의 변형인 "classifier"도 있어요. Maven 조달자에서 classifier는 lib 이름 끝에 $로 구분해 groupId/artifactId$classifier 형식으로 포함돼요.

현재 jar 아티팩트만 지원돼요. 다른 아티팩트 타입(특히 Bill of Materials pom)에 대한 지원은 미래에 추가될 수 있어요.

의존성 또는 전이 의존성에 선언된 Maven <repositories>는 무시된다는 점을 유의해요. 전체 의존성 집합에 필요한 모든 저장소는 프로젝트 deps.edn에 :mvn/repos를 사용해 선언해야 해요.

:mvn/version

모든 Maven 의존성에 필수이며, 버전을 문자열로 지정해요.

예:

"1.2.3"
"1.2.3-SNAPSHOT"

Git deps

git 조달자는 Git 저장소에 호스팅된 소스 기반 lib의 직접 사용을 지원해요. Git lib은 기본적으로 ~/.gitlibs 디렉터리에 다운로드돼요. 작업 트리는 의존성으로 포함된 각 sha에 대해 체크아웃되고 캐시돼요.

git lib을 의존성으로 지정하려면 Git 저장소 url과 특정 sha 두 정보를 알아야 해요. 브랜치 이름 같은 이동 가능 참조(movable references) 사용은 지원되지 않아요.

Git 좌표는 다음 속성을 가져요:

:git/url — 선택, Git url (아래처럼 lib 이름에서 추론될 수 있음)
:git/sha — 필수, 전체 40-char sha 또는 sha 접두사(태그와 함께 제공될 수 있음) (:sha도 하위 호환으로 받아들여짐)
:git/tag — 선택, git 태그 이름 (:git/sha와 함께만 사용될 수 있으며, :tag는 하위 호환으로 받아들여짐)

git url은 제공되거나 lib 이름에서 추론돼야 해요. 제공되면 :git/url이 우선해요. Lib에서 URL로의 규칙은 다음과 같아요:

다음은 두 개의 유효한 git dep을 포함하는 deps.edn 예시로, 첫 번째는 추론된 git url, git 태그, sha 접두사를, 두 번째는 명시적 git url과 전체 sha를 가져요:

{:deps
 {;; 추론된 git url, 태그 + sha 접두사
  io.github.clojure/tools.deps.graph {:git/tag "v1.1.68" :git/sha "6971bb4"}

  ;; 명시적 git url, 전체 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의 훌륭한 정보를 참조해요:

다른 프로토콜(local과 file 포함)도 동작해야 하지만 흔히 쓰이지 않아요.

:git/tag

:git/tag는 태그를 지정해 sha의 의미를 나타내는 선택적 coord 키예요. :git/tag가 제공되면 :git/sha는 전체 40-문자 sha 대신 짧은 sha일 수 있어요.

:git/sha

:git/sha는 필수 coord 키예요. :git/tag가 제공되면 접두사 sha일 수 있고(같은 커밋으로 unpeel돼야 함), 그렇지 않으면 전체 40-char sha여야 해요.

sha A와 sha B 사이에서 버전을 선택할 때 B가 A를 조상으로 가지면(가장 "후손"인 것) B가 선호돼요. A와 B가 조상/후손 관계를 가지지 않으면(예: 병렬 브랜치의 커밋) 이것은 오류이며 클래스패스 구성이 실패해요.

로컬 deps (Local deps)

로컬 dep은 디스크의 디렉터리나 jar 파일을 가리켜요. :local/root 속성은 필수이며 절대 또는 상대일 수 있어요.

:local/root

로컬 프로젝트 디렉터리의 경우 :local/root는 프로젝트 디렉터리 위치에 상대적이거나 절대적인 디렉터리 경로여야 해요.

jar 파일의 경우 :local/root는 jar 파일에 대한 절대 또는 상대 경로여야 해요. jar가 pom.xml 파일을 포함하면 전이 의존성을 찾는 데 사용돼요.

공유 dep 속성

:exclusions

:exclusions 속성은 이 의존성에서 전이 dep으로 배제할 lib symbol들의 벡터를 받아요. 이 속성은 어떤 의존성에도 사용할 수 있어요.

:deps/root

:deps/root 속성은 매니페스트 파일을 검색하기 위한 파일 기반 dep 내의 상대 디렉터리 경로를 나타내요. monorepo 스타일 프로젝트에서 저장소 루트 아래 디렉터리의 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는 좌표가 지정되지 않았을 때 사용할 기본 좌표 버전 집합을 제공해요. 기본 dep은 공유 프로젝트 집합에 걸쳐 의존성 관리 시스템으로 작동할 수 있어요:

{: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 속성은 한정되지 않은 symbol을 제공하는 속성, 가장 중요하게는 :exec-fn의 기본 네임스페이스로 사용될 네임스페이스 symbol이에요.

:ns-aliases

:ns-aliases 속성은 한정 symbol, 가장 중요하게는 :exec-fn을 해석하는 데 사용될 alias symbol에서 네임스페이스 symbol로의 맵이에요.

:exec-fn

:exec-fn symbol은 Clojure CLI에서 -X 함수 실행을 사용할 때 호출될 기본 함수를 정의해요:

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

:exec-fn symbol은 다음 규칙으로 해석돼요:

함수가 한정되지 않으면 arg 맵의 :ns-default 키의 네임스페이스를 사용해요 (없으면 오류)
함수가 한정되고 한정자가 arg 맵의 :ns-aliases 아래의 별칭이면 그 네임스페이스를 사용해요
그 외에는 완전 한정 함수 symbol을 사용해요

: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으로 시작된 프로그램에 제공되는 문자열 옵션 컬렉션이에요. main 인자를 제공하는 여러 별칭이 병합되면 마지막 별칭의 인자만 사용돼요(누적되거나 결합되지 않음). 추가 main 옵션은 -M 뒤 명령줄에서 제공될 수 있어요.

조달자 설정 (Procurer config)

Maven

Maven 조달자는 아티팩트를 다운로드하기 위해 Maven resolver와 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_ALLOW_HTTP_REPO에 대한 정보를 env_vars에서 참조해요.

:releases and :snapshots

:releases 속성은 선택적이지만, 릴리스(비-스냅샷 아티팩트)에 대한 기본 저장소 설정을 재정의하는 데 사용될 수 있어요:

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

:snapshots 속성은 :releases 속성과 같지만, 스냅샷 아티팩트에 대한 저장소 정책을 적용해요.

저장소 속성:

:enabled는 boolean이며, 기본값=true예요. 때로는 저장소를 릴리스나 스냅샷 전용으로 겨냥하는 데 사용돼요.
:update는 저장소 업데이트를 얼마나 자주 확인할지에 대한 플래그이며, 유효한 값은 :daily(기본), :always, :never, 또는 분 단위 간격(정수)이에요.
:checksum은 체크섬 검증에 대한 플래그로, :warn(기본), :fail, :ignore 중 하나예요.

Clojure CLI의 추가 설정은 Maven procurer config도 참조해요.

Git

Clojure CLI의 추가 설정은 Git procurer config도 참조해요.

Local

로컬 조달자에 대한 설정 옵션은 없어요.

도구 정의 (Tool definition)

GitHub 또는 로컬 디렉터리에서 로드된 Clojure CLI 도구는 deps.edn에 :tools/usage 키를 사용해 기본 도구 설정을 제공할 수 있어요. 도구의 모든 사용자는 도구 설치의 일부로 이 설정을 받아요.

:tools/usage

deps.edn 기반 도구를 위한 exec arg 맵으로, 다음 속성을 포함할 수 있어요:

:exec-args
:ns-default
:ns-aliases

Prep 라이브러리 (Prep lib)

:deps/prep-lib

Clojure 소스를 가진 소스 lib은 그것을 사용하는 프로젝트의 클래스패스에 즉시 추가될 수 있어요. 그러나 일부 소스 lib은 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는 프로젝트에 상대적인 디렉터리 경로로, 그 존재 여부가 prep이 필요한지 결정해요(존재하면 prep이 끝난 것).

:alias

:alias는 prep 동안 -T로 호출할 키워드 별칭이에요.

:fn

:fn은 prep 동안 -T로 호출할 함수예요.

러닝타임 베이시스 (Runtime basis)

러닝타임 베이시스는 Clojure 런타임이 시작될 때 의존성 환경의 표현이에요. 의존성, 클래스패스, 베이시스가 어떻게 만들어졌는지에 대한 정보를 포함해요.

러닝타임 베이시스는 Clojure 안에서 clojure.java.basis API를 사용해 접근할 수 있어요. 초기 베이시스와 현재 베이시스 모두에 대한 접근을 포함하며, 후자는 add-libs와 관련 함수로 수정될 수 있어요.

러닝타임 베이시스 속성 인덱스:

{;; 베이시스는 병합된 deps.edn의 상위집합이므로
 ;; 이 모든 속성에 더해 다음을 포함할 수 있음

 ;; 프로젝트 경로
 :basis-config {:dir "project/dir"
                :root    :standard|path|map
                :user    :standard|path|map
                :project :standard|path|map
                :extra   path|map

                :aliases [:alias1 ...]
                :args    {arg val}}
 :argmap {arg val}
 :libs {lib coord}
 :classpath {classpath-path classpath-info}
 :classpath-roots [classpath-path ...]}

:basis-config

:basis-config 속성은 베이시스가 만들어질 때 사용된 파라미터를 포함하며, 나중에 베이시스를 재생성하기에 충분해야 해요. 이 성질은 특히 sync-deps가 사용해요.

:basis-config는 다음 속성을 가질 수 있어요:

:dir — 프로젝트 디렉터리(프로젝트 deps.edn 포함)에 대한 절대 또는 상대 경로, 기본값은 현재 디렉터리
:root — 루트 deps.edn 소스: :standard(클래스패스에서 읽음), 경로, 또는 리터럴 맵 중 하나
:user — 사용자 deps.edn 소스: :standard(사용자 설정 디렉터리에서 읽음), 경로, 또는 리터럴 맵 중 하나
:project — 프로젝트 deps.edn 소스: :standard(:dir에서 읽음), 경로, 또는 리터럴 맵 중 하나
:extra — 추가 deps.edn 소스: 경로 또는 리터럴 맵
:aliases — argmap 키를 제공하는 제공된 별칭 키워드의 벡터
:args — 별칭 argmap이 병합된 후 적용되는 추가 argmap 인자의 맵

:argmap

베이시스 :argmap은 의존성을 해석하고 클래스패스를 계산할 때 사용된 병합된 argmap을 포함해요. argmap은 :aliases로 간접적으로 또는 베이시스를 만들 때 :args 키로 직접 제공될 수 있어요.

argmap 인자 전체 목록과 그 동작은 Clojure CLI 레퍼런스 페이지를 참조해요.

:libs

베이시스 :libs 키는 베이시스 클래스패스에 포함된 직접·전이 의존성 모두의 맵이에요. :libs 값은 lib 이름(한정 symbol)에서 추가 키가 있는 lib 좌표로의 맵이에요. 대부분의 키는 비-규범적이지만, 중요한 추가 키 하나는 이 lib에 대해 클래스패스에 추가할 파일 경로의 :paths 벡터예요.

:classpath

:classpath 키는 키가 클래스패스 경로(문자열)이고 값이 그 경로가 포함된 이유를 서술하는 맵이에요. 가장 흔히 소스 경로의 :path-key 키가 있는 맵 대신, lib의 :lib-name 키가 있는 맵이에요.

:classpath-roots

:classpath-roots 키는 클래스패스를 정렬하는 벡터예요(경로 문자열은 :classpath 키의 키와 일치해야 함). 정렬 규칙은 클래스패스 구성에 관한 Clojure CLI 섹션을 참조해요.

deps.edn 레퍼런스