From 2df87f3dda5c4cc64a5c0ac0ccbf749ad981ec0b Mon Sep 17 00:00:00 2001 From: Phil Hagelberg Date: Wed, 9 May 2012 19:22:04 -0700 Subject: [PATCH] Reword a few things in READMEs, todo tweaks. --- README.md | 63 ++++++++++++---------- leiningen-core/README.md | 31 ++++++----- leiningen-core/src/leiningen/core/user.clj | 1 + project.clj | 1 + todo.org | 5 +- 5 files changed, 58 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index ad0a9b27d..b2b008ef0 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ 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 +> 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 > fiend from hell..." -> -- from Leiningen Versus the Ants by Carl Stephenson +> - from Leiningen Versus the Ants by Carl Stephenson Leiningen is for automating Clojure projects without setting your hair on fire. @@ -26,7 +26,7 @@ upon the first run on unix, so the first run will take longer. 2. Place it on your `$PATH`. (I like to use `~/bin`) 3. Set it to be executable. (`chmod 755 ~/bin/lein`) -The instructions above will install the stable release. The Leiningen 2 +The link above will get you the stable release. The Leiningen 2 [preview release](https://raw.github.com/technomancy/leiningen/preview/bin/lein) has some great new features, but not all projects and plugins have been upgraded to work with it yet. Please see the @@ -56,7 +56,7 @@ project, but here are the commonly-used tasks: $ lein jar # package up the whole project as a .jar file - $ lein install # install a project + $ lein install # install a project into the local repository $ lein search [TERM] # find jars for your project.clj dependencies @@ -83,19 +83,14 @@ The `project.clj` file in the project root should look like this: :plugins [[lein-ring "0.4.5"]]) ``` -To find specific versions of a dependency, use `lein search`. +To find specific versions of a dependency, use `lein search`, though +note that this can be extremely slow the first time you use it. -The `lein new` task generates a project skeleton with an -appropriate starting point from which you can work. See the +The `lein new` task generates a project skeleton with an appropriate +starting point from which you can work. See the [sample.project.clj](https://github.com/technomancy/leiningen/blob/preview/sample.project.clj) -file for a detailed listing of configuration options. - -You can also have user-level configuration that applies for all -projects. The `~/.lein/init.clj` file will be loaded every time -Leiningen launches; any arbitrary code may go there. This code is -executed inside Leiningen itself, not in your project. Set the -`:init-ns` key in `:repl-options` in project.clj to point to a -namespace if you want code executed inside your project in the repl. +file (also available via `lein help sample`) for a detailed listing of +configuration options. ### Profiles @@ -107,9 +102,11 @@ Clojure available in every project you hack on without modifying every single project.clj you use. By default the `:dev`, `:user`, and `:default` profiles are activated -for each task. Each profile is defined as a map which gets merged into -your project map. To add resources directories during development, add -a `:profiles` key to project.clj like so: +for each task, but the settings they provide are not propagated +downstream to projects that depend upon yours. Each profile is defined +as a map which gets merged into your project map. To add resources +directories during development, add a `:profiles` key to project.clj +like so: ```clj (defproject myproject "0.5.0-SNAPSHOT" @@ -230,6 +227,15 @@ explains how to write plugins. any of their dependencies by using the `:exclusions` key. See `lein help sample` for details. +**Q:** Why doesn't `deps` task populate the `lib` directory in version 2? +**A:** The only reason version 1 copied the jars around in the first + place was to support existing tooling that needed a cheap way to + calculate a project's classpath. Now that Leiningen has a mature + plugin ecosystem, this is no longer needed; jars can be referenced + directly out of the `~/.m2/repository` directory. If you need to see + a listing of all the dependencies that will be used and their + versions, use `lein deps :tree`. + **Q:** What does `java.lang.NoSuchMethodError: clojure.lang.RestFn.(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 @@ -251,7 +257,7 @@ explains how to write plugins. **Q:** What can be done to speed up launch? **A:** The main delay involved in Leiningen comes from starting the JVM. Most people use a development cycle that involves keeping a - single process running for as long as you're working on that + single REPL 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 @@ -267,10 +273,10 @@ explains how to write plugins. **Q:** Why is Leiningen 2 still in a preview release? **A:** As of the preview3 release, Leiningen 2 is very stable and recommended for general use. The main thing keeping it from a final - release is the fact that the Clojars repository + release is the fact that the current Clojars repository [mingles snapshots with releases](https://github.com/ato/clojars-web/issues/24), which is undesirable. Since switching the default repositories to a - releases-only Clojars (which hasn't been implemented yet) would be a + releases-only Clojars (which is still in development) would be a breaking change, a series of previews is being released in the mean time. **Q:** I don't have access to stdin inside my project. @@ -284,15 +290,16 @@ explains how to write plugins. ## Contributing Please report issues on the -[Github issue tracker](https://github.com/technomancy/leiningen/issues) +[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 readme for the `leiningen-core` library and `doc/PLUGINS.md` for -more details on how Leiningen's codebase is structured. Design -discussions also occur in the +the +[readme for the leiningen-core library](https://github.com/technomancy/leiningen/blob/master/leiningen-core/README.md) +and `doc/PLUGINS.md` for more details on how Leiningen's codebase is +structured. Design discussions also occur in the [#leiningen channel on Freenode](irc://chat.freenode.net#leiningen). -Patches are preferred as Github pull requests, though patches from +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 directly to master in order to minimize unnecessary merge commit @@ -306,7 +313,7 @@ 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 -mailing list and mailing a SASE. +mailing list and mailing a self-addressed, stamped envelope. ## Building diff --git a/leiningen-core/README.md b/leiningen-core/README.md index b3d2e8f2c..df688e95f 100644 --- a/leiningen-core/README.md +++ b/leiningen-core/README.md @@ -1,13 +1,12 @@ # Leiningen Core This library provides the core functionality of Leiningen. This -consists of the task execution implementation and helper functions -without any of the tasks or launcher scripts. +consists of the task execution implementation, project configuration, +and helper functions. The built-in tasks and the launcher scripts are +kept in the main `leiningen` project. -More [copious documentation is available](http://technomancy.github.com/leiningen/). - -The tasks that get run come from Leiningen itself as well as any -Leiningen plugins that may be active. +More detailed [API reference](http://leiningen.org/reference.html) is +available. ## Namespaces @@ -23,8 +22,6 @@ Leiningen plugins that may be active. implements the isolation of project code from Leiningen's own code. * **leiningen.core.user** just has a handful of functions which handle user-level configuration. -* **leiningen.core.ns** contains helper functions for finding - namespaces on the classpath. ## Running Tasks @@ -51,11 +48,19 @@ visible to the project's functions. Leiningen currently implements this by launching a sub-process using `leiningen.core.eval/eval-in-project`. Any code that must execute within the context of the project (AOT compilation, test runs, repls) -needs to go through this function. This sub-process (referred to as -the "project JVM") is an entirely new invocation of the `java` command -with its own classpath calculated from functions in the -`leiningen.core.classpath` namespace. It can only communicate with -Leiningen's process via the file system, sockets, and its exit code. +needs to go through this function. Before the process is launched, the +project must be "prepped", which consists of running all the tasks +named in the project's `:prep-tasks` key. This defaults to `javac` and +`compile`, but `defproject` or profiles may add additional tasks as +necessary. All prep tasks must be cheap to call if nothing has changed +since their last invocation. + +The sub-process (referred to as the "project JVM") is an entirely new +invocation of the `java` command with its own classpath calculated +from functions in the `leiningen.core.classpath` namespace. It can +even use a different version of the JVM from Leiningen if the +`:java-cmd` key is provided. It can only communicate with Leiningen's +process via the file system, sockets, and its exit code. The exception to this rule is when `:eval-in-leiningen` in `project.clj` is true, as is commonly used for Leiningen plugins. diff --git a/leiningen-core/src/leiningen/core/user.clj b/leiningen-core/src/leiningen/core/user.clj index 4badd18d9..8ea3c24a2 100644 --- a/leiningen-core/src/leiningen/core/user.clj +++ b/leiningen-core/src/leiningen/core/user.clj @@ -10,6 +10,7 @@ (io/file (System/getProperty "user.home") ".lein"))] (.getAbsolutePath (doto lein-home .mkdirs)))) +;; TODO: is this still needed now that we have the user profile? (def init "Load the user's ~/.lein/init.clj file, if present." (memoize (fn [] diff --git a/project.clj b/project.clj index 1babafd07..a8c1dc3a6 100644 --- a/project.clj +++ b/project.clj @@ -34,6 +34,7 @@ ;; * test self-install ;; * git tag ;; * push, push tags, update stable branch +;; * publish leiningen-core docs ;; * announce on mailing list ;; * bump version numbers back to snapshot ;; * regenerate pom.xml diff --git a/todo.org b/todo.org index 7d5e53edc..e372ded5e 100644 --- a/todo.org +++ b/todo.org @@ -5,9 +5,10 @@ See also https://github.com/technomancy/leiningen/issues * For 2.0.0 ** preview4 - [X] Don't re-extract native deps (#535) - - [ ] Install task outside projects (#546) (LHF) + - [X] Make offline profile use dev profile (#514) (LHF) + - [ ] Fix $JVM_OPTS (#565) + - [ ] Move lein-newnew plugin into default profile (#540) - [ ] Force checking of snapshots (#518) (LHF) - - [ ] Make offline profile use dev profile (#514) (LHF) ** Intermediate - [X] Pretty-print pom - [X] deps :tree