main | ||
dev |
A little tools.build task library and turnkey build script that supports the author's personal GitHub workflow. It is not expected to be especially relevant for other developers' workflows, except perhaps as a model for how tools.build can be (somewhat) tamed when working with multiple independent projects that share common build tasks.
Because "vanilla" tools.build builds impose a lot of unnecessary repetition when one is working on lots of separate projects that have the same build tasks. A more detailed explanation of the problem is here.
PBR includes a library of tools.build tasks that are documented here. These may be used independently of the turnkey build script described next.
PBR also provides a turnkey build.clj
script that provides all of the tasks I typically need in my build scripts. It allows customisation via a per-project pbr.clj
file, which must contain a set-opts
fn where various project specific options can be set. You can look at PBR's own pbr.clj
file for an idea of what this looks like.
Tasks can be listed by running clojure -A:deps -T:build help/doc
, and are:
check
- Check the code by AOT compiling it (and throwing away the result).check-asf-policy
- Checks this project's dependencies' licenses against the ASF's 3rd party license policy (https://www.apache.org/legal/resolved.html).check-release
- Check that a release can be done from the current directory.ci
- Run the CI pipeline.clean
- Clean up the project.deploy
- Deploys the library JAR to Clojars.docs
- Generates documentation (using codox).eastwood
- Run the eastwood linter.install
- Install the library locally e.g. so it can be tested by downstream dependenciesjar
- Generates a library JAR for the project.kondo
- Run the clj-kondo linter.licenses
- Attempts to list all licenses for the transitive set of dependencies of the project, as SPDX license identifiers.lint
- Run all linters.nvd
- Run an NVD vulnerability check.outdated
- Check for outdated dependencies (using antq).pom
- Generates a comprehensive pom.xml for the project.release
- Release a new version of the library.test
- Run the tests.uber
- Create an uber jar.uberexec
- Creates an executable uber jar. NOTE: does not bundle a JRE, though one is still required.upgrade
- Upgrade any outdated dependencies (using antq). NOTE: does not prompt for confirmation!To use the turnkey build script, include the following alias in your project's deps.edn
:
{:deps { ; Your project's dependencies
}
:aliases {:build {:deps {io.github.seancorfield/build-clj {:git/tag "v0.8.2" :git/sha "0ffdb4c"}
com.github.pmonks/pbr {:mvn/version "RELEASE"}}
:ns-default pbr.build
:extra-paths ["src"]}}} ; To appease codox, which is poorly integrated with tools.deps/tools.build...
Note that despite not using it directly, you must express an explicit dependency on io.github.seancorfield/build-clj
in your build alias, as that project doesn't publish artifacts to Clojars and transitive git coordinate dependencies are not supported by tools.deps.
To prepare your project to use the turnkey build script, you must run the following command first:
$ clj -A:build -P
Q. Why "PBR"?
A. Because this code is cheap and nasty, and will give you a headache if you consume too much of it.
Q. Does PBR use itself for build tasks?
A. Yes it does! You can see this sneaky self-reference here.
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.
pbr
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 testsclojure -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).
Copyright © 2021 Peter Monks
Distributed under the Apache License, Version 2.0.
SPDX-License-Identifier: Apache-2.0
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close