doudou / roby

== Installation
* The Roby engine needs 
  * +utilrb+, which is available either as a gem or on {my research
    page}[http://www.laas.fr/~sjoyeux/research.php]
  * +utilmm+, available on {my research page}[http://www.laas.fr/~sjoyeux/research.php]
  * Facets, available on RubyForge[http://facets.rubyforge.org] or as a gem
  * ActiveSupport, available on RubyForge[http://facets.rubyforge.org] or as a gem

* Build the extension in ext/ using:
    cd ext
    ruby extconf.rb
    make
    ln -s $PWD/bgl.so ../lib/roby
  +utilmm+ must be available to pkg-config (make sure that the +<prefix>/lib/pkgconfig+,
  with <prefix> the directory in which +utilmm+ has been installed is in +PKG_CONFIG_PATH+)

* the Genom bindings need Genom.rb, which in turn needs +typelib+ and +utilmm+. 
  All three are available on {my research
  page}[http://www.laas.fr/~sjoyeux/research.php]

== Graph structures
Event structures are declared in Roby::EventStructure, and task structures are declared
in Roby::TaskStructure

See Roby::RelationSpace, Roby::DirectedRelationSupport and Roby::RelationGraph

== Events
The event structure is described by a graph of Roby::EventGenerator objects. The actual events
are produced when needed by calling the #new method on generators.

Examples of event generators:
* Roby::TaskEventGenerator for event generated by tasks
* Roby::AndGenerator, Roby::OrGenerator, which aggregates a list of events
* Roby::EverGenerator which implements the 'ever' semantic in Roby::EventGenerator#ever

=== Event propagation
Event propagation is done in a synchronous way (well, synchronous-like way). Since Ruby is
not really a 

See Roby::EventGenerator and Roby::Event

== Tasks
=== Inheritance semantics
See Roby::Task

== Planning
The planning is in spirit similar to HTN planning: methods are used to develop 
a task tree. In Roby::Planning::Planner, methods produce Task objects, an can 
call submethods. See Planning::method for the method definitions. These tasks
can then be used to build task relation graphs. Planning#method provides means
to easily build a meaningful task hierarchy:
* the :returns option constrains what kind of task a method can return. Moreover,
  if a method has a return type, then if its return value is used in a realized_by
  relation, the :model option of the relation is set to this return type automatically

=== Inheritance semantics of Planner classes
* added method models, for now one model for each inheritance level. Maybe go
  back at using one model for everybody
* a subclass can overload a specific method by setting :id explicitely
* the :returns option can be overriden as follows:
  - the :returns of a method should be a subclass of the :returns of its model
    and of the overloaded methods (methods in the inheritance hierarchy with the
    same id)
  - you cannot overload a method model, because it would lead to inconsistencies:
    if a method in the parent planner is defined w.r.t. the parent method model,
    then this method could be inconsistent with the method model defined in the 
    submodel
* a model is frozen as soon as a method is defined based on it

See Roby::Planning and Roby::Plan

== Genom adaptor
Genom requests are automatically mapped on Task objects. Genom modules are represented
by a Roby::Genom::RunnerTask task.

See Roby::Genom