README.adoc

tools.build’s missing piece

1. Add to your deps.edn:

   deps.edn

   :aliases {;;; Tools
             :build {:deps       {com.github.gnl/build.simple {:mvn/version "x.x.x"}}
                     :ns-default build.simple.core}}

2. Create a project.edn file in your project’s root directory

   ℹ️	All supported keys are documented in the config file linked above. build.simple tries to follow the "configurability is the root of all evil" design principle.

3. Install Maven 3.x+ (build.simple uses it for deployment), and set it up to get the Clojars (or other repository) credentials from the environment:

   ~/.m2/settings.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">
     <servers>
       <server>
         <id>clojars</id>
         <username>${env.clojars_username}</username>
         <password>${env.clojars_password}</password>
       </server>
     </servers>
   </settings>

4. clj -T:build [install|deploy|jar|pom|clean] [:check false] [:sign false]

ℹ️

When deploying a non-snapshot artifact, deploy performs a number of sanity checks by default (clean working directory, correct git version tag, etc.), and signs it. It securely prompts for repository credentials as needed, and passes them to Maven via the environment; GPG-signing and passphrase handling are fully delegated to gpg-agent (you should probably use a graphical pinentry interface for this to work reliably).

💡

If you have special requirements, build.simple can be a good starting point or foundation for rolling your own tools.build solution – feel free to call into it from your code and add your own keys to project.edn if you just want to add some minor functionality on top without writing everything from scratch.

Why

While I consider tools.build to be an improvement in a number of ways – straightforward dependency resolution, no implicit behaviour/magic profiles, greater flexibility – I do miss Leiningen’s easy basic workflow of 1. bump version/edit metadata in project.clj → 2. lein install jar locally for testing → 3. lein deploy clojars.

Performing the same tasks with tools.build involves some combination of: creating and editing a verbose pom.xml template file (before 0.9.6’s :pom-data, anyway); syncing dependencies from deps.edn; choosing between multiple separate solutions for deployment, most of which handle the GPG and/or Clojars credentials in various rather convoluted and insecure ways; directly calling Maven; and writing some code to tie it all together.

I have no intention of reinventing Leiningen here, and am inclined to view the project as more or less feature-complete. build.simple is meant to cover the 95% use case of a library author, and I would generally recommend using tools.build directly for anything else.

Projects using build.simple

• gnl/playback

Similar projects

• liquidz/build.edn has been around for quite a bit longer and takes a very similar approach to making the tools.build experience more pleasant. I wasn’t aware of it when I wrote and released build.simple. build.edn has more features, more configurability, more (relative) complexity, a non-prompting approach to credentials handling, and no artifact signing (at the time of writing). build.simple also stays a little closer to tools.build in its configuration – all keys related to the latter’s API are directly passed through to it.

Copyright (c) 2023 George Lipov
Licensed under the Eclipse Public License 2.0