diff --git a/PLUGINS.md b/PLUGINS.md index 62869ddd5..83604a461 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -74,11 +74,9 @@ to and a function to perform the wrapping: (add-hook #'leiningen.test/test skip-integration-hook) Hooks compose, so be aware that your hook may be running inside -another hook. Hooks are loaded by looking for all namespaces under -leiningen.hooks.* on the classpath and loading them in alphabetical -order. - -TODO: document hook loading +another hook. To take advantage of this functionality, projects must +set the :hooks key in project.clj to a seq of namespaces to load that +call add-hook. See [the documentation for Hooke](http://github.com/technomancy/robert-hooke/blob/master/README.md) diff --git a/README.md b/README.md index 1575f57e3..b6d2f84b0 100644 --- a/README.md +++ b/README.md @@ -54,12 +54,22 @@ project, but here are the commonly-used tasks: $ lein jar # package up the whole project as a .jar file + $ lein install [NAME VERSION] # install a project + Use lein help to see a complete list. lein help $TASK shows the usage for a specific one. -TODO: document chaining tasks +You can also chain tasks together in a single command by using commas: + + $ lein clean, test foo.test-core, jar -TODO: document user-level init script and plugins +Most tasks need to be run from somewhere inside a project directory to +work, but some (new, help, version and the +two-argument version of install) may run from anywhere. + +The install task places shell scripts in the ~/.lein/bin +directory for projects that include them, so if you want to take +advantage of this, you should put it on your $PATH. ## Configuration @@ -79,6 +89,12 @@ appropriate starting point from which you can work. See the [sample.project.clj](http://github.com/technomancy/leiningen/blob/master/sample.project.clj) file for a detailed listing of configuration options. +You can also have user-level configuration that applies for all +projects. The ~/.lein/init.clj file will be loaded every time +Leiningen launches; any arbitrary code may go there. Place jars +containing plugins in ~/.lein/plugins to have them available globally +for the current user. + ## FAQ **Q:** How do you pronounce Leiningen? diff --git a/TUTORIAL.md b/TUTORIAL.md index 3221b00a9..878d0bb37 100644 --- a/TUTORIAL.md +++ b/TUTORIAL.md @@ -238,15 +238,17 @@ of Leiningen projects: * A library * A server-side application -For the first, you will want to build an uberjar. For libraries, you -will want to have them published to a repository like Clojars. For -server-side applications it varies as described below. +For the first, you can either build an uberjar or use a shell-wrapper. +For libraries, you will want to have them published to a repository +like Clojars. For server-side applications it varies as described +below. ### Uberjar -The uberjar task is used to create a standalone, executable -jar. For this to work you'll need to specify a namespace as your :main -in project.clj. By this point our project.clj file should look like this: +The simplest thing to do is to distribute an uberjar. This is a single +standalone executable jar file. For this to work you'll need to +specify a namespace as your :main in project.clj. By this point our +project.clj file should look like this: (defproject myproject "1.0.0-SNAPSHOT" :description "This project is MINE." @@ -293,7 +295,35 @@ You can run a regular (non-uber) jar with the java command-line tool, but that requires constructing the classpath yourself, so it's not a good solution for end-users. -TODO: document shell wrappers +### Shell Wrappers + +There are a few downsides to uberjars. It's relatively awkward to +invoke them compared to other command-line tools. You also can't +control how the JVM is launched. To solve this, you can include a +shell script in your jar file that can be used to launch the +project. Leiningen places this shell script into the +~/.lein/bin directory at install time. + +If you simply include :shell-wrapper true in your +project.clj, Leiningen automatically generates a simple shell script +wrapper when you create your jar file. However, if you need more +control you can provide a map instead: + + :shell-wrapper {:main myproject.core + :bin "bin/myproject"} + +Normally the shell wrapper will invoke the -main function in your +project's :main namespace, but specifying this option triggers AOT for +uberjars, so if you wish to avoid this or use a different :main for +the shell wrapper vs uberjar you can specify a :main ns inside the +:shell-wrapper map. You may also specify a :bin key, which should +point to a file in resources/ directory to use as a shell +wrapper template instead of the default. The format function +is called with the contents of this file along with the necessary +classpath and the main namespace, so put %s in the right place. See +[the default +wrapper](http://github.com/technomancy/leiningen/blob/master/resources/script-template) +for an example. ### Publishing diff --git a/src/leiningen/install.clj b/src/leiningen/install.clj index f6a50fbc7..14df07a07 100644 --- a/src/leiningen/install.clj +++ b/src/leiningen/install.clj @@ -34,7 +34,9 @@ install-shell-wrapper))) (defn install - "Install the project and its dependencies in your local repository." + "With no arguments, installs the current project and its dependencies in +your local repository. With two arguments, downloads and installs a project +from a remote repository. May place shell wrappers in ~/.lein/bin." ([project] (let [jarfile (file (jar project)) model (make-model project) diff --git a/src/leiningen/repl.clj b/src/leiningen/repl.clj index 082f6f4d8..b29b01a3f 100644 --- a/src/leiningen/repl.clj +++ b/src/leiningen/repl.clj @@ -70,8 +70,8 @@ (recur port))) (defn repl - ;; TODO: document socket repl - "Start a repl session for the current project." + "Start a repl session. A socket-repl will also be launched in the +background; use the LEIN_REPL_PORT environment variable to set the port." [project] (let [host (or (System/getenv "LEIN_REPL_HOST") "localhost") port (Integer. (or (System/getenv "LEIN_REPL_PORT") diff --git a/todo.org b/todo.org index 318259612..a605f64c8 100644 --- a/todo.org +++ b/todo.org @@ -8,6 +8,7 @@ Leiningen TODOs * For 1.4.0 or later ** TODO add option to use ~/.m2-based classpath instead of copying to lib/? ** TODO lein add $DEPENDENCY (inserts it into :dependencies in project.clj) +** TODO shell wrappers should support multiple versions ** TODO classifiers for specifying what clojure version to use? ** TODO test classification using metadata; run a subset of tests ** TODO a list of dirs to include in the jar when building