Update readme for lein2.
This commit is contained in:
Phil Hagelberg
parent
30041014b4
commit
042ec19404
4 changed files with 60 additions and 90 deletions
130
README.md
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,18 +166,17 @@ 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),
|
||||
|
|
@ -211,25 +184,24 @@ See the plugin task's help for more information.
|
|||
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.
|
||||
|
|
|
|||
2
bin/lein
2
bin/lein
|
|
@ -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."
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
14
todo.org
14
todo.org
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue