Permalink
Browse files

Update readme for lein2.

  • Loading branch information...
1 parent 3004101 commit 042ec1940414dad0cfd8d4b2e370d9a1ab2d5b10 @technomancy committed Jan 13, 2012
Showing with 60 additions and 90 deletions.
  1. +47 −83 README.md
  2. +1 −1 bin/lein
  3. +2 −2 doc/lein.1
  4. +10 −4 todo.org
View
130 README.md
@@ -1,5 +1,7 @@
# Leiningen
+<img src="https://github.com/downloads/technomancy/leiningen/leiningen-banner.png" alt="Leiningen logo" title="The man himself" align="right" />
+
> "Leiningen!" he shouted. "You're insane! They're not creatures you can
> fight--they're an elemental--an 'act of God!' Ten miles long, two
> miles wide--ants, nothing but ants! And every single one of them a
@@ -8,11 +10,6 @@
Leiningen is for automating Clojure projects without setting your hair on fire.
-<img src="https://github.com/downloads/technomancy/leiningen/leiningen-banner.png" alt="Leiningen logo" title="The man himself" align="right" />
-
-Working on Clojure projects with tools designed for Java can be an
-exercise in frustration. With Leiningen, you just write Clojure.
-
## Installation
Leiningen bootstraps itself using the `lein` shell script;
@@ -52,10 +49,10 @@ project, but here are the commonly-used tasks:
$ lein install [NAME VERSION] # install a project
- $ lein search ... # find recent jars for your project.clj dependencies
+ $ lein search ... # find jars for your project.clj dependencies
Use `lein help` to see a complete list. `lein help $TASK` shows the
-usage for a specific one.
+usage for a specific task.
You can also chain tasks together in a single command by using commas:
@@ -79,11 +76,10 @@ The `project.clj` file in the project root should look like this:
:url "http://github.com/technomancy/myproject"
:dependencies [[org.clojure/clojure "1.2.1"]
[org.clojure/clojure-contrib "1.2.0"]]
- :dev-dependencies [[lein-ring "0.4.5"]])
+ :plugins [[lein-ring "0.4.5"]])
```
-If you're looking for the most recent jar of one of your dependencies,
-use `lein search`.
+To find specific versions of a dependency, use `lein search`.
The `lein new` task generates a project skeleton with an
appropriate starting point from which you can work. See the
@@ -97,46 +93,23 @@ executed inside Leiningen itself, not in your project. Set the
`:repl-init` key in project.clj to point to a namespace if
you want code executed inside your project.
+## Profiles
+
## Leiningen Plugins
Leiningen supports plugins. See [the plugins wiki
page](https://github.com/technomancy/leiningen/wiki/Plugins) for a
full list. If a plugin is needed for successful test or build runs,
-(such as lein-tar) then it should be added to `:dev-dependencies` in
+(such as lein-tar) then it should be added to `:plugins` in
project.clj, but if it's for your own convenience (such as
-swank-clojure) then it should be added using the `plugin` task:
-
- $ lein plugin install lein-clojars "0.6.0"
-
-See the plugin task's help for more information.
-
- $ lein plugin help
+swank-clojure) then it should be added to the `:plugins` list in the
+`:user` profile from `~/.lein/profiles.clj`.
## FAQ
**Q:** How do you pronounce Leiningen?
**A:** It's LINE-ing-en. ['laɪnɪŋən]
-**Q:** What does this offer over [Lancet](https://github.com/stuarthalloway/lancet)?
-**A:** Lancet is more of a library than a build tool. It doesn't predefine
- any tasks apart from what Ant itself offers, so there is nothing
- Clojure-specific in it. Leiningen builds on Lancet, but takes
- things further. In addition, it includes some Maven functionality
- for dependencies.
-
-**Q:** But Maven is terrifying!
-**A:** That's not a question. Anyway, Leiningen only uses the dependency
- resolution parts of Maven, which are quite tame. For some other
- build-related functionality it uses Ant under the covers via Lancet.
-
-**Q:** But Ant is terrifying!
-**A:** That's [true](http://www.defmacro.org/ramblings/lisp.html). Ant is
- an interpreter for a [procedural language with a regrettable
- syntax](http://blogs.tedneward.com/2005/08/22/When+Do+You+Use+XML+Again.aspx).
- But if you treat it as a standard library of build-related
- functions and are able to write it with a more pleasing syntax, it's
- not bad.
-
**Q:** What's a group ID? How do snapshots work?
**A:** See the
[tutorial](https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md)
@@ -153,33 +126,34 @@ See the plugin task's help for more information.
**Q:** What if my project depends on jars that aren't in any repository?
**A:** The [deploy guide](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md)
explains how to set up a private repository. If you are not sharing
- them with a team you could also just [install locally.](http://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html).
+ them with a team you could also just [install locally](https://github.com/kumarshantanu/lein-localrepo).
**Q:** How do I write my own tasks?
-**A:** If it's a task that may be useful to more than just your
- project, you should make it into a
- [plugin](https://github.com/technomancy/leiningen/blob/stable/doc/PLUGINS.md).
- You can also include one-off tasks in your src/leiningen/ directory
- if they're not worth spinning off; the plugin guide shows how.
+**A:** You can use `lein new plugin lein-myplugin` to create a new
+ [plugin project](https://github.com/technomancy/leiningen/blob/stable/doc/PLUGINS.md).
+ You can also include one-off tasks in your src/leiningen/ directory,
+ but it's actually fairly rare to have a task that's truly unique to
+ your project.
**Q:** I want to hack two projects in parallel, but it's annoying to switch between them.
-**A:** Use a feature called _checkout dependencies_. If you create a
- directory called `checkouts` in your project root and symlink
- some other project roots into it, Leiningen will allow you to hack
- on them in parallel. That means changes in the dependency will be
- visible in the main project without having to go through the whole
- install/switch-projects/deps/restart-repl cycle. Note that this is
- not a replacement for listing the project in :dependencies; it
- simply supplements that for tighter change cycles.
+**A:** If you create a directory called `checkouts` in your project
+ root and symlink some other project roots into it, Leiningen will
+ allow you to hack on them in parallel. That means changes in the
+ dependency will be visible in the main project without having to go
+ through the whole install/switch-projects/deps/restart-repl cycle,
+ and the copy in `checkouts` will take precedence over the dependency
+ declared in project.clj. Note that this is not a replacement for
+ listing the project in `:dependencies`; it simply supplements that for
+ convenience.
**Q:** Is it possible to exclude indirect dependencies?
**A:** Yes. Some libraries, such as log4j, depend on projects that are
not included in public repositories and unnecessary for basic
- functionality. Projects listed as :dependencies may exclude
- any of their dependencies by using the :exclusions key. See
- sample.project.clj for details.
+ functionality. Projects listed as `:dependencies` may exclude
+ any of their dependencies by using the `:exclusions` key. See
+ `lein help sample` for details.
-**Q:** What does java.lang.NoSuchMethodError: clojure.lang.RestFn.<init>(I)V mean?
+**Q:** What does `java.lang.NoSuchMethodError: clojure.lang.RestFn.<init>(I)V` mean?
**A:** It means you have some code that was AOT (ahead-of-time)
compiled with a different version of Clojure than the one you're
currently using. If it persists after running `lein clean` then it
@@ -192,44 +166,42 @@ See the plugin task's help for more information.
upon it.
**Q:** I'm behind an HTTP proxy; how can I fetch my dependencies?
-**A:** Currently you need to configure the underlying Maven library by
- creating `~/.m2/settings.xml` as explained in the
- [Maven guide](http://maven.apache.org/guides/mini/guide-proxies.html).
+**A:** TODO: document aether proxy setup.
**Q:** What can be done to speed up launch?
**A:** The main delay involved in Leiningen comes from starting the
- JVM. Launching `lein interactive` will give you an interactive
- session so you can run many tasks against the same process instead
- of launching a new one every time. Depending on your editor you may
- also be able to take advantage of its Clojure integration. (See
+ JVM. Most people use a development cycle that involves keeping a
+ single process running for as long as you're working on that
+ project. Depending on your editor you may be able to do this via its
+ Clojure integration. (See
[swank-clojure](http://github.com/technomancy/swank-clojure) or
- [VimClojure](https://bitbucket.org/kotarak/vimclojure), for example.)
+ [VimClojure](https://bitbucket.org/kotarak/vimclojure), for
+ example.) Otherwise you can use the basic `lein repl`.
**Q:** Still too slow; what else can make startup faster?
**A:** There are two flavours of Hotspot (Oracle/OpenJDK's JVM),
client and server. The server is optimized for long-running
processes and has quite a poor startup time. Leiningen will try to
launch a client JVM, but this only works on 32-bit Hotspot. If you
are on a 64-bit machine you can still use a client JVM if you
- install 32-bit packages; on Debian try ia32-sun-java6-bin. Once
- you've installed it, run `sudo update-java-alternatives -s ia32-java-6-sun`.
+ install 32-bit packages. TODO: document on wiki.
**Q:** I don't have access to stdin inside my project.
-**A:** There's a bug in the Ant library that Leiningen uses to spawn
+**A:** There's a problem in the library that Leiningen uses to spawn
new processes that blocks access to console input. This means that
functions like `read-line` will not work as expected in most
contexts, though the `repl` task necessarily includes a
workaround. You can also use the `trampoline` task to
launch your project's JVM after Leiningen's has exited rather than
- launching it as a subprocess
+ launching it as a subprocess. TODO: document in-process classloader
## Contributing
Please report issues on the [Github issue
tracker](https://github.com/technomancy/leiningen/issues) or the
[mailing list](http://groups.google.com/group/leiningen). Personal
-email addresses are not appropriate for bug reports. See the file
-HACKING.md for more details on how Leiningen's codebase is structured.
+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
@@ -238,10 +210,10 @@ directly to master in order to minimize unnecessary merge commit
clutter.
Contributors who have had a single patch accepted may request commit
-rights on the mailing list or in IRC. Please be careful with the
-master branch and keep any potentially-destabilizing work on topic
-branches. Other contributors will usually be glad to review topic
-branches before merging if you ask on IRC or the mailing list.
+rights on the mailing list or in IRC. Please use your judgment
+regarding potentially-destabilizing work and branches. Other
+contributors will usually be glad to review topic branches before
+merging if you ask on IRC or the mailing list.
Contributors are also welcome to request a free
[Leiningen sticker](http://twitpic.com/2e33r1) by asking on the
@@ -255,14 +227,6 @@ a `lein self-install` will usually get you what you
need. However, this will occasionally fail for very new SNAPSHOT
versions since the standalone jar will not have been uploaded yet.
-Alternatively if you have a copy of an older Leiningen version around
-(at least 1.1.0, installed as lein-stable, for example), then you can
-run `lein-stable deps` in your checkout. If Leiningen's dependencies
-change it will be necessary to remove the lib/ directory entirely
-before running `lein deps` again. (This is not necessary for most
-projects, but Leiningen has unique bootstrapping issues when working
-on itself.)
-
You can also use Maven, just for variety's sake:
$ mvn dependency:copy-dependencies
@@ -274,7 +238,7 @@ and use the checkout rather than the self-install uberjar if necessary.
## License
-Source Copyright © 2009-2011 Phil Hagelberg, Alex Osborne, Dan Larkin, and
+Source Copyright © 2009-2012 Phil Hagelberg, Alex Osborne, Dan Larkin, and
[other contributors](https://www.ohloh.net/p/leiningen/contributors).
Distributed under the Eclipse Public License, the same as Clojure
uses. See the file COPYING.
View
@@ -106,7 +106,7 @@ if [ -r "$BIN_DIR/../src/leiningen/main.clj" ]; then
# Running from source checkout
LEIN_DIR="$(dirname "$BIN_DIR")"
LEIN_LIBS="$(find -H "$LEIN_DIR/lib" -mindepth 1 -maxdepth 1 -print0 2> /dev/null | tr \\0 \:)"
- CLASSPATH="$CLASSPATH:leiningen-core/src/:$LEIN_LIBS:$LEIN_DIR/src:$LEIN_DIR/classes:$LEIN_DIR/resources:$LEIN_JAR"
+ CLASSPATH="$CLASSPATH:leiningen-core/src/:$LEIN_LIBS:$LEIN_DIR/src:$LEIN_DIR/resources:$LEIN_JAR"
if [ "$LEIN_LIBS" = "" -a "$1" != "self-install" -a ! -r "$LEIN_JAR" ]; then
echo "Leiningen is missing its dependencies. Please see \"Building\" in the README."
View
@@ -41,7 +41,7 @@ launch an interactive REPL session and socket server
package up the whole project as a .jar file
.TP
\fBlein install [NAME VERSION]\fR
-install a project
+install a project into your local repository
.SH CONFIGURATION
@@ -82,7 +82,7 @@ file and as much of the relevant code from your project as possible.
Copyright
.if t \(co
.if n (C)
-2009-2011 Phil Hagelberg and contributors.
+2009-2012 Phil Hagelberg and contributors.
Distributed under the Eclipse Public License, the same as Clojure
uses. See the file /usr/share/doc/leiningen/copyright.
View
@@ -12,14 +12,20 @@ See also https://github.com/technomancy/leiningen/issues
- [X] Finish designing and implement profiles
- [ ] Further design on Project Middleware
- [ ] In-process eval-in-project
- - [ ] Dynamic recalculating of classpath via pomegranate
+ - [X] Dynamic recalculating of classpath via pomegranate
- [ ] Redesign repl task, possibly around nREPL
- - [ ] Honor :plugins as separate from :dependencies
+ - [X] Honor :plugins as separate from :dependencies
+ - [ ] Update documentation
+ - plugin guide
+ - tutorial
+ - migration guide
+ - user settings
+ - hacking guide
+ - deploy guide
+ - sample project.clj
** Other stuff
- [ ] Move pom generation to pomegranate or leiningen
- - [ ] Better consistency/docs around user/settings
- [ ] Non-transitive AOT
- - [ ] lint/check mode for lein compile
- [X] More flexibility for jarring
- [ ] Mirror/proxy support, also for search indices
- [ ] Allow disabling of all injected code

0 comments on commit 042ec19

Please sign in to comment.