
=head1 NAME

dh-clojure-lein - Debhelper support for Leiningen projects

=head1 DESCRIPTION

Support for Leiningen projects consists of a Debhelper build system,
available via the B<dh> B<--buildsystem> argument, and support for
automatic and customizable adjustments to projects.

Currently under development, and should not be considered stable until
(at least) the C<:debian.dh-clojure-lein/version> is no longer 0 and
this notice changes.

=head1 USAGE

=head2 Buildsystem

The build system is designed to facilitate packaging Leiningen-based
Clojure projects for Debian, and can be activated by passing the
B<--buildsystem=leiningen> option to B<dh>:

 %:
    dh $@ --buildsystem=leiningen

It takes action during these debhelper stages:

=over

=item B<configure>

Sets up a debian/dh-clojure/tmp/maven-repo symlink pointing to
/usr/share/maven-repo for use by lein as a :local-repo.

=item B<build>

Creates a debian/dh-clojure/tmp/pom.xml for use in the debian/PACKAGENAME.poms
file (which it also creates), and it creates an unversioned symlink in target/
for the jar.

=item B<install>

Calls helpers from the B<maven-repo-helper> package to install the
built jars into /usr/share/java and poms and jar symlinks in
/usr/share/maven-repo and generate the ${maven:Depends} substitution
variable.

=item B<test>

Runs C<lein test>.

=item B<clean>

Runs C<lein clean> and cleans up after the previous steps.

=back

=head2 Project Adjustment (middleware)

The Leiningen F<project.clj> will be adjusted by a middleware injected
by the buildsystem (see above).  By default, it will set all of the
dependency versions in the project to "debian", excepting
C<org.clojure/clojure>, which will be set to "1.x".

The project adjustments may be customized via a configuration read
from F<debian/dh-clojure-lein.edn> which must contain a single EDN map
like this:

 {:debian.dh-clojure-lein/version 0
  :project
  {org.clojure/tools.cli
   {:edit
    {:version [= "1.x"]
     :plugins -
     :dependencies
     [[= [org.clojure/clojure "1.x"]]
      ...]}}}}

The C<:edit> entries specify changes for B<lein> to make to the
project map of the given C<:project> (here just
C<org.clojure/tools.cli>) when running commands.  Each C<:project> map
key that is not C<:dependencies>, C<:managed-dependencies>, or
C<:plugins> may may be associated with one of the following forms:

=over

=item C<[= I<VALUE>]>

the value for the key will be set to VALUE (the key must have an
existing value)

=item C<[+ I<VALUE>]>

the value for the key will be set to VALUE (the key must not have an
existing value)

=item C<->

the key will be removed

=back

The C<:dependencies>, C<:managed-dependencies>, and C<:plugins> are
handled differently.  They may specify a vector of forms describing
alterations to the project dependencies like this:

=over

=item C<[+ I<DEP_SPEC>]>

the dependency will be added (it must not be present in the original
project)

=item C<[= I<DEP_SPEC>]>

the dependency will be adjusted (it must be present in the original
project)

=item C<[- I<DEP_KEY>]>

the dependency will be removed (it must be present in the original
project)

=back

A I<DEP_KEY> is the subset of a lein project dependency vector that
uniquely identifies a dependency, either a symbol like
C<org.clojure/tools.cli> or a a lein project dependency vector
starting with that symbol, optionally followed by a C<:classifier>,
and/or C<:extension>, for example C<[org.clojure/tools.cli :classifier
"test"]>.

A I<DEP_SPEC>s is a lein project dependency vector with the exception
that it may omit the version, for example C<[org.clojure/tools.cli
"1.x"]> or C<[org.clojure/tools.cli :classifier "test"]>.

For the C<=> operator, any I<DEP_SPEC> components provided will
change the corresponding value in the project, and setting the
component to nil will delete it from the dependency.

Note that unless otherwise specified, the default value for all
dependencies will be set to either C<"debian">, or for
C<org.clojure/clojure>, to "1.x".

=head1 FILES

F<debian/dh-clojure-lein.edn>

=head1 SEE ALSO

L<dh-clojure(7)>, L<dh(1)>, L<lein(1)>, and L<http://edn-format.org/>
