Liking cljdoc? Tell your friends :D

Libraries

When we talk about poly libraries, we refer to 3rd-party library dependencies used by components, bases, and projects. For poly brick dependencies, see Dependencies.

The poly tool parses deps.edn files throughout your workspace to resolve 3rd-party library dependencies, which it uses for the libs and test commands.

Tutorial Setup

We explored brick dependencies using the Realworld example app; we’ll continue with the same workspace to explore libraries.

Reporting

Ask poly to report on 3rd-party libraries:

poly libs
libs

Notice that poly has reported on library usage across all:

  • projects in purple - rb is the alias for the realworld-backend project, and dev is the alias for the development project. The dependencies for a project also include the dependencies for its bricks. If different versions of a library are referenced, poly will use the latest version of that library.

  • components in green

  • bases in blue

An x means that the library is used from the src context, and t means that it’s only used from the test context.

The type column describes where the library is hosted. See Library Dependency Types.

The KB column shows the size of each library in kilobytes. A - means poly could not calculate the library size because either:

One way to force libraries to download is to run the following from your workspace root:

clojure -A:dev:test -P

If your workspace has many bricks, you may prefer a more compact report format. You can either set :compact-views to #{"libs"} in your workspace.edn or specify the :compact argument:

poly libs :compact
libs compact

Updating

You can list outdated libraries:

poly libs :outdated

Your output will differ. Here’s an example output where some libraries were out of date:

libs outdated

You can ask poly to update all libraries to the latest version in all deps.edn for all bricks and projects via:

poly libs :update

To update specific libraries:

poly libs :update libraries:djblue/portal:com.taoensso/timbre
When using the shell, poly will, after a short pause, offer autocomplete suggestions for libraries!

To skip updating specific libraries, specify :keep-lib-versions in your workspace.edn, e.g.:

{...
 :bricks {"article" {:keep-lib-versions [djblue/portal]}}}
 :projects {"realworld-backend" {:alias "rb"
                                 :keep-lib-versions [clj-jwt/clj-jwt clj-time/clj-time]}

Library Dependency Types

You can specify libraries in three ways in tools.deps deps.edn files:

TypeDescription

Maven

As a Maven dependency, e.g.:

clj-time/clj-time {:mvn/version "0.15.2"}

The key is the Maven groupId/artifactId. Maven artifacts are stored by default under ~/.m2/repositories/ (configured via :m2-dir).

Local

As a local dependency, e.g.:

clj-time {:local/root "/local-libs/clj-time-0.15.2.jar"}

The key is an arbitrary identifier. A local dependency is a path to a local jar file or directory.

See also: Local Dependencies.

Git

As a Git dependency, e.g.:

clj-time/clj-time {:git/url "https://github.com/clj-time/clj-time.git",
                   :sha "d9ed4e46c6b42271af69daa1d07a6da2df455fab"}

The poly tool will calculate the KB column for a Git dependency, only if the key path matches the path for the libary under ~/.gitlibs/libs (the Git owner and repo from the :git/url).

Configuration

3rd-party library dependencies are specified in deps.edn for each component, base, and project:

EntityFileScopeLocation in File

Components

components/COMPONENT-DIR/deps.edn

src

:deps

test

:aliases > :test > :extra-deps

Bases

bases/BASE-DIR/deps.edn

src

:deps

test

:aliases > :test > :extra-deps

Deployable projects

projects/PROJECT-DIR/deps.edn

src

:deps

test

:aliases > :test > :extra-deps

Development project

./deps.edn

src

:aliases > :dev > :extra-deps

test

:aliases > :test > :extra-deps

Local Dependencies

Distinguishing from Bricks

You’ll remember that you also specify bricks and projects as :local/root dependencies. The poly tool distinguishes brick dependencies from local 3rd-party library dependencies by their paths. The poly tool understands that when a :local/root path starts with:

  • ../../bases/ or ../../components/ for deployable projects

  • or bases/ or components/ for the development project

that it is a poly brick dependency; otherwise, it is considered a 3rd-party library dependency.

Differences from Tools.deps

When using the tools.deps CLI (i.e. clojure or clj), :local/root dependencies only inherit :src dependencies; :test dependencies are ignored. The poly tool builds upon tools.deps but has its own test runner that it invokes for the test command. Unlike the tools.deps CLI, the poly also inherits dependencies from the test context for :local/root dependencies.

If you want to run your tests directly from a project using the tools.deps CLI tool, you must duplicate test library dependencies from the bricks to the project’s deps.edn file under :aliases > :test > :extra-deps. If you only run tests with the built-in test command, you don’t have to worry about this.

Project Library Dependencies

The library dependencies for a project are the sum of all library dependencies that are indirectly included via its bricks, together with dependencies declared by the project itself. If different versions of the same library dependency exist, then poly will use the latest version.

You can override the library version used for a project in its deps.edn file. For example:

./projects/realworld-backend/deps.edn
{...
 :deps {poly/article  {:local/root "../../components/article"}
        poly/comment  {:local/root "../../components/comment"}
        poly/database {:local/root "../../components/database"}
        ...

 :override-deps {clj-time/clj-time {:mvn/version "0.15.1"}} (1)
 ...
}
1Override version of clj-time/clj-time for this project

If you re-run the libs command:

libs override

Notice that two versions of clj-time are listed and that the realworld-backend project now uses version 0.15.1.

You can override project library dependencies for projects via :override-deps in the following places:

EntityFileScopeLocation in File

Deployable projects

projects/PROJECT-DIR/deps.edn

src

:override-deps

test

:aliases > :test > :override-deps

Development project

./deps.edn

src

:aliases > :dev > :override-deps

test

:aliases > :test > :override-deps

Overriding a library in the src scope will also affect the test scope. If you override a library in the test scope, it will only affect the test scope.

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close