Permalink
Browse files

Add sample.project.clj showing all honored project keys.

  • Loading branch information...
1 parent 553eed8 commit 915e61a8304b90f4774ff215f6336036f1233cb3 @technomancy committed Jun 5, 2010
Showing with 85 additions and 61 deletions.
  1. +11 −9 INTRO.md
  2. +31 −50 README.md
  3. +42 −0 sample.project.clj
  4. +1 −2 src/leiningen/compile.clj
View
@@ -6,14 +6,15 @@ built on some Maven libraries; specifically the dependency resolution
parts. These aspects of Maven are not nearly as complex as the build
features that have given it its somewhat fearsome reputation. Think of
it as the package manager of the JVM world, much like Rubygems, CPAN,
-etc. There is a central canonical repository, a Clojure-specific
-repository called Clojars, and projects often also make their jars
-available through project-specific public repositories. It allows you
-to define the dependencies of your project, which it then goes and
-retrieves, stores in a local repository ("~/.m2" on Unix by default),
-and copies into your project's "lib/" directory. This makes it so that
-you don't have to check your dependent jar files into your SCM or make
-developers hunt down dependency jars by hand.
+etc. There is a central canonical Java-centric repository, a
+Clojure-specific repository called Clojars, and projects often also
+make their jars available through project-specific public
+repositories. It allows you to define the dependencies of your
+project, which it then goes and retrieves, stores in a local
+repository ("~/.m2" on Unix by default), and copies into your
+project's "lib/" directory. This makes it so that you don't have to
+check your dependent jar files into your SCM or make developers hunt
+down dependency jars by hand.
Leiningen describes packages using identifiers that look like:
@@ -41,7 +42,8 @@ following dependency in your project.clj file:
[org.ho.yaml/jyaml "1.3"]
-You'll get an error when you run "lein deps". One way to find the
+You'll get an error when you run "lein deps" because the group id
+doesn't match the package name in this case. One way to find the
correct group id is to use a maven search web site like
[Jarvana](http://jarvana.com). In the "project search" box, enter
"jyaml", and you'll see results that indicate the correct group-id
View
@@ -43,12 +43,12 @@ instead, though support on that platform is still experimental.
## Usage
+ $ lein new NAME # generate a new project skeleton
+
$ lein deps # install dependencies in lib/
$ lein test [TESTS] # run the tests in the TESTS namespaces, or all tests
- $ lein compile # ahead-of-time compile into classes/
-
$ lein repl # launch a REPL with the project classpath configured
$ lein clean # remove all build artifacts
@@ -57,13 +57,10 @@ instead, though support on that platform is still experimental.
$ lein uberjar # create a standalone jar that contains all dependencies
- $ lein pom # output a pom.xml file for interop with Maven
-
$ lein install # install in local repository
- $ lein help [TASK] # show a list of tasks or help for a given TASK
-
- $ lein new NAME # generate a new project skeleton
+These are the most commonly-used tasks; you can use "lein help" to see
+a complete list. "lein help $TASK" will show the usage for a specific one.
## Configuration
@@ -72,23 +69,16 @@ Place a project.clj file in the project root that looks something like this:
(defproject leiningen "0.5.0-SNAPSHOT"
:description "A build tool designed not to set your hair on fire."
:url "http://github.com/technomancy/leiningen"
- :dependencies [[org.clojure/clojure "1.1.0-alpha-SNAPSHOT"]
- [org.clojure/clojure-contrib "1.0-SNAPSHOT"]
+ :dependencies [[org.clojure/clojure "1.1.0]
+ [org.clojure/clojure-contrib "1.1.0"]
[ant/ant-launcher "1.6.2"]
[org.apache.maven/maven-ant-tasks "2.0.10"]]
- :dev-dependencies [[org.clojure/swank-clojure "1.0"]])
+ :dev-dependencies [[org.clojure/swank-clojure "1.2.1"]])
-Other keys accepted:
-
-* :aot - a list of namespaces on which to perform AOT-compilation.
-* :main - specify a namespace to use as main for an executable jar.
-* :repositories - additional maven repositories to search for dependencies.
- Specify this as a map of repo IDs to URLs.
-* :source-path, :compile-path, :library-path, :test-path, :resources-path -
- alternate paths for src/, classes/, lib/, resources/, and test/ directories.
-* :jvm-opts - a list of arguments to pass to the project-level JVM
-
-TODO: spin this list off into its own file and explain each option better
+The "lein new" task will generate a project skeleton with an
+appropriate starting point from which you can work. See the file
+sample.project.clj for a detailed listing of all the configuration
+options that Leiningen knows about.
## FAQ
@@ -122,11 +112,11 @@ TODO: spin this list off into its own file and explain each option better
**Q:** What if my project depends on jars that aren't in any repository?
**A:** Open-source jars can be uploaded to Clojars (see "Publishing"
- below), though be sure to use the groupId of "org.clojars.$USERNAME"
+ below), though be sure to use the group-id of "org.clojars.$USERNAME"
in order to avoid conflicts and to allow the original authors to
claim it in the future once they get around to uploading.
- Alternatively you can install into your local repository in ~/.m2
- with Maven for Java libs or "lein install" for Clojure libs.
+ Alternatively you can do a one-off install into your local repository in
+ ~/.m2 with Maven for Java libs or "lein install" for Clojure libs.
**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)
@@ -141,31 +131,21 @@ TODO: spin this list off into its own file and explain each option better
should not AOT-compile your project if other projects may depend
upon it.
-**Q:** It looks like the classpath isn't honoring project.clj.
-**A:** Leiningen runs many things in a subclassloader so it can
- control the classpath and other things. Because of this, the
- standard (System/getProperty "java.class.path") call will return the
- classpath that Leiningen runs in, not the one that your project is
- run in. Your project's classpath is stored in the user/*classpath* var.
-
**Q:** Is it possible to exclude indirect dependencies?
-**A:** Yes. Some libraries, such as log4j, depend on projects that are
+**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, as demonstrated here:
- [log4j "1.2.15" :exclusions [javax.mail/mail
- javax.jms/jms
- com.sun.jdmk/jmxtools
- com.sun.jmx/jmxri]]
+ any of their dependencies by using the :exclusions key. See
+ sample.project.clj for details.
+
+**Q:** It says a required artifact is missing for "super-pom". What's that?
+**A:** The Maven API that Leiningen uses refers to your project as
+ "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 should I pick my version numbers?
**A:** Use [semantic versioning](http://semver.org).
-**Q:** What happened to [Corkscrew](http://github.com/technomancy/corkscrew)?
-**A:** I tried, but I really couldn't make the wine metaphor work. That,
- and the Plexus Classworlds container was an ornery beast causing
- much frustration. The maven-ant-tasks API is much more manageable.
-
## Publishing
If your project is a library and you would like others to be able to
@@ -176,8 +156,8 @@ it into Maven central, the easiest way is to publish it at
for open-source code. Once you have created an account there,
publishing is easy:
- $ lein jar
- $ scp $PROJECT.jar clojars@clojars.org:
+ $ lein jar && lein pom
+ $ scp pom.xml $PROJECT.jar clojars@clojars.org:
Once that succeeds it will be available for other projects to depend
on. Leiningen adds Clojars and [the Clojure nightly build
@@ -205,16 +185,17 @@ Contributions are preferred as either Github pull requests or using
"git format-patch" and the mailing list as is requested [for
contributing to Clojure itself](http://clojure.org/patches). Please
use standard indentation with no tabs, trailing whitespace, or lines
-longer than 80 columns. If you've got some time on your hands, reading
-this [style guide](http://mumble.net/~campbell/scheme/style.txt)
-wouldn't hurt either.
+longer than 80 columns. See [this post on submitting good
+patches](http://technomancy.us/135) for some tips. If you've got some
+time on your hands, reading this [style
+guide](http://mumble.net/~campbell/scheme/style.txt) wouldn't hurt
+either.
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".
+"lein $YOUR_COMMAND". See the file PLUGINS.md for details.
-See the [complete list of known
- issues](http://github.com/technomancy/leiningen/issues).
+See the [complete list of known issues](http://github.com/technomancy/leiningen/issues).
## License
View
@@ -0,0 +1,42 @@
+;; This is an annotated example of the options that may be set in a
+;; project.clj file. It is a fairly contrived example in order to
+;; cover all options exhaustively; it shouldn't be considered a
+;; representative configuration.
+
+;; The project is named "sample", and its group-id is "org.example".
+(defproject org.example/sample "1.0.0-SNAPSHOT" ; version "1.0.0-SNAPSHOT"
+ ;; The descrption is used to allow searchability when uploaded to Clojars.
+ :description "A sample project"
+ ;; The URL is also metadata that Clojars uses.
+ :url "http://example.org/sample-clojure-project"
+ ;; Dependencies are listed as [group-id/name version].
+ :dependencies [[org.clojure/clojure "1.1.0"]
+ [org.clojure/clojure-contrib "1.1.0"]
+ [log4j "1.2.15" :exclusions [javax.mail/mail
+ javax.jms/jms
+ com.sun.jdmk/jmxtools
+ com.sun.jmx/jmxri]]]
+ ;; Dev dependencies are intended for use only during
+ ;; development. Projects that depend on this project will not pull
+ ;; in its dev-dependencies, and they won't be included in the uberjar.
+ :dev-dependencies [[org.clojure/swank-clojure "1.2.1"]]
+ ;; These namespaces will be AOT-compiled. Needed for gen-class and
+ ;; other Java interop functionality. :namespaces is an alias for this.
+ :aot [org.example.sample.SampleClass]
+ ;; This namespace will be used as the "main" in the uberjar.
+ :main [org.example.sample]
+ ;; Emit warnings on all reflection calls.
+ :warn-on-reflection true
+ ;; Set this in order to only use the :repositories you list below.
+ :omit-default-repositories true
+ :repositories { "java.net" "http://download.java.net/maven/2"
+ "jboss" "http://repository.jboss.com/maven2/"}
+ ;; If you'd rather use a different directory structure, you can set these.
+ :source-path "src/main/clojure"
+ :library-path "target/dependency"
+ :test-path "src/test/clojure"
+ :resources-path "src/main/resources"
+ :native-path "src/native" ; where to look for native dependencies
+ :jar-dir "target/" ; where to place the project's jar file
+ ;; You can set JVM-level options here.
+ :jvm-opts "-Xmx1g")
@@ -129,8 +129,7 @@
(.executeJava java)))
(defn compile
- "Ahead-of-time compile the project. Looks for all namespaces under src/
- unless a list of :namespaces is provided in project.clj."
+ "Ahead-of-time compile the namespaces given under :aot in project.clj."
[project]
;; dependencies should be resolved by explicit "lein deps",
;; otherwise it will be done only if :library-path is empty

0 comments on commit 915e61a

Please sign in to comment.