Implemented documentation suggestions from readers.
This commit is contained in:
parent
9b823c2cc8
commit
d2e016c498
4 changed files with 74 additions and 43 deletions
|
@ -21,6 +21,8 @@ The docstring from the plugin's namespace will be displayed by the
|
|||
"lein help" task. The function's arglists will also be shown, so pick
|
||||
argument names that are clear and descriptive.
|
||||
|
||||
TODO: describe lancet
|
||||
|
||||
## Leiningen 1.2
|
||||
|
||||
The rest of this document only applies to Leiningen version 1.2+. It
|
||||
|
|
21
README.md
21
README.md
|
@ -10,7 +10,7 @@ Leiningen is a build tool for Clojure designed to not set your hair on fire.
|
|||
|
||||
Building Clojure projects with tools designed for Java can be an
|
||||
exercise in frustration. If you use Ant, you end up copying around a
|
||||
lot of the same tasks around between XML files on all your projects;
|
||||
lot of the same tasks between XML files on all your projects;
|
||||
there's a lot of repetition. Maven avoids repetition, but provides
|
||||
very little transparency into what's really going on behind the scenes
|
||||
and forces you to become a Maven expert to script a nontrivial
|
||||
|
@ -37,11 +37,16 @@ For snapshot versions you may use [the dev version of the lein
|
|||
script](http://github.com/technomancy/leiningen/raw/master/bin/lein) instead.
|
||||
|
||||
On Windows you can download
|
||||
[lein.bat](http://github.com/technomancy/leiningen/raw/stable/bin/lein.bat),
|
||||
[lein.bat](http://github.com/technomancy/leiningen/raw/master/bin/lein.bat),
|
||||
instead, though support on that platform is still experimental.
|
||||
|
||||
## Usage
|
||||
|
||||
The
|
||||
[tutorial](http://github.com/technomancy/leiningen/blob/master/TUTORIAL.md)
|
||||
has a detailed walk-through of the steps involved in creating a new
|
||||
project, but here are the commonly-used tasks:
|
||||
|
||||
$ lein new NAME # generate a new project skeleton
|
||||
|
||||
$ lein deps # install dependencies in lib/
|
||||
|
@ -78,9 +83,7 @@ Place a project.clj file in the project root like this:
|
|||
The <tt>lein new</tt> task generates a project skeleton with an
|
||||
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. The
|
||||
[tutorial](http://github.com/technomancy/leiningen/blob/master/TUTORIAL.md)
|
||||
may also help.
|
||||
file for a detailed listing of configuration options.
|
||||
|
||||
## FAQ
|
||||
|
||||
|
@ -146,6 +149,14 @@ may also help.
|
|||
"super-pom". It's just a quirk of the API. It probably means there
|
||||
is a typo in your :dependency declaration in project.clj.
|
||||
|
||||
**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](http://github.com/technomancy/leiningen/blob/master/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.
|
||||
|
||||
**Q:** How should I pick my version numbers?
|
||||
**A:** Use [semantic versioning](http://semver.org).
|
||||
|
||||
|
|
92
TUTORIAL.md
92
TUTORIAL.md
|
@ -8,7 +8,7 @@ project building and JVM-land dependency management.
|
|||
## Creating a Project
|
||||
|
||||
We'll assume you've got Leiningen installed as per the
|
||||
[readme](http://github.com/technomancy/leiningen/blob/master/README.md).
|
||||
[README](http://github.com/technomancy/leiningen/blob/master/README.md).
|
||||
Generating a new project is easy:
|
||||
|
||||
$ lein new myproject
|
||||
|
@ -49,10 +49,11 @@ fairly useless:
|
|||
Created ~/src/myproject/myproject-1.0.0-SNAPSHOT.jar
|
||||
|
||||
Libraries for the JVM are packaged up as .jar files, which are
|
||||
basically just .zip files with a little extra JVM-specific metadata
|
||||
that contain either .class files (bytecode) or .clj source
|
||||
files. These jar files are available through repositories that serve
|
||||
them up over HTTP alongside their metadata.
|
||||
basically just .zip files with a little extra JVM-specific metadata.
|
||||
They usually contain .class files (JVM bytecode) and .clj source
|
||||
files, but they can also contain other things like config
|
||||
files. Leiningen downloads them from remote Maven repositories for
|
||||
you.
|
||||
|
||||
## project.clj
|
||||
|
||||
|
@ -64,11 +65,16 @@ them up over HTTP alongside their metadata.
|
|||
[org.clojure/clojure-contrib "1.1.0"]])
|
||||
|
||||
Fill in the :description with a short paragraph so that your project
|
||||
will show up in search results. At some point you'll need to flesh out
|
||||
the README too, but for now let's skip ahead to setting :dependencies.
|
||||
will show up in search results once you upload to Clojars (as
|
||||
described below). At some point you'll need to flesh out the README
|
||||
too, but for now let's skip ahead to setting :dependencies. Note that
|
||||
Clojure is just another dependency here. Unlike most languages, it's
|
||||
easy to swap out any version of Clojure. If you're using Clojure
|
||||
Contrib, make sure that version matches the Clojure version.
|
||||
|
||||
If you've got a simple pure-clojure project, you will be fine with the
|
||||
default of Clojure and Contrib, but otherwise you'll need to list
|
||||
other dependencies.
|
||||
default of depending only on Clojure and Contrib, but otherwise you'll
|
||||
need to list other dependencies.
|
||||
|
||||
## Dependencies
|
||||
|
||||
|
@ -80,34 +86,42 @@ searching [Jarvana](http://jarvana.com), though you'll need to
|
|||
translate their notation into Leiningen's. Leiningen describes
|
||||
packages using identifiers that look like this:
|
||||
|
||||
[org.clojure/swank-clojure "1.2.1"]
|
||||
[org.clojure/clojure-contrib "1.1.0"]
|
||||
|
||||
* "org.clojure" is called the 'group-id'
|
||||
* "swank-clojure" is called the 'artifact-id'
|
||||
TODO: show example of mvn deps
|
||||
|
||||
* "org.clojure" is called the "group-id"
|
||||
* "clojure-contrib" is called the "artifact-id"
|
||||
* "1.2.1" is the version of the jar file you require
|
||||
|
||||
If you omit the group-id, then Leiningen will use the artifact-id for
|
||||
it. This is the convention generally used for Leiningen libraries. The
|
||||
name and version at the top of the defproject form follows the same
|
||||
rules.
|
||||
|
||||
Sometimes versions will end in "-SNAPSHOT". This means that it is not
|
||||
an official release but a development build. In general relying on
|
||||
snapshot dependencies is discouraged, but sometimes its necessary if
|
||||
you need bug fixes etc. that have not made their way into a release
|
||||
yet. Adding a snapshot dependency to your project will cause Leiningen
|
||||
to actively go seek out the latest version of the dependency every
|
||||
time you run <tt>lein deps</tt>, (whereas normal release versions are
|
||||
cached in the local repository) so if you have a lot of snapshots it
|
||||
will slow things down.
|
||||
an official release but a development build. Relying on snapshot
|
||||
dependencies is discouraged but is sometimes necessary if you need bug
|
||||
fixes etc. that have not made their way into a release yet. Adding a
|
||||
snapshot dependency to your project will cause Leiningen to actively
|
||||
go seek out the latest version of the dependency once a day when you
|
||||
run <tt>lein deps</tt>, (whereas normal release versions are cached in
|
||||
the local repository) so if you have a lot of snapshots it will slow
|
||||
things down.
|
||||
|
||||
Speaking of the local repository, all the dependencies you pull in
|
||||
using Leiningen or Maven get cached in $HOME/.m2/repository. You can
|
||||
install the current project in there:
|
||||
using Leiningen or Maven get cached in $HOME/.m2/repository since
|
||||
Leiningen uses the Maven API under the covers. You can install the
|
||||
current project in the local repository with this command:
|
||||
|
||||
$ lein install
|
||||
|
||||
Wrote pom.xml
|
||||
[INFO] Installing myproject-1.0.0-SNAPSHOT.jar to ~/.m2/repository/myproject/myproject/1.0.0-SNAPSHOT/myproject-1.0.0-SNAPSHOT.jar
|
||||
|
||||
Generally Leiningen will fetch your dependencies on-demand, but if you
|
||||
have just added a new dependency and you want to force it to fetch it,
|
||||
you can do that too:
|
||||
Generally Leiningen will fetch your dependencies when they're needed,
|
||||
but if you have just added a new dependency and you want to force it
|
||||
to fetch it, you can do that too:
|
||||
|
||||
$ lein deps
|
||||
|
||||
|
@ -117,7 +131,7 @@ you can do that too:
|
|||
Dependencies are downloaded from Clojars, the central Maven (Java)
|
||||
repository, the [official Clojure build
|
||||
server](http://build.clojure.org), and any other repositories that you
|
||||
add to your project.clj file; see the
|
||||
add to your project.clj file. See :repositories in
|
||||
[sample.project.clj](http://github.com/technomancy/leiningen/blob/master/sample.project.clj).
|
||||
|
||||
If you've confirmed that your project will work with a number of
|
||||
|
@ -162,7 +176,7 @@ Of course, we haven't written any tests yet, so we've just got the
|
|||
skeleton failing tests that Leiningen gave us with <tt>lein
|
||||
new</tt>. But once we fill it in the test suite will become more
|
||||
useful. Sometimes if you've got a large test suite you'll want to run
|
||||
just one or two namespaces worth:
|
||||
just one or two namespaces at a time:
|
||||
|
||||
$ lein test myproject.parser-test
|
||||
|
||||
|
@ -170,13 +184,6 @@ just one or two namespaces worth:
|
|||
Ran 2 tests containing 10 assertions.
|
||||
0 failures, 0 errors.
|
||||
|
||||
When naming your test namespaces, it's a good idea to pick a name that
|
||||
matches the name of the namespace it's testing, but with a "-test"
|
||||
suffix. In stack traces that come from test failures you'll only see
|
||||
the last segment of the namespace that caused the exception, so it's
|
||||
convenient to have it distinguishable from the implementation
|
||||
namespace.
|
||||
|
||||
## Compiling
|
||||
|
||||
If you're lucky you'll be able to get away without doing any AOT
|
||||
|
@ -206,15 +213,26 @@ publishing is easy:
|
|||
$ lein jar && lein pom
|
||||
$ scp pom.xml myproject-1.0.0.jar clojars@clojars.org:
|
||||
|
||||
Once that succeeds it will be available for other projects to depend
|
||||
on.
|
||||
Once that succeeds it will be available as a package on which other
|
||||
projects may depend. You will need to have permission to publish to
|
||||
the project's group-id under Clojars, though if that group-id doesn't
|
||||
exist yet then Clojars will automatically create it and give you
|
||||
permissions.
|
||||
|
||||
Sometimes you'll need to publish libraries that you don't directly
|
||||
maintain, either because the original maintainer hasn't published it
|
||||
or because you need some bugfixes that haven't been applied upstream
|
||||
yet. In this case you don't want to publish it under its original
|
||||
group-id, since this will prevent the true maintainer from using that
|
||||
group-id once they publish it. In this case you should use
|
||||
"org.clojars.$USERNAME" as the group-id when you upload your fork.
|
||||
|
||||
## Uberjar
|
||||
|
||||
Not all Leiningen projects are libraries though--sometimes you want to
|
||||
distribute your project to end-users who don't want to worry about
|
||||
having a copy of Clojure lying around. You can use the
|
||||
<tt>uberjar</tt> task to create a standalone executable jar.
|
||||
<tt>uberjar</tt> task to create a standalone, executable jar.
|
||||
|
||||
For this to work you'll need to specify in project.clj a namespace as
|
||||
your :main that contains a <tt>-main</tt> function which will get
|
||||
|
|
2
todo.org
2
todo.org
|
@ -21,9 +21,9 @@ Leiningen TODOs
|
|||
** Improve plugins
|
||||
*** TODO Allow plugins to be activated user-wide (maybe system-wide?)
|
||||
* For 1.2.0
|
||||
** TODO Move the intro into a tutorial
|
||||
** TODO document checkout dependencies
|
||||
** TODO Re-enable rlwrap
|
||||
** DONE Move the intro into a tutorial
|
||||
** DONE bin script has stabilized; self-install for dev versions should work
|
||||
** DONE accept list of namespaces to compile from command-line options
|
||||
** DONE document version ranges
|
||||
|
|
Loading…
Reference in a new issue