diff --git a/README.md b/README.md index ceed9bff..de015edd 100644 --- a/README.md +++ b/README.md @@ -232,8 +232,8 @@ email addresses are not appropriate for bug reports. See the file HACKING.md for more details on how Leiningen's codebase is structured. Patches are preferred as Github pull requests, though patches from -git format-patch are also welcome on the mailing list. Please -use topic branches when sending pull requests rather than committing +`git format-patch` are also welcome on the mailing list. Please use +topic branches when sending pull requests rather than committing directly to master in order to minimize unnecessary merge commit clutter. diff --git a/doc/HACKING.md b/doc/HACKING.md index 158f5ad8..262abfd3 100644 --- a/doc/HACKING.md +++ b/doc/HACKING.md @@ -5,26 +5,50 @@ Leiningen is composed of a few layers. First we have the functionality that would be useful outside the context of Leiningen itself, primarily for IDEs and other tools. This is available independently on [Clojars](http://clojars.org/leiningen-core) and -documented at TODO +[documented on Github](http://technomancy.github.com/leiningen). + +The next layer is `leiningen.main`, which is the launcher responsible +for resolving and calling Leiningen task functions. + +Finally we have the tasks themselves. Tasks are simply functions in +specially-named namespaces: + +```clj +(ns leiningen.pprint + (:require [clojure.pprint :as pp])) + +(defn pprint + "Print a readable representation of the current project." + [project] + (pp/pprint project)) +``` + +The docstring for the task will be used by `lein help`. In particular, +the first line will be used as a summary, so it needs to stand on its +own if you are going to have a longer multi-line explanation. + +## Task Execution When you launch Leiningen, it must start an instance of Clojure to load itself. But this instance must not affect the project that you're building. It may use a different version of Clojure from Leiningen, -and the project should be in a fresh JVM. Leiningen uses ant's -java task to fork off a separate process for this -purpose. The leiningen.compile namespace implements this; -specifically the eval-in-project function. Any code that must -execute within the context of the project (AOT compilation, test runs) -needs to go through this function. +and the project should be in a fresh JVM. Leiningen currently launches +this as a subprocess using `leiningen.core.eval/eval-in-project`. Any +code that must execute within the context of the project (AOT +compilation, test runs) needs to go through this function. The exception to this rule is when :eval-in-leiningen in project.clj is true, as is commonly used for Leiningen plugins. -TODO: what goes where? a tour through the launching of a task - Leiningen is extensible; you can define new tasks in plugins. Add your plugin as a dev-dependency of your project, and you'll be able to call -lein $YOUR_COMMAND. See the [plugins guide](https://github.com/technomancy/leiningen/blob/stable/doc/PLUGINS.md) for details. +lein $YOUR_COMMAND. + +See the +[plugins guide](https://github.com/technomancy/leiningen/blob/stable/doc/PLUGINS.md) +for details. + +## Contributing The [mailing list](http://groups.google.com/group/leiningen) and the leiningen or clojure channels on Freenode are the best places to diff --git a/src/leiningen/help.clj b/src/leiningen/help.clj index cfaef0fb..58c5ab2f 100644 --- a/src/leiningen/help.clj +++ b/src/leiningen/help.clj @@ -41,8 +41,7 @@ (let [subtasks (get-subtasks-and-docstrings-for task)] (if (empty? subtasks) nil - (let [longest-key-length (apply max (map count (keys subtasks))) - help-fn (ns-resolve task-ns 'help)] + (let [longest-key-length (apply max (map count (keys subtasks)))] (string/join "\n" (concat ["\n\nSubtasks available:"] (for [[subtask doc] subtasks]