Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Virgo/Build"

m
Line 105: Line 105:
 
|}
 
|}
  
=== Repository Map  ===
+
== Repository Map  ==
  
 
By default, Ripplor checks out each repository working copy to the working directory that it was run from. For most people, this isn't a good idea as it can pollute the filesystem. To account for this, Ripplor takes a repository map file. This file tells Ripplor where to checkout a repository working copy to. The file itself is a simple mapping from a repository name to a filesystem location.  
 
By default, Ripplor checks out each repository working copy to the working directory that it was run from. For most people, this isn't a good idea as it can pollute the filesystem. To account for this, Ripplor takes a repository map file. This file tells Ripplor where to checkout a repository working copy to. The file itself is a simple mapping from a repository name to a filesystem location.  

Revision as of 03:42, 23 April 2010



Virgo has its own build system known as "Virgo build" which is a collection of Any/Ivy scripts.

Prerequisites

Make sure you have git, Java 6 or later, and ant 1.7.1 or later installed.

Building Individual Repositories

To build a given git repository, first clone it:

git clone <repository URL>

and then make sure that the Virgo build submodule is correctly initialised by changing directory to the cloned repository and issuing:

git submodule update --init

then change directory into the build-xxx directory and invoke ant with the appropriate targets, usually:

ant clean clean-integration test

Note: at the time of writing, Virgo build is still to be checked in and linked into each repository. Until that is done, you cannot build anything.

This will do a fresh build and run all the unit and integration tests. It will only report "Build successful" if everything compiles cleanly and all the tests pass.

ant -p displays commonly used targets. Use "ant clean-ivy" to delete the ivy cache (or use git clean -dfx to get everything back to a reset state, including ditching any changes you haven't committed).

If you simply want to compile the runtime code, you can use "ant clean clean-integration jar" but that will not compile (or run) the tests.

"ant precommit" performs more extensive checks including code coverage and findbugs.

Building the packaged web server is somewhat different:

ant clean clean-integration jar package smoke-test

You can also use the "package" target in the kernel to build a standalone kernel:

ant clean clean-integration test package

Building the documentation is different too:

ant doc

Updating Dependencies

In general, dependencies are declared in files named ivy.xml.

Dependencies between Virgo components are a special case of this. The properties file build.versions in the root directory of each git repository defines the versions of the Virgo components that the build will download. Updating any of the versions in build.versions is error-prone as the same values occur in certain other files (which cannot use property substitution). To update a version in build.versions, run the "update dependency" script, for example:

~/virgo/web-server/scripts/update-dependency.sh -v <variable> -n <new version> 

where <variable> is the relevant property name in build.versions and <new version> is the replacement version. The script will report the changes it makes and may issue warnings, so pay attention to its output.

"Rippling"

Since the Virgo components form a directed, acyclic graph, changing the graph to use a new version of a specific component involves not only updating that version throughout the graph, but also updating the versions of the components which have been changed. This is the tedious process known as "rippling" and so the "ripplor" script was written to automate it. Essentially, ripplor handles the most commonly updated components and flattens the dependency graph into a linear sequence, e.g.:

osgi-test-stubs
osgi-extensions
util
test
medic
artifact-repository
kernel
web
apps
documentation
web-server

So, for example, if you change the kernel and want to produce a package web server containing the updated kernel, you would run:

~/virgo/web-server/scripts/ripplor/ripplor.rb -r kernel

This would build and publish a new version of the kernel, update the dependency of the web layer on the newly built kernel, build and publish a new version of the web layer, update the dependency of the Virgo-supplied applications on the newly built web layer and kernel, and so on until it builds and publishes a new version of the packaged web server.

Please note at the time of writing, ripplor still needs to be converted to publish into the Eclipse infrastructure. For now, you'll have to use the "update dependency" script to perform a manual ripple.

Prerequisites

  1. Ruby must be installed
    • If you do not have this,
      sudo port install ruby
      will install it for you
  2. RubyGems must be installed
    • If you do not have this,
      sudo port install rb-rubygems
      will install it for you
  3. Rubygem
    choice
    must be installed
    • If you do not have this,
      sudo gem install choice
      will install it for you

When should Ripplor be used?

In general, Ripplor is used any time a change needs to be propagated up the graph of dependent repositories. There are two main cases that cause this to happen.

  1. An external dependency needs to be upgraded in all modules of dm Server
  2. A change has been made to code in a repository (e.g. the kernel) and the code above (i.e. the web layer, Virgo-supplied applications, etc.) needs to be updated to see the changes.

Usage

Usage: ripplor.rb [-rvm] 

Required arguments: 

    -r, --repo=REPO                  The name of the starting repo

Optional arguments: 

    -v, --version=VARIABLE:VERSION   A version to substitute during the ripple
   -m, --map=REPO-MAP               The property file containing a mapping from a repository name to a location
                                    (defaults to ~/repository.map)
Option Description
-r The name of the repository you want to start the ripple at. A typical repository name is util or kernel.
-v When updating a dependency use this flag to describe both the variable to update and the new version to update to. Can be a comma separate list if multiple dependencies need updating at the same time.
-m The location of the repository map file (see below). By default, this file is found in ~/repository.map, but in cases where you have more than one file (one for simple ripples, one for complex ripples that happen in your working copy) you may need to pass in this value.

Repository Map

By default, Ripplor checks out each repository working copy to the working directory that it was run from. For most people, this isn't a good idea as it can pollute the filesystem. To account for this, Ripplor takes a repository map file. This file tells Ripplor where to checkout a repository working copy to. The file itself is a simple mapping from a repository name to a filesystem location.

osgi-extensions=~/dev/ripplor/osgi-extensions
util=~/dev/ripplor/util
...

Tip: in the repository map file,

~

will be expanded to the current user's home directory.

Broken Build

Ripplor is smart enough to restart a failed ripple. If a ripple fails (due to test or compile failure), simply fix any problems in the working copy that Ripplor is using and restart the ripple at the same location you originally used. Ripplor will bring in any new commits since you last started the ripple and continue up the stack as done previously. This behavior is very useful if you are rippling a breaking API change and need to fix code as the ripple moves upwards.

Examples

Upgrading the version of Spring used in util and upward:

./ripplor.rb -r util -v "org.springframework:3.1.0.RELEASE" -m ~/ripple.repository.map

Rippling a breaking API change to kernel

./ripplor.rb -r kernel -m ~/workingcopy.repository.map<pre>

Back to the top