Meikel Brandmeyer committed 04bdd2d

Update documentation for new release

  • Participants
  • Parent commits 6f5e144

Comments (0)

Files changed (1)

   first in the file. Comments may precede the form. The symbol is allowed
   to be fully qualified: `clojure.core/ns`.
-## Getting started
+* In order for the scp deployment of [Clojars][cr] to work, you have to
+  replace the jsch jar in `${{GRADLE_HOME}/lib` with jsch-0.1.29.jar.
+  Otherwise the transfer might hang.  See this [ant bug][antbug] for more
+  information.
-Create a sandbox directory. Add a subdirectory `lib` and put the `clojure.jar`
-as well as the `clojuresque.jar` there. Create some test namespace in
+## Usage
-    (ns test.example
-      (:gen-class))
-    (defn -main
-      []
-      (println "Hello, World!"))
-Now create the `build.gradle` script:
+Create a `build.gradle` script in the root directory of your project. *Note
+that gradle derives the project name from the name of this directory!*
     buildscript {
         repositories {
-            flatDir name: 'lib', dirs: 'lib'
+            mavenRepo name: 'clojars', urls: ''
         dependencies {
-            classpath name: 'clojuresque'
+            classpath 'clojuresque:clojuresque:1.2.0'
-    usePlugin(de.kotka.gradle.ClojurePlugin)
+    group = ''
+    version = '1.0.0'
-    repositories {
-        flatDir name: 'lib', dirs: 'lib'
+    usePlugin(cojuresque.ClojurePlugin)
+    warnOnReflection = true
+    aotCompile = true
+    clojureSnapshotsRepo(repositories)
+    clojarsRepo(repositories)
+    gradleHomeRepo(repositories)
+    dependencies {
+        compile 'org.clojure:clojure:1.1.0-master-SNAPSHOT'
-    configurations {
-        compileOnly {
-            visible = false
-            transitive = false
-        }
-        compile.extendsFrom(compileOnly)
-    }
-    dependencies {
-        compileOnly name: 'clojuresque'
-        compile name: 'clojure'
-    }
+    configureClojarsDeploy(uploadArchives)
-This looks rather verbose, but I hope to simplify it later on. First we
-declare a dependency (and where to find it) for the build script itself.
-This is necessary, since the we need the plugin already to define the build
-logic itself.
+A small walkthrough:
-Next we define the repositories and dependencies for the project being
-build. Since we need the `ClojureCompile` class from the `clojuresque.jar`
-in the classpath for compilation we introduce a special `compileOnly`
-configuration. It's private the finally deployed archives of the project
-won't depend on it at runtime. Additionally we add a dependency on the
-new configuration to the pre-defined `compile` configuration.
+* The `buildscript` part defines a dependency and automatically fetches
+  clojuresque from Clojars.
+* The `group` and `version` properties define the respective attributes of
+  your project. They are required for the POM generation.
+* `usePlugin` basically loads the clojure plugin.
+* `warnOnReflection` turns on the reflection warnings of the clojure compiler
+* `aotCompile` specifies whether to produce a source jar or an AOT compiled
+  jar. The default is produce a source jar, because they also tend to be
+  smaller. [This issue was discussed on the Google group.][aot]
+* `clojureSnapshotsRepo` tells gradle where to find the clojure and contrib
+  snapshots, ie. where it can find the [Hudson server][hudson].
+* `clojarsRepo` adds the [Clojars Repository][cr] in a similar way.
+* `gradleHomeRepo` is used to add `${GRADLE_HOME}/lib` as a local repository.
+  This is useful to minimise the download of the scp ant task dependencies.
+  *Note that `GRADLE_HOME` must be set for this to work!* *Note, that this
+  must come before a possible `mavenCentral()`!*
+* In the `dependencies` section we add a dependency on the current master
+* Last but not least: `configureClojarsDeploy` configures the given `Upload`
+  task to deploy to the [Clojars Repository][cr]
-Now build the project with `gradle build` and test the result:
+This can be even more simplified by registering clojuresque with your local
+Gradle installation. Put the clojuresque jar in `${GRADLE_HOME}/lib` and add
+the following line to `${GRADLE_HOME}/`:
-    ceres:..gradle-plugin/test% java -cp lib/clojure.jar:build/libs/test-unspecified.jar test.example
-    Hello, World!
-    ceres:..gradle-plugin/test%
+    clojure=clojuresque.ClojurePlugin
-Please note, that the name of the generated jar depends on how you named
-the sandbox directory.
+From now on you can skip the whole `buildscript` stuff and just use
+`usePlugin('clojure')` to load the plugin.
+## Clojars Deployment
+Additional to configuration of the `Upload` tasks with `configureClojarsDeploy`
+you also have to specify the location of the keyfile and the passphrase you
+use to access [Clojars][cr]. This can be done independent of the projects
+in a file called `${HOME}/.gradle/`.
+    clojarsKeyfile = /Users/mb/.ssh/id_dsa
+    clojarsPassphrase = My super secret passphrase
+**Be sure to correctly secure this file! Or your key might be compromised!**
 ## Issues
 Meikel Brandmeyer <>
-Frankfurt am Main, November 2009
+Frankfurt am Main, December 2009