main
dev

tools-licenses

A Clojure tools.build task library for interrogating your project's dependencies' licenses. Somewhat inspired by the (discontinued) lein-licenses Leiningen plugin, but with the added benefit of canonicalisation to SPDX License Expressions.

It also provides the ability to check your (Apache-2.0 licensed) project against the Apache Software Foundation's 3rd Party License Policy.

Disclaimer

The author and contributors to tools-licenses are not lawyers, and neither they nor tools-licenses itself provide legal advice. This is simply a tool that might help you and your legal counsel perform licensing due diligence on your projects.

Tasks

1. licenses - attempt to display the licenses used by all transitive dependencies of the project
2. check-asf-policy - attempt to check your project's probable compliance (or not) with the ASF's 3rd Party License Policy

Why not tools.deps' built-in license detection?

tools.deps' license discovery logic (provided via the command clj -X:deps list) has several serious shortcomings, including:

• It only scans Maven POM files for license information, and silently ignores projects that don't have license tags in their POM file, or don't have a POM file at all. This is a problem because:
  • git dependencies (whose use is encouraged by tools.deps/tools.build) don't need a POM file (and in practice most don't provide one)
  • Clojars only recently started mandating license information in the POM files it hosts, and as of mid-2023 around 1/3 of all projects deployed hosted there do not include any licensing information in their POM files
• It's coupled to tools.deps and cannot easily be consumed as an independent library. It's also dependent on tools.deps state management (e.g. requires POM files to be downloaded locally).
• It doesn't canonicalise license information to SPDX License Expressions (it leaves canonicalisation, a fairly difficult problem, to the caller).

In contrast, tools-licenses leverages the lice-comb library, a build-tool-agnostic library that takes a more comprehensive approach to license detection.

Usage

Documentation

API documentation is available here, or here on cljdoc.

FAQ is available here.

Adding the tasks to your tools.build script

Add the tool as a Maven dependency to your deps.edn, in your build alias:

  :aliases
    :build
      {:deps {com.github.pmonks/tools-licenses {:mvn/version "LATEST_CLOJARS_VERSION"}}  ; Or use "RELEASE" to blindly follow the latest release of the tool
       :ns-default your.build.ns}

Require the namespace in your tools.build script (typically called build.clj), and add task functions that delegate to the tool:

(ns your.build.ns
  (:require [tools-licenses.tasks :as lic]))

(defn licenses
  "Attempts to list all licenses for the transitive set of dependencies of the
  project, as SPDX license expressions."
  [opts]
  (lic/licenses opts))

(defn check-asf-policy
  "Checks this project's dependencies' licenses against the ASF's 3rd party
  license policy (https://www.apache.org/legal/resolved.html).

  Note: only meaningful if this project is Apache-2.0 licensed."
  [opts]
  (lic/check-asf-policy opts))

Using the tasks from the command line

licenses task

Example summary output:

$ clj -T:build licenses

This project: Apache-2.0

License Expression                                           # of Deps
------------------------------------------------------------ ---------
Apache-2.0                                                          61
BSD-3-Clause                                                         1
CDDL-1.1                                                             1
EPL-1.0                                                             25
EPL-2.0                                                              5
GPL-2.0-only WITH Classpath-exception-2.0                            1
Public domain                                                        1
MIT                                                                  7
No licenses found                                                    1

If you see Unlisted (<some text>) licenses in the output, please raise an issue here.

Other invocation possibilities:

• clj -T:build licenses :output :summary - the default (see above)
• clj -T:build licenses :output :detailed - detailed per-dependency license information
• clj -T:build licenses :output :edn - detailed per-dependency license information in EDN format
• clj -T:build licenses :output :explain :dep <dep symbol> - an explanation of how the tool arrived at the given license(s) for a single dep (expressed as a tools.dep symbol). For example:

$ clj -T:build licenses :output :explain :dep org.clojure/clojure
Dependency: org.clojure/clojure
Licenses: EPL-1.0

EPL-1.0 Concluded
    Confidence: high
    Strategy: SPDX listed name (case insensitive match)
    Source:
      org.clojure/clojure@1.11.1
      /Users/pmonks/.m2/repository/org/clojure/clojure/1.11.1/clojure-1.11.1.pom
      <licenses><license><name>
      Eclipse Public License 1.0

check-asf-policy task

Example summary output:

$ clj -T:build check-asf-policy

ASF Category                  # of Deps
----------------------------- ---------
Category A                           69
Category A (with caveats)             1
Category B                           27
Creative Commons Licenses             0
Category X                            0
Uncategorised                         1

Other invocation possibilities:

• clj -T:build check-asf-policy :output :summary - the default (see above)
• clj -T:build check-asf-policy :output :detailed - detailed per-dependency ASF category information
• clj -T:build check-asf-policy :output :edn - detailed per-dependency ASF category information in EDN format

Contributor Information

Contributing Guidelines

Bug Tracker

Code of Conduct

Developer Workflow

This project uses the git-flow branching strategy, with the caveat that the permanent branches are called main and dev, and any changes to the main branch are considered a release and auto-deployed (JARs to Clojars, API docs to GitHub Pages, etc.).

For this reason, all development must occur either in branch dev, or (preferably) in temporary branches off of dev. All PRs from forked repos must also be submitted against dev; the main branch is only updated from dev via PRs created by the core development team. All other changes submitted to main will be rejected.

Build Tasks

tools-licenses uses tools.build. You can get a list of available tasks by running:

clojure -A:deps -T:build help/doc

Of particular interest are:

• clojure -T:build test - run the unit tests
• clojure -T:build lint - run the linters (clj-kondo and eastwood)
• clojure -T:build ci - run the full CI suite (check for outdated dependencies, run the unit tests, run the linters)
• clojure -T:build install - build the JAR and install it locally (e.g. so you can test it with downstream code)

Please note that the deploy task is restricted to the core development team (and will not function if you run it yourself).

License

Copyright © 2021 Peter Monks

Distributed under the Apache License, Version 2.0.

SPDX-License-Identifier: Apache-2.0