alembic

Repository · Issues · API docs · Annotated source · Release Notes

Alembic is a clojure library that allows you to distill jars onto your classpath in a running JVM instance. You can use it to add dependencies to a running REPL, either in an ad-hoc fashion, or by reloading your project.clj file.

You can also use it to reload your project.clj file and invoke leiningen tasks.

It uses leiningen and pomegranate to resolve the jars, classlojure to isolate leiningen and its dependencies, and dynapath to modify the classpath.

This means you can use lein and pomegranate without their dependencies interfering with your project classpath. The only dependencies added are classlojure and dynapath - both small libraries with no transitive dependencies.

Project Dependency

To use Alembic with nREPL or any other clojure REPL, you will need to add Alembic to you development dependencies. For a leiningen based project, you can do this by adding it to the :dependencies vector of the :dev profile in project.clj.

:profiles {:dev {:dependencies [[alembic "0.3.2"]]}}

You can enable Alembic on all you projects, by adding it to the :dependencies vector of the :user profile in ~/.lein/profiles.clj.

Usage

Reloading project.clj

If you modify the dependencies in your project.clj file, you can load the modified dependencies with load-project.

This will add all non-conflicting dependency changes. Only new dependencies are considered non-conflicting. New versions of existing dependencies are not loaded. Removed dependencies are not unloaded.

Adding Ad-Hoc Dependencies

To add a dependency to the classpath, use the distill function, passing a leiningen style dependency vector.

(alembic.still/distill '[org.clojure/tools.logging "0.3.2"])

You can pass a sequence of dependencies to add, or just a single dependency as in the example above.

distill prints the dependencies added to the classpath, and those not added due to conflicts.

The distill function returns with no side-effects, if the dependency's jars are already on the classpath.

By default, distill uses the repositories in the current lein project. You can override this by passing a map of lein style repository information to the :repositories option. The project-repositories function can be used to obtain the lein project repositories, should you want to adapt these to pass as an :repositories argument.

For programmatic use, distill* returns a sequence of maps, where each map represents a dependent jar. Those jars without a current version on the classpath will be added to the classpath. The jars with a version already on the classpath are not added to the classpath, and the currently loaded version is reported on the :current-version key.

You can query the dependencies that have been added with the dependencies-added function, which returns a sequence of leiningen style dependency vectors.

You can lookup the dependency jars for the distilled dependencies, using the dependency-jars function.

The conflicting-versions function returns a sequence of dependencies for a distilled dependency, where the dependency jar version doesn't match the version currently on the classpath.

Invoking Leiningen Tasks

The lein macro invokes leiningen. For example, to show your project's dependency tree, you could run:

(alembic.still/lein deps :tree)

The macro allows you to invoke tasks without passing string arguments. If you need to call lein functionally, use the lein* function instead.

Configuring User Profile with Injections

You can reduce the amount of typing you need to use alembic by using the lein-shorthand plugin and configuring your :user profile in ~/.lein/profiles.clj.

{:user
  {:dependencies [[alembic "0.3.2"]]
   :plugins [[com.palletops/lein-shorthand "0.4.0"]]
   :shorthand {. [alembic.still/distill alembic.still/lein]}}}

This will define the . namespace, so you can run (./lein deps :tree).

Support and Discussion

Discussion of alembic, either on the clojure-tools google group, or on #clojure or #pallet on freenode IRC.

License

Copyright © 2013 Hugo Duncan

Distributed under the Eclipse Public License.