release
dev

PBR - Peter's Build Resources

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.

Why?

Because "vanilla" tools.build build scripts impose a lot of unnecessary repetition when one is working on lots of separate projects that need to have the same set of build tasks. A more detailed explanation of the problem is here.

Why not clein or build.edn?

These projects look very promising - I encourage folks to try them out and contribute to them!

Why not build-clj?

Discontinued February 2023.

Features

Task library

PBR includes a library of tools.build tasks that are documented here. These may be used independently of the turnkey build script described next.

Turnkey build script

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 include:

• check - Check the code by AOT compiling it (and throwing away the result). Uses clj-check.
• 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 (using deps-deploy).
• docs - Generates documentation (using codox).
• eastwood - Run the eastwood linter.
• install - Install the library locally e.g. so it can be tested by downstream dependencies
• jar - 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 expressions, using tools-licenses.
• lint - Run all linters.
• nvd - Run an NVD vulnerability check. NOTE: requires an API key from here.
• outdated - Check for outdated dependencies, using antq.
• pom - Generates a comprehensive pom.xml for the project, using tools-pom
• 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!

deps.edn required by turnkey build script

To use the turnkey build script, include the following alias in your project's deps.edn:

{:deps { ; Your project's dependencies
       }
 :aliases {:build {:deps        {com.github.pmonks/pbr {:mvn/version "RELEASE"}}
                   :ns-default  pbr.build}}}

Then, to run tasks, use:

$ clojure -T:build <task-name>

A list of all available tasks can be obtained with:

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

Note: you do not need to include the pbr.build namespace when referring to a task by name.

Preparing to build with the turnkey build script

To prepare your project to use the turnkey build script, you must run the following command first:

$ clj -A:build -P

FAQ

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.

Contributor Information

Contributing Guidelines

Bug Tracker

Code of Conduct

Developer Workflow

This project uses the git-flow branching strategy, and the permanent branches are called release and dev. Any changes to the release 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 release branch is only updated from dev via PRs created by the core development team. All other changes submitted to release will be rejected.

Build Tasks

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 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