|
|
|
Dependencies
Project Zero provides tools to help you manage your application’s dependencies and share your applications and libraries with others.
Dependency management
Zero uses a dependency management utility called Ivy to ensure that your application is using the right versions of the libraries you declare as dependencies. In Ivy, these libraries are called modules. A module represents an artifact, which is code packaged as either a JAR file or a Zero ZIP file. You declare the modules your application needs to run in an XML file called an Ivy file. Zero then uses Ivy to resolve your application’s dependencies. “Resolve” means that Ivy searches a chain of repositories to find a module that matches the dependency you declared. Ivy can search the local repository that Zero creates on your system, or it can search remote repositories such as the Project Zero package repository. When a match is found, Ivy downloads the module’s artifact into your local repository (if it isn’t already there), and updates your application’s classpath to include the dependency.
 Note: It's up to you to make sure you are following the license agreement for any dependencies you specify in the development of your applications, and that Zero downloads for you.
Repositories
An Ivy repository is simply a collection of artifacts stored in a structured format that Ivy can understand. Repositories are typically accessed through file system or HTTP interfaces. Repositories can store different versions of modules, so you can declare which specific version you need.
Local repository
When you first install Zero, a local repository is created on your system to store artifacts. All downloaded artifacts are placed into your local repository. Zero looks in your local repository for matching dependencies first. If a dependency can not be found locally, you have the option of telling Zero to look for it in remote repositories.
Note: Within Eclipse, Zero will look in your workspace for open Projects that match your dependency declaration before looking in the local repository.
The local repository is created in your <user.home> directory by default.
On Windows, the local repository can typically be found at
<root>:\Documents and Settings\<username>\zero
On Linux, the local repository is typically at
/home/<username>/zero
The location of the local repository can be changed by configuring the file <zerohome>/config/ivy/local.properties when using the Command Line Interface, or through the Window > Preferences > Zero Repositories page in Eclipse. If you are using the command-line, then change the local.root property to a new path.
To manage the artifacts stored in your local repository in Eclipse, go to the menu Zero > Manage Repository. From this screen (shown below), you can remove modules from the local repository or search for new modules in your remote Ivy repositories. See Remote Repositories, below, for more information on searching remote repositories.
To manage your local repository from the Command Line Interface, you can use the following commands:
| Command | Example | Description |
|---|
zero get org:module[:revision] | zero get zero:zero.core | Downloads the latest Zero core into your local repository |
zero delete org:module:revision | zero delete zero:zero.TestSvc:1.0.0 | Removes TestSvc 1.0.0 from your local repository |
zero list [-remote true] | zero list | Lists the modules in your local (or remote) repository |
For more details, see the Command Line Interface reference.
Zero can look in remote repositories for dependencies if they can’t be found on the local system. Remote repositories are file servers with an HTTP interface. The remote repositories can either use an Ivy format or a Maven format. Zero repositories use an Ivy format. Maven is a build utility that has similar dependency management capabilities to Ivy.
Zero is configured to look for dependencies in two remote locations by default:
| Repository | Format | Location | Contents |
|---|
| Zero Latest Package Repository | Ivy | http://www.projectzero.org/repo/zero.repo.latest/ | Zero packages |
| Maven | Maven | http://repo1.maven.org/maven2/ | A large open source repository, containing many open source artifacts, such as those from Apache |
You can configure Zero to look in additional or different remote repositories.
If you are using the Command Line Interface, edit the file
<zerohome>/config/ivy/remote.properties
zero.1=http://www.projectzero.org/repo/zero.repo.latest/
maven.2=http://repo1.maven.org/maven2/
The repositories will be searched in the numerical order listed. Ivy repositories must be labeled as zero.#, while Maven repositories must be labeled as maven.#. No two repositories should use the same number.
To configure the remote repository chain from Eclipse, go to Window > Preferences > Project Zero. You can also search remote Ivy repositories for new artifacts through the local repository management screen, accessible through the menu Zero > Manage Repository.
 Note: Searching Maven repositories using the Eclipse Zero Repositories interface is not supported at this time. To locate artifacts in a Maven repository such as http://repo1.maven.org/maven2/, try browsing using the Java package name as the directory structure, e.g. org/apache/... Keep drilling down until you get into a specific version of the package with a .pom file. Open the .pom file and extract the following information:
Add a new dependency to your ivy.xml file as described in Declaring Dependencies in ivy.xml, below, and resolve.
Declaring dependencies
You can declare dependencies for your application by configuring your ivy.xml file, which is located in your application’s config directory.
Each dependency declaration is made up of three parts: an organization (org), a module name (name), and a revision matching pattern (rev). For Zero dependencies, org is always “zero”. Module name is usually the same as the application name. Revision is a pattern that specifies the specific version of the artifact that your application needs, or it is a pattern such as “1.0.0+”. “1.0.0+” means match any version from 1.0.0 up to but not including version 1.0.1.
The following is an example of getting Derby from a Maven server and zero.data from the Zero repository server.
<dependencies>
<dependency org="org.apache.derby" name="derbyclient" rev="10.1.1.0"/>
<dependency org="zero" name="zero.data" rev="1.0.0+"/>
</dependencies>
Declaring dependencies in Eclipse
The Zero Eclipse plugin offers several options for configuring dependencies. First, Zero supplies an editor for ivy.xml files that looks like this:
Clicking the “Add…” button will allow you to add dependencies from the local repository to your application. You can also add dependencies manually to the ivy.xml by clicking on the “Source” tab at the bottom of the page. When you close this window, the ivy.xml file will be saved, and your new dependency list will be resolved. If successful, your application’s classpath will be updated with the new list of dependencies.
You can also add dependencies to your project through the project’s Properties page by clicking on Java Build Path > Libraries. Select “Zero Resolved Libraries” and click “Edit” to select additional dependencies from the local repository.
Resolving dependencies
Resolving dependencies in Eclipse
In Eclipse, Zero will generally resolve the dependencies of your projects automatically any time a change is made to a project’s dependency list, either through editing the ivy.xml or the Zero Resolved Libraries container.
When resolving in Eclipse, Zero searches in the following locations for dependencies, in order:
- Open projects in your workspace, regardless of their revision number
- Your local repository. If a match has not been found yet, Zero will prompt you to see if you want to look in the remote chain for missing dependencies.
- Remote repositories. By default, the remote repositories searched are the Zero package repository and the Maven repository.
You can also force a resolve by right-clicking on your project and selecting Zero Tools > Resolve. If you want to remotely update the versions of all of your dependencies for all of your open projects, you can click on the menu option Zero > Update Dependencies, or the Update Dependencies icon on the toolbar.
Troubleshooting resolves in Eclipse
If you want to see exactly which dependencies your application picked up during a resolve, look in your application’s “reports” folder. Right-click on the XML file in this directory and select “Open with…->System Editor”. Your browser should open a nicely formatted report describing the versions of all the dependencies resolved for your application.
Resolving dependencies with the command line interface
To resolve dependencies from the command line, change into your application’s directory and type
zero resolve
This command will look in your local repository for dependencies and update your application’s classpath accordingly. An error will be returned if any dependencies are not found. To look for dependencies remotely, execute
zero resolve –remote true
followed by another
zero resolve
to update your application’s classpath.
Troubleshooting resolves from the command line
If you want to see exactly which dependencies your application is using, open the XML file in your application’s “reports” directory with a web browser. Your browser should display a nicely formatted report describing the versions of all the dependencies resolved for your application.
Packaging to publish
Zero uses standard ZIP files for packaging. If you are going to package your application to share with others, you should update your ivy.xml file to include information about your package, such as author (ivyauthor), organization (organisation and org), version (revision), license, and description. From a Zero perspective, the elements you should be sure to have correct are the organization, module, and revision. These fields are used for naming your package and dependency resolution using Ivy.
<info organisation="zero" module="ETestApp2" revision="1.0.0">
<license name="type of license" url="http://license.page"/>
<ivyauthor name="AuthorsName" url="http://authors.home.page"/>
<description homepage="http://module.description.page"/>
</info>
<publications>
<artifact org="zero" name="ETestApp2" type="zip" />
</publications>
To create a Zero package in Eclipse, simply right click on your project and select "Export...->Zero->Project Zero Export Wizard. You can then specify the directory to export to (<apphome>/export by default) and optionally include your source files. Note: you must include source if you plan to import the project back into Eclipse. A ZIP file will be created in that directory with the name module-revision.zip, e.g. ETestApp2-1.0.0.zip.
To create a Zero package with the Command Line Interface, change to your application's directory and type zero package. A file with with the naming pattern module-revision.zip will be created in your application's export directory.
If you want to make your package available for other application's on your system to use, you can publish it to your local repository using zero publish. Once a package has been published to the local repository, other applications can declare dependencies on it. To verify that your package has been published, you can use the zero list command to view the local repository.
Sharing and using Zero packages
Zero ZIP files can easily be shared with other developers.
To use a Zero ZIP file from the Command Line Interface:
- Unzip the file into your <zerohome>/apps directory.
- Change into the application's directory.
- Execute
zero resolve to resolve any dependencies the application has.
- If the package contained an application, execute
zero run to run it.
- If the package contained a library, execute
zero publish to publish it to your local repository so that your applications can include it in their dependencies.
To import a Zero ZIP file into Eclipse (note: the ZIP must contain source)
- Select "File->Import->Existing Projects into Workspace.
- Select "Select archive file" and browse to the ZIP's location.
- Select the project and click Finish.
- Right click on the project in the Package Explorer and select Zero->Resolve to resolve the package's dependencies.
Version format of Project Zero libraries
Version Defined:
The Project Zero libraries use the following version format:
major.minor.revision[.qualifier]
- major - [0-9]+ - denotes potentially breaking changes - libraries with different major version numbers may not be compatible
- minor - [0-9]+ - denotes feature changes - libraries with different minor version numbers are compatible
- revision - [0-9]+ - denotes the Subversion revision number - this number by itself can be used to uniquely identify a library, and thus to rebuild a specific version from source
- qualifier (optional) - [a-zA-Z0-9]* - this part of the version is lexigraphically matched, it has no specific reservation, but it is currently being used to categorize versions into milestones, for example M1. When an official full release is reached the qualifier will be dropped.
Version examples:
- 1.0.3207.M1 - milestone build: major = 1, minor = 0, svn revision = 3207, part of milestone 1
- 1.0.3405 - official release build: major = 1, minor = 0, svn revision = 3405
|
