Rock is first and foremost a rich collection of components. The bundle is what provides a "system view" of this collection, i.e. set of files that allow to manage a system or -- more generally -- functionality out of collection of components.

It contains (but is not limited to)
 - run scripts
 - log convertion scripts
 - log sanity scripts
 - GUIs
 - when using the system management layer, the required models

== Basic Structure ==
  scripts/:: startup scripts (either pure ruby scripts or tooling scripts)
  scripts/gui/:: GUI scripts
  config/orogen/:: configuration files for oroGen tasks
  models/orogen/*.orogen:: extensions to the orogen specifications, dummy orogen specifications (new folder)
  models/typelib/*.rb:: extensions to the typelib types (new folder)
  data/:: system specific data files
  data/migration/:: log migration scripts
  data/sanity/:: sanity checks on log data
  logs/:: base directory under which log files are saved (previously log/ and results/)
  logs/current/:: symlink to the current log directory (i.e. the directory in logs/ where data is currently being produced)

== Additional Elements: System Management Layer ==
  scripts/orocos/:: common scripts for management of a system that uses the rock-roby system management layer (instanciate, run, ...)
  scripts/controllers/:: supervision controller scripts (previously controllers/)
  models/tasks/:: supervision task models (previously tasks/)
  models/orogen/*.rb:: extension to supervision task representing orogen components (previously tasks/orogen/)
  models/planners:: supervision planner models (previously planners/)
  models/blueprints:: supervision planner models (previously planners/)

== Cross-bundle dependencies ==

Bundles can depend on each others, in particular in order to share models. The sharing mechanism is based on:

 * the definition of a ROCK_BUNDLE_PATH environment variable. This path variable is a colon-separated (:) list of paths under which bundles are installed. It is customary to add $prefix/share/rock to the list.
 * dependencies are listed in config/app.yml in the bundle: section, i.e.
{{{
bundles:
  dependencies:
    - rock
}}}
 * the corresponding directories are searched for in the ROCK_BUNDLE_PATH, and found directories are added to the relevant configurations so that scripts, configuration files and models are transparently made accessible.

== Creation ==
Bundles are created using the rock-create-bundle script contained in base/scripts

Newly created bundles contain only the "Basic structure" folder, with in each folder a README.txt file explaining its role and pointing to the relevant documentation on the Rock website or wiki.

== General Usage ==
The currently available bundles, the current selected bundle and the set of bundles that are active (i.e. selected because of dependencies) is displayed by the bundle-info tool. For instance:

{{{
$ bundle-info
Bundles[INFO]: initializing bundle support
Bundles[INFO]:   available bundles:
Bundles[INFO]:     asguard (/media/Data/rock/imoby/asguard)
Bundles[INFO]:     rock.dfki (/media/Data/rock/imoby/bundles/rock.dfki)
Bundles[INFO]:     rock (/media/Data/rock/imoby/bundles/rock)
Bundles[INFO]:     rock-nav (/media/Data/rock/imoby/bundles/rock-nav)
Bundles[INFO]:     asguard (/media/Data/rock/imoby/bundles/asguard)
Bundles[INFO]:   current_bundle: asguard in /media/Data/rock/imoby/asguard
Bundles[INFO]:   selected bundles: asguard
}}}

A new current bundle can be selected using bundle-sel

{{{
$ bundle-sel rock
Bundles[INFO]: initializing bundle support
Bundles[INFO]:   available bundles:
Bundles[INFO]:     rock.dfki (/media/Data/rock/imoby/bundles/rock.dfki)
Bundles[INFO]:     rock (/media/Data/rock/imoby/bundles/rock)
Bundles[INFO]:     rock-nav (/media/Data/rock/imoby/bundles/rock-nav)
Bundles[INFO]:     asguard (/media/Data/rock/imoby/bundles/asguard)
Bundles[INFO]:   current_bundle: rock in /media/Data/rock/imoby/bundles/rock
Bundles[INFO]:   selected bundles: rock
}}}

If you don't want any bundle to be active, just run bundle-unsel

{{{
$ bundle-unsel
$ bundle-info
Bundles[INFO]: initializing bundle support
Bundles[INFO]:   available bundles:
Bundles[INFO]:     rock.dfki (/media/Data/rock/imoby/bundles/rock.dfki)
Bundles[INFO]:     rock (/media/Data/rock/imoby/bundles/rock)
Bundles[INFO]:     rock-nav (/media/Data/rock/imoby/bundles/rock-nav)
Bundles[INFO]:     asguard (/media/Data/rock/imoby/bundles/asguard)
Bundles[INFO]:   no bundle currently selected
}}}

== Usage in Ruby scripts ==

For normal Ruby scripts to use the bundle system, replace:

{{{
require 'orocos'
Orocos.initialize
Orocos.run ... do
end
}}}

by

{{{
require 'rock/bundle'
Rock::Bundles.initialize
Rock::Bundles.run ... do
end
}}}

== Usage in rock-roby ==

rock-roby <toolname> makes sure that the system management layer runs under bundle support already. The now-obsoleted scripts/orocos/* scripts should therefore be used through rock-roby. Instead of:

{{{
scripts/orocos/instanciate -rasguardv3 main corridor_following
}}}

do

{{{
rock-roby -rasguardv3 main corridor_following
}}}