forked from playframework/play1
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation for dependency management
- Loading branch information
1 parent
131bd68
commit 065fd1d
Showing
52 changed files
with
341 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
~ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.