https://github.com/gnl/build.simple

tools.build's missing piece – install, sign and deploy libraries easily and securely like with Leiningen
https://github.com/gnl/build.simple

build-tool clojars clojure clojurescript deployment leiningen library

Last synced: 3 months ago
JSON representation

tools.build's missing piece – install, sign and deploy libraries easily and securely like with Leiningen

• Host: GitHub
• URL: https://github.com/gnl/build.simple
• Owner: gnl
• License: other
• Created: 2023-10-15T11:57:38.000Z (about 1 year ago)
• Default Branch: master
• Last Pushed: 2023-11-08T20:39:35.000Z (12 months ago)
• Last Synced: 2024-06-21T18:12:00.167Z (5 months ago)
• Topics: build-tool, clojars, clojure, clojurescript, deployment, leiningen, library
• Language: Clojure
• Homepage:
• Size: 26.4 KB
• Stars: 32
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

• awesome-clojure - build.simple

README

        
:linkattrs:

:sectanchors:

ifdef::env-github,env-cljdoc[]

:tip-caption: :bulb:

:note-caption: :information_source:

:caution-caption: :fire:

:warning-caption: :warning:

endif::[]

image:https://img.shields.io/badge/License-EPL%202.0-94A5F5.svg[License,link=https://choosealicense.com/licenses/epl-2.0/]

## tools.build's missing piece

. Add image:https://img.shields.io/clojars/v/com.github.gnl/build.simple.svg[Clojars Project,link=https://clojars.org/com.github.gnl/build.simple] to your `deps.edn`:

+

.deps.edn

[source,clojure]

----

:aliases {;;; Tools

          :build {:deps       {com.github.gnl/build.simple {:mvn/version "x.x.x"}}

                  :ns-default build.simple.core}}

----

+

. Create a https://github.com/gnl/build.simple/blob/master/project.edn[project.edn file] in your project's root directory

+

NOTE: All supported keys are documented in the config file linked above. build.simple tries to follow the https://fishshell.com/docs/current/design.html#configurability-is-the-root-of-all-evil["configurability is the root of all evil"] design principle.

+

. 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

[source,xml]

----

  

    

      clojars

      ${env.clojars_username}

      ${env.clojars_password}

    

  

----

+

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

NOTE: 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).

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

- https://github.com/gnl/playback[gnl/playback]

## Similar projects

- https://github.com/liquidz/build.edn[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.

{empty} +

Copyright (c) 2023 George Lipov +

Licensed under the https://choosealicense.com/licenses/epl-2.0/[Eclipse Public License 2.0]