Merge pull request #746 from llasram/provided-profile

Document :provided profile

doc/PROFILES.md

@@ -7,10 +7,10 @@ without including them in the jar, or you may want to have Swank
 Clojure available in every project you hack on without modifying every
 single project.clj you use.
 
-By default the `:dev`, `:user`, and `:base` profiles are activated
-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.
+By default the `:dev`, `:provided`, `:user`, and `:base` profiles are
+activated 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.
 
 You can place any arbitrary defproject entries into a given profile
 and they will be merged into the project map when that profile is
@@ -114,10 +114,11 @@ This can be used to avoid duplication:
  :production [:shared {:servers [\"prod1.mycorp.com\", \"prod1.mycorp.com\"]}]}
 ```
 
-Composite profiles are used by Leiningen internally for the `:default` profile,
-which is the profile used if you don't change it using `with-profile`. The
-`:default` profile is defined to be a composite of `[:dev :user :base]`, but you
-can change this in your `project.clj` just like any other profile.
+Composite profiles are used by Leiningen internally for the `:default`
+profile, which is the profile used if you don't change it using
+`with-profile`. The `:default` profile is defined to be a composite of
+`[:dev :provided :user :base]`, but you can change this in your
+`project.clj` just like any other profile.
 
 ## Debugging
 

doc/TUTORIAL.md

@@ -352,6 +352,45 @@ yourself, so it's not a good solution for end-users.
 Of course if your users already have Leiningen installed, you can
 instruct them to use `lein run` as described above.
 
+### Framework (Uber)jars
+
+Many Java frameworks expect deployment of a jar file or derived archive
+sub-format containing a subset of the application's necessary
+dependencies.  The framework expects to provide the missing dependencies
+itself at run-time.  Dependencies which are provided by a framework in
+this fashion may be specified in the `:provided` profile.  Such
+dependencies will be available during compilation, testing, etc., but
+won't be included by default by the `uberjar` task or plugin tasks
+intended to produce stable deployment artifacts.
+
+For example, Hadoop job jars may be just regular (uber)jar files
+containing all dependencies except the Hadoop libraries themselves:
+
+```clj
+(project example.hadoop "0.1.0"
+  ...
+  :profiles {:provided
+             {:dependencies
+              [[org.apache.hadoop/hadoop-core "0.20.2-dev"]]}}
+  :main example.hadoop)
+```
+
+    $ lein uberjar
+    Compiling example.hadoop
+    Created /home/xmpl/src/example.hadoop/example.hadoop-0.1.0.jar
+    Including example.hadoop-0.1.0.jar
+    Including clojure-1.4.0.jar
+    Created /home/xmpl/src/example.hadoop/example.hadoop-0.1.0-standalone.jar
+    $ hadoop jar example.hadoop-0.1.0-standalone.jar
+    12/08/24 08:28:30 INFO util.Util: resolving application jar from found main method on: example.hadoop
+    12/08/24 08:28:30 INFO flow.MultiMapReducePlanner: using application jar: /home/xmpl/src/example.hadoop/./example.hadoop-0.1.0-standalone.jar
+    ...
+
+Plugins are required to generate framework deployment jar derivatives
+(such as WAR files) which include additional metadata, but the
+`:provided` profile provides a general mechanism for handling the
+framework dependencies.
+
 ### Server-side Projects
 
 There are many ways to get your project deployed as a server-side

leiningen-core/src/leiningen/core/project.clj

@@ -154,9 +154,9 @@
 ;; # Profiles: basic merge logic
 
 (def default-profiles
-  "Profiles get merged into the project map. The :dev and :user
+  "Profiles get merged into the project map. The :dev, :provided, and :user
   profiles are active by default."
-  (atom {:default [:provided :dev :user :base]
+  (atom {:default [:dev :provided :user :base]
          :base {:resource-paths ["dev-resources"]
                 :plugins [['lein-newnew "0.3.5"]]
                 :checkout-deps-shares [:source-paths