If any of the following is true:

• You often change from one OSGi platform to another.
• You don't know what OSGi is, but want to spend half an hour checking it out.
• You can't be bothered about following the setup and requirements README for the OSGi platform of your choice.
• You have problem to get the OSGi platform working at all.

then perhaps the Pax Runner can help. And it will not take you very long to find out, just read the easy installation steps. You have some questions? Maybe they are already answered.

How Pax Runner helps you

• Quick start up
  You have a set of bundles you just developed or wanna test? Just place them all in the same folder, start a command prompt, go to your folder and type "pax-run". That simple.
• Easy run on different platforms
  If you need to run your set of bundles under different platform runner helps you. You just have to type the name of your platform. That simple.
• Easy running in different contexts
  As runner supports multiple provisioning sources, you could easily define sets of bundles that should be installed together with your bundles. You could for example have sets of bundles that you use in different development lifecycle steps, like dev, test and production. Or maybe you wanna test how your bundles behave depending on the availability of different services.

Other resources

• Pax Runner - Change Log — Details about what is changed in each release
• Pax Runner - Design — Detailed explanations about Pax Runner internal design
• Pax Runner - Download — Download archive.
• Pax Runner - FAQ — Frequently Asked Questions.
• Pax Runner - Modules — List of modules that makes up Pax Runner.
• Pax Runner - Options — Detailed startup options.
• Pax Runner - Resources — Divers resources
• Pax Runner - Screencasts — Watch screen casts related to Pax Runner

Installation instructions

Follow this steps in order to install pax runner or watch a screencast:

1. Download the latest version (0.16.0) from below or checkout older versions:
   • java 1.5 and beyond: zip tar.gz
   • java 1.4: zip tar.gz
2. Unpack the downloaded archive to an arbitrary folder
3. Optional: set the PATH to include also the bin directory from the unpacked directory so you will be able to execute pax-run from anywhere.
4. Go to the folder containing your bundles and execute pax-run. Note that this is just an example of how you could start pax runner. For other ways see how do you start it up (for jdk 1.4 use pax-run-1.4)

How do you start it up

pax-run [--option]* [provision_spec]*

where:

• option : optional; a start up option. Can be zero, one or more.
• provision_url : optional; a provision specification. Can be zero, one or more.

DOS/Windows users have to enclose every option between quotes ("). Check FAQ for details.

Debugging with Pax Runner

pax-run --vmOptions=-agentlib:jdwp=transport=dt_socket,server=y,address=8000

Then you can use your IDE, such as Eclipse IDE, to attach debugger to localhost port 8000.

If you use <tt>mvn pax:provision</tt>, create a file named <tt>runner.args</tt> and put <tt>--vmOptions=-agentlib:jdwp=transport=dt_socket,server=y,address=8000</tt> in it. Or you can use Maven goal configuration <tt>args</tt> that specifies the file name (<tt>runner.args</tt> is default).

More about Java JPDA debugging info here: http://articles.techrepublic.com.com/5100-10878_11-6139512.html

Provision urls

A provision specification is an URL like string that is understood by one of the scanners. Default value is "./*.jar" meaning that will scan the folder from where runner was started for all the jar files and will install them via Scanner - Directory.
If no provision schema is specified, runner will try to determine the correct schema based on the extension of your file as follow:

If there is no protocol specified and runner can find a file that matches it will automatically transform it to an valid file url. This means that you can simply use a provision url as mybundles.txt and runner will resolve it for you from the current folder.

Options

If the default settings of runner does not suit you below you can find a set of usual options that allow you to control runner behavior (listed alphabetically).
For a detailed list of options take a look at this page.

Legend

• - stands for: implemented
• - stands for: under development
• - stands for: in design phase
• - stands for: only an idea

Source code

https://scm.ops4j.org/repos/ops4j/projects/pax/runner ( or browse via FishEye )
This project builds with Apache Maven and uses Apache Felix's maven-bundle-plugin, and Peter Krien's bnd tool.

Issue tracker

Issues, bugs, and feature requests can be submitted to the issue tracking system.

Previous versions

For information on Pax Runner releases before 0.5.0 visit this page.