Documentation for dependency management

.gitignore

@@ -117,9 +117,9 @@ samples-and-tests/jobboard/tmp
 samples-and-tests/validation/logs
 samples-and-tests/zencontact/precompiled
 !modules/docviewer
-!modules/crud
+!modules/crud-1.2
 !modules/console
 !modules/grizzly
-!modules/secure
+!modules/secure-1.2
 !modules/testrunner
 !framework/src/play/db

documentation/commands/cmd-dependencies.txt

@@ -0,0 +1,21 @@
+~ Name:
+~ ~~~~~
+~ dependencies -- Resolve and retrieve project dependencies
+~
+~ Alias:
+~ ~~~~~
+~ deps
+~ 
+~ Synopsis:
+~ ~~~~~~~~~
+~ play dependencies [app_path] [--verbose] [--debug] [--sync]
+~
+~ Description:
+~ ~~~~~~~~~~~~
+~ Compute resolve and retrieve project dependencies and install them either
+~ in lib/ directory for jar artifacts or in modules/ for Play modules artifacts.
+~
+~ By default the command will not delete unrecognized artifacts. Use the --sync option
+~ to keep both lib/ and modules/ directory synchronized with the dependencies management
+~ system.
+~

documentation/manual/dependency.textile

@@ -0,0 +1,255 @@
+h1. Dependency management
+
+The Play's dependency management system allow to express all external dependencies required by your application in a single **dependencies.yml** file. 
+
+A Play application can have 3 kind of dependencies:
+
+* The Play framework itself since a Play application always depends of Play framework.
+* Any Java library, provided as **jar** file installed in your application's **lib/** directory.
+* A Play module (in fact an application fragment) installed in your application's **modules/** directory.
+
+Once expressed all these dependencies in the **conf/dependencies.yml** file of you application, Play will resolve, download and install all required dependencies.
+
+h2. <a name="format">Dependency format</a>
+
+A dependency is described by an organisation a name and a revision number. In the **dependencies.yml** file you will write it this way:
+
+bc. organisation -> name revision
+
+So, for instance the "version 1.0 of the Play PDF module":http://www.playframework.org/modules/pdf is expressed this way:
+
+bc. play -> pdf 1.0
+
+Sometimes the organisation matches exactly the dependency name. It is for instance the case for "commons-lang":http://commons.apache.org/lang/:
+
+bc. commons-lang -> commons-lang 2.5
+
+In this case, you can avoid the organisation in the dependency declaration:
+
+bc. commons-lang 2.5
+
+h3. Dynamic revisions
+
+The revision can be given as a fixed one (1.2, for instance) or dynamically. A dynamic revision expresses a range of allowed revisions. 
+
+Example:
+
+* **[1.0,2.0]** matches all versions greater or equal to 1.0 and lower or equal to 2.0
+* **[1.0,2.0[** matches all versions greater or equal to 1.0 and lower than 2.0
+* **]1.0,2.0]** matches all versions greater than 1.0 and lower or equal to 2.0
+* **]1.0,2.0[** matches all versions greater than 1.0 and lower than 2.0
+* **[1.0,)** matches all versions greater or equal to 1.0
+* **]1.0,)** matches all versions greater than 1.0
+* **(,2.0]** matches all versions lower or equal to 2.0
+* **(,2.0[** matches all versions lower than 2.0
+
+h2. <a name="yml">dependencies.yml</a>
+
+When you create a new Play application, a **dependencies.yml** descriptor is automatically created in the **conf/** directory:
+
+bc. # Application dependencies
+
+require:
+    - play 1.2
+
+The **require** section list all dependencies needed by your application. Here the new application only depends of **Play version 1.2**. But let's say your application need "Google Guava":http://code.google.com/p/guava-libraries/, you would have:
+
+bc. # Application dependencies
+
+require:
+    - play 1.2
+    - com.google.guava -> guava r07
+
+h3. The 'play dependencies' command
+
+To ask Play to resolve, download and install the new dependencies, run **play dependencies**:
+
+bc. $ play dependencies
+~        _            _ 
+~  _ __ | | __ _ _  _| |
+~ | '_ \| |/ _' | || |_|
+~ |  __/|_|\____|\__ (_)
+~ |_|            |__/   
+~
+~ play! 1.2, http://www.playframework.org
+~ framework ID is gbo
+~
+~ Resolving dependencies using ~/Desktop/scrapbook/coco/conf/dependencies.yml,
+~
+~ 	com.google.guava->guava r07 (from mavenCentral)
+~ 	com.google.code.findbugs->jsr305 1.3.7 (from mavenCentral)
+~
+~ Downloading required dependencies,
+~
+~ 	downloaded http://repo1.maven.org/maven2/com/google/guava/guava/r07/guava-r07.jar
+~ 	downloaded http://repo1.maven.org/maven2/com/google/code/findbugs/jsr305/1.3.7/jsr305-1.3.7.jar
+~
+~ Installing resolved dependencies,
+~
+~ 	lib/guava-r07.jar
+~ 	lib/jsr305-1.3.7.jar
+~
+~ Done!
+~
+
+Now Play has downloaded 2 jars (guava-r07.jar, jsr305-1.3.7.jar) from the central Maven repository, and installed them into the application **lib/** directory. 
+
+Why 2 jars since we have only declared one dependency? Because Google Guava has a transitive dependency. In fact this dependency is not really required and we would like to exclude it. 
+
+h3. Transitive dependencies
+
+By default, any transitive dependencies are automatically retrieved. But there are several ways to exclude them if needed.
+
+1. You can disable transitive dependencies for a particular dependency:
+
+bc. # Application dependencies
+
+require:
+    - play 1.2
+    - com.google.guava -> guava r07:
+        transitive: false
+
+2. You can disable transitive dependencies for the whole project:
+
+bc. # Application dependencies
+
+transitiveDependencies: false    
+
+require:
+    - play 1.2
+    - com.google.guava -> guava r07
+
+3. You can exclude any specific dependency explicitely:
+
+bc. # Application dependencies
+
+require:
+    - play 1.2
+    - com.google.guava -> guava r07:
+        exclude:
+            - com.google.code.findbugs -> *
+
+h3. Keep lib/ and modules/ directory in sync
+
+Now if you run **play dependencies** again, the findbugs dependency will be omitted:
+
+bc. $ play deps
+~        _            _ 
+~  _ __ | | __ _ _  _| |
+~ | '_ \| |/ _' | || |_|
+~ |  __/|_|\____|\__ (_)
+~ |_|            |__/   
+~
+~ play! 1.2, http://www.playframework.org
+~ framework ID is gbo
+~
+~ Resolving dependencies using ~/Desktop/scrapbook/coco/conf/dependencies.yml,
+~
+~ 	com.google.guava->guava r07 (from mavenCentral)
+~
+~ Installing resolved dependencies,
+~
+~ 	lib/guava-r07.jar
+~
+~ ******************************************************************************************************************************
+~ WARNING: Your lib/ and modules/ directories and not synced with current dependencies (use --sync to automatically delete them)
+~
+~ 	Unknown: ~/Desktop/scrapbook/coco/lib/jsr305-1.3.7.jar
+~ ******************************************************************************************************************************
+~
+~ Done!
+~
+
+However the **jsr305-1.3.7.jar** artifact downloaded before is still present in the application **lib/** directory. 
+
+To keep the **lib/** and **modules/** directory synced with the dependency management system, you can specify the **--sync** command to the **dependencies** command:
+
+bc. play dependencies --sync
+
+If you run this command again the unwanted **jar** will be deleted. 
+
+h2. <a name="conflicts">Conflicts resolution</a>
+
+Whenever two components need different revisions of the same dependency, the conflicts manager will choose one. The default is to keep the latest revision and to evict the others. 
+
+But there is an exception. When a core dependency of Play framework itself is involved in a conflict, the version available in **$PLAY/framework/lib** is preferred. For instance, Play depends of **commons-lang 2.5**. If your application requires **commons-lang 3.0**:
+
+bc. # Application dependencies
+
+require:
+    - play 1.2
+    - com.google.guava -> guava r07:
+        transitive: false
+    - commons-lang 3.0
+
+Running **play dependencies** will evict **commons-lang 3.0** even if this version is newer:
+
+bc. play dependencies
+~        _            _ 
+~  _ __ | | __ _ _  _| |
+~ | '_ \| |/ _' | || |_|
+~ |  __/|_|\____|\__ (_)
+~ |_|            |__/   
+~
+~ play! 1.2, http://www.playframework.org
+~ framework ID is gbo
+~
+~ Resolving dependencies using ~/Desktop/scrapbook/coco/conf/dependencies.yml,
+~
+~ 	com.google.guava->guava r07 (from mavenCentral)
+~
+~ Some dependencies have been evicted,
+~
+~	commons-lang 3.0 is overriden by commons-lang 2.5
+~
+~ Installing resolved dependencies,
+~
+~ 	lib/guava-r07.jar
+~
+~ Done!
+~
+
+Also, you can notice that dependencies already availables in **$PLAY/framework/lib** will not been installed in your application's **lib/** directory.
+
+However sometimes you want to force a specific dependency version, either to override a core dependency or to choose another revision that the latest version available. 
+
+So you can specify the **force** option on any dependency:
+
+bc. # Application dependencies
+
+require:
+    - play 1.2
+    - com.google.guava -> guava r07:
+        transitive: false
+    - commons-lang 3.0:
+        force: true
+
+h2. <a name="repositories">Adding new repositories</a>
+
+By default, Play will search for **jar** dependencies in the "central Maven repository":http://repo1.maven.org/maven2/, and will search for **Play modules** in the "central Play modules repository":http://www.playframework.org/modules. 
+
+But you can of course specify new custom repositories in the **repositories** section:
+
+bc. # Application dependencies
+
+require:
+    - play 1.2
+    - com.google.guava -> guava r07:
+        transitive: false
+    - commons-lang 3.0:
+        force: true
+    - com.zenexity -> sso 1.0
+
+# My custom repositories
+repositories:
+
+    - zenexity:
+        type:       http
+        artifact:   "http://www.zenexity.com/repo/[module]-[revision].[ext]"
+        contains:
+            - com.zenexity -> *
+
+Using this configuration all dependencies of the **com.zenexity** organisation will be retrieved and downloaded from a remote HTTP server.
+
+
+

documentation/manual/home.textile

@@ -98,6 +98,11 @@ Everything you need to know about Play.
 ## "Fixtures":test#fixtures
 ## "Running the tests":test#running
 ## "Continuous integration":test#continuous
+# "Dependency management":dependency
+## "Dependency format":dependency#format
+## "dependencies.yml":dependency#yml
+## "Conflicts resolution":dependency#conflicts
+## "Adding new repositories":dependency#repositories
 # "Deployment options":deployment
 ## "Standalone Play application":deployment#standalone
 ## "Running on JEE application servers":deployment#appservers

framework/dependencies-1.2.yml

@@ -1,5 +1,5 @@
 
-# Play 1.1
+# Play 1.2
 self: play -> play 1.2
 
 # Don't follow transitive dependencies for this project
@@ -71,7 +71,7 @@ repositories:
 
     - playModules:  
         type:       chain
-        using:
+        using:            
             - playLocalModules:
                 type:       local
                 descriptor: "${play.path}/modules/[module]-[revision]/conf/dependencies.yml"

framework/pym/play/application.py

@@ -66,6 +66,13 @@ def modules(self):
                     print "~"
                 sys.exit(-1)
             modules.append(m)
+        if os.path.exists(os.path.join(self.path, 'modules')):
+            for m in os.listdir(os.path.join(self.path, 'modules')):
+                mf = os.path.join(os.path.join(self.path, 'modules'), m)
+                if os.path.isdir(mf):
+                    modules.append(mf)
+                else:
+                    modules.append(open(mf, 'r').read())
         if self.play_env["id"] == 'test':
             modules.append(os.path.normpath(os.path.join(self.play_env["basedir"], 'modules/testrunner')))
         return modules

framework/pym/play/commands/deps.py

@@ -9,7 +9,7 @@
 COMMANDS = ['dependencies','deps']
 
 HELP = {
-    'dependencies': 'Check for a release newer than the current one'
+    'dependencies': 'Resolve and retrieve project dependencies'
 }
 
 def execute(**kargs):