Commits

Meikel Brandmeyer committed 04bdd2d

Update documentation for new release

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
-`src/main/clojure/test/example.clj`:
+## 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: 'http://clojars.org/repo'
         }
         dependencies {
-            classpath name: 'clojuresque'
+            classpath 'clojuresque:clojuresque:1.2.0'
         }
     }
     
-    usePlugin(de.kotka.gradle.ClojurePlugin)
+    group = 'example.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
+  SNAPSHOT.
+* 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}/plugin.properties`:
 
-    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/gradle.properties`.
+
+    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 <mb@kotka.de>
-Frankfurt am Main, November 2009
+Frankfurt am Main, December 2009
 
 [Gradle]: http://www.gradle.org
 [Groovy]: http://groovy.codehaus.org
 [clj]:    http://clojure.org
 [cg]:     http://bitbucket.org/kotarak/clojuresque
+[cr]:     http://clojars.org
+[hudson]: http://build.clojure.org
+[antbug]: https://issues.apache.org/bugzilla/show_bug.cgi?id=41090
+[aot]:    http://groups.google.com/group/clojure/browse_thread/thread/6cef4fcf523f936/3cfe17ba2d2a8a23
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.