ARCHIVED

Ideas explored in this first attempt flourished into a new paradigm. The new version of Maestro is maintained in the public monorepo of Protosens SRL, itself managed using Maestro and a growing collection of related tools and plugins.

Leveraging Clojure Deps and Babashka, managing a repository hosting any number of projects becomes a breeze.

This tools aims to provide a reasonable and flexible solution focusing on:

• Building the exact classpath that is needed, for the required purposes, nothing more, nothing less
• Pinning external dependencies, avoiding any duplication
• Promoting documentation of repository structure and overview

In essence, the idea is to use one deps.edn alias for any unit of source: external libraries, internal ones, projects in the repository, etc.

This principle is demonstrated in this repository's own ./deps.edn file. One can see that aliases are namespaced with recognizable names: :ext/kaocha for the alias importing Kaocha, :project/core for core utilities, project/kaocha for utilities targetting Kaocha, etc.

By being so granular and by providing a way for an alias to require other aliases, it becomes surprisingly simple to build arbitrarily complex projects and provide a plethora of useful features.

The namespaces of this ./deps.edn file's aliases are mostly arbitrary. One can choose whatever describes best the organization of a repository. We recommend:

Alias data in :aliases of ./deps.edn, besides conventional keys like :extra-paths, may contain:

During dev mode, if :dev+ is not supplied, the namespace of the alias is replaced with "dev" in an attempt to find a related dev alias. For instance: :project/foo -> :dev/foo. Similarly for testing, replacing the namespace with "test".

Those are the only existing special treatments at the level of namespaces since those use cases are so common. Any other structure is at the liberty of the user.

Given that kind of organization, this tool offers common tasks which are especially convenient when called as Babashka tasks.

The best examples is this repository's own bb.edn file which lists all currently available tasks and where to find them. The API has been designed to be flexible so that if defaults are not enough, users can hack around. Namespaces of interest: helins.maestro, helins.maestro.cmd.

Cloning/forking this repository, inspecting deps.edn and bb.edn, and trying things out should quickly provide an idea of how well the principle can scale.

Defaults are sufficient for most use cases. Starting a Clojure process is very similar to using Clojure CLI. For instance:

# Starting core project in dev mode + my own personal :nrepl alias
$ bb dev :project/core:nrepl

# Testing the Kaocha project and all the aliases it requires
$ bb test :project/kaocha

# Testing the Kaocha project only, not test paths for transitive projects
$ bb test:narrow :projeect/kaocha

# Printing classpath for core in dev mode, '-A' is mentioned explicitly
$ bb dev -A:project/core -Spath | bb cp

This abstraction allows a dependency to change shape when needed. A common example is requiring a local dependency during dev but an external one in production. For instance, :project/kaocha requires :project/core. During development, local files are needed but when building a release jar, :project/kaocha should not package :project/core. Instead, it should link to the :project/core package deployed on Clojars.

This is why the following figures in the alias data of :project/kaocha:

{:maestro/require [:ext/kaocha
                   {default :project/core
                    release :release/core}]}

Instead of a mere alias, there is a map containing both options: :project/core provides extra paths if the default target is activated while :release/core provides an extra dep if the release target is activated.

Babashka tasks that accepts aliases also optionally take a target (default by default). For instance, building a release jar for :project/kaocha:

$ bb jar release :project/kaocha

Support for common tools and PRs are welcome.

Plugins provide Babashka tasks which integrates common tools with Maestro. Currently, document does not build on Cljdoc. However, namespaces are well-documented.

Currently:

Plugin	Purpose	Clojars
Depstar	Jarring and uberjarring
Kaocha	Running tests

More features can be imagined: printing documentation for aliases, sorting and filtering them using tags, pulling not only required aliases by X but also aliases that rely on X for complex integration tests, etc.

Ideas and PRs welcome, and happy hacking ;)

Copyright © 2021 Adam Helinski and Contributors

Licensed under the term of the Mozilla Public License 2.0, see LICENSE.