Difference between revisions of "YARP 2.4 Migration"

From Wiki for iCub and Friends
Jump to: navigation, search
m
 
(44 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Under_construction}}
+
''This page is still work in progress and may change''.
  
Migrating from YARP 2.3 to YARP 2.4 might require some changes to your code.
+
Migrating from YARP 2.3 to YARP 2.4 might require some changes to your code. Notice that before the release of YARP 2.4 these changes are in the master branch of the repository (version 2.3.60).
 +
 
 +
== Changes in YARP ==
 +
 
 +
* The main different was in the policy used in YARP to organize and search for configuration files has changed heavily: see [[ResourceFinder]]
 +
 
 +
* Devices:
 +
 
 +
controlBoardWrapper2
 +
analogServer
 +
virtualAnalogServer
 +
 
 +
from icubmod have been moved to YARP. The versions in icubmod are deprecated and will be removed.
 +
 
 +
* Added new interfaces for:
 +
** Controlling subset of joints [http://wiki.icub.org/yarpdoc/classyarp_1_1dev_1_1IPositionControl2.html IPositionControl2], [http://wiki.icub.org/yarpdoc/classyarp_1_1dev_1_1IVelocityControl2.html IVelocityControl2]
 +
** Control the position directly (bypassing the minimum-jerk trajecotory generator) [http://wiki.icub.org/yarpdoc/classyarp_1_1dev_1_1IPositionDirect.html IPositionDirect]
 +
 
 +
* Full revision of yarprun. Notice: now when you run yarprun server (e.g. yarprun --server /node) two processes with the same name are created and appear in the process list (the first one to receive commands and the second to fork processes). This is normal.
 +
 
 +
== Things that change in iCub ==
 +
 
 +
* ICUB_ROOT
 +
** Remove references to ICUB_ROOT in ResourceFinder configuration
 +
** No need to set ICUB_ROOT environment variable
 +
** $ICUB_ROOT/ICUB_ROOT.ini is obsolete
 +
** Files that used to be in $ICUB_ROOT/app are now in $ICUB_DIR/app or installed in /usr/local with the binaries (depending on how you compile the code) (see changes to the ResourceFinder in the previous section). If existing old files in $ICUB_ROOT/app should be removed.
 +
 
 +
* Target ''install_application'' and ICUB_INSTALL_APPLICATIONS CMake flag removed, now applications and other files are with the binaries both in the build and in the installation directory
 +
 
 +
* Updated installation instructions:
 +
 
 +
[[ICub Software Installation]]
 +
 
 +
* Repository description [[Better_Repository]] and CMake templates in particular have been updated:
 +
 
 +
[[Simple template for modules in main]]
 +
 
 +
[[Simple template for libraries in main]]
 +
 
 +
[[Simple template for modules in contrib]]
 +
 
 +
[[Simple template for libraries in contrib]]
 +
 
 +
* Improved '''but changed''' compilation of modules in '''contrib'''. Before you compile modules in contrib you have to set up the ''contrib'' package (this is described in the installation instructions)
 +
 
 +
* CMake functions for applications like icub_app()/icub_app_install() are obsolete, use yarp_install() instead
 +
 
 +
* YARP_ROBOT_NAME environment variable replaces ICUB_ROBOTNAME
  
 
== List of incompatible changes ==
 
== List of incompatible changes ==
Line 18: Line 66:
 
     include(something)
 
     include(something)
  
 +
==== <code>add_library</code> inside a <code>PLUGIN_LIBRARY</code> block ====
  
== Ongoing discussions ==
+
In order to add a plugin, in YARP 2.3 you had to use <code>add_library</code> inside a <code>YARP_{BEGIN,END}_PLUGIN_LIBRARY</code> block.
 
+
This is no creates a plugin, you should use <code>yarp_add_plugin</code> instead.
=== libYARP_dev ===
 
 
 
The key point here is to clearly define what should be visible and reachable from outside the library and what shouldn't.
 
 
 
In our understanding, the goal of this library is mainly to provide general virtual interfaces without implemetation, and some devices already implemented. <br>
 
In the former category fall interfaces like <code>IPositionControl, IVelocityControl, IFrameGrabberControlsDC1394 </code> and so on, in the latter category falls devices like <code>controlboard, serverInertial, remoteFrameGrabber</code> and so on...
 
 
 
Those devices are meant to be instatiated by the factory and the accessed using the public interfaces, e.g.
 
 
 
PolyDriver poly;
 
poly.open("device", "controlboard");
 
IPositionControl *iPos;
 
poly.view(iPos);
 
iPos->...
 
  
BUT, since all headers are public and installed, an user could also instantiate devices using other methods like simply <br>
+
==== Imported Targets ====
new RemoteFrameGrabber;
 
and even create new classes derived from those devices.
 
  
'''''And in fact they do.'''''
+
In YARP 2.3 and previous versions, YARP cmake target were exported without namespace, starting from YARP 2.4 they are exported with the "YARP::" namespace. Therefore you can no longer link <code>YARP_OS</code>, but you have to link <code>YARP::YARP_OS</code>. If you are linking the <code>${YARP_LIBRARIES}</code> variable, the behaviour is not changed.
  
This is a snippet from FrameGrabberGUIControl2 (iCub/tools)
+
==== <code>YARP_ADMIN</code> ====
  
class FrameGrabberGUIControl2 : public Gtk::Window, virtual public yarp::dev::RemoteFrameGrabberControlsDC1394
+
The <code>YARP_ADMIN</code> environment variable is no longer considered by CMake.
{
 
...
 
}
 
  
The same thing can be done using the "factory + interface" idea.
+
=== yarp/os ===
  
FrameGrabberGUIControl2::FrameGrabberGUIControl2(char* loc, char* rem)
+
* The headers <code>begin_pack_for_net.h</code> and <code>end_pack_for_net.h</code> are deprecated in favour of the macros <code>YARP_BEGIN_PACK</code> and <code>YARP_END_PACK</code> in <code>yarp/conf/system.h</code>.
{
 
  yarp::dev::PolyDriver grabberDev;
 
  yarp::dev::IFrameGrabberControlsDC1394 * iGrabber;
 
  yarp::os::Property config;
 
  config.put("remote",rem);
 
  config.put("local",loc);
 
  config.put("device", "remote_grabber");
 
  grabberDev.open(config);
 
  grabberDev.view(iGrabber);
 
  iGrabber->XXX
 
}
 
  
I did this changes in this class and it compiles fine (I haven't tried to run it, however).
+
* yarp::os::Module is deprecated and should be replaced by yarp::os::RFModule.
  
So the philosophical question is: should we allow user to do whatever he/she likes with devices or restrict the usage in the "factory + interface" fashion?
+
* the header <yarp/os/Bottle.h> no longer includes <yarp/os/Value.h>, therefore this file must be included when calling yarp::os::Value methods.
  
If this is the case a way of doing it is to create a subfolder for the devices with implementation and keep there their headers and implementation files without installing them.
 
  
Pros:
+
=== GUIs and tools ===
* User is forced to use the factory because it cannot have direct access to the real device anymore
 
* Helper classes used by a device internally will not be exported in the library avoid name conflict problem from the root.
 
  
Cons:
+
* <code>yarpmanager</code> tool was renamed <code>yarpmanager-console</code>
* Derived classes that now use the other way of access devices needs to be modified
+
* <code>gyarpmanager</code> GUI was renamed <code>yarpmanager</code>
* If derived devices need to have access to something currently not exported by the interfaces, it won't work unless the interface is expanded (btw for the FrameGrabberGui I saw it's not the case)
+
* <code>gyarpbuilder</code> GUI was renamed <code>yarpbuilder</code>
* Remember this change could involve devices outside iCub repo.
 

Latest revision as of 09:46, 8 January 2016

This page is still work in progress and may change.

Migrating from YARP 2.3 to YARP 2.4 might require some changes to your code. Notice that before the release of YARP 2.4 these changes are in the master branch of the repository (version 2.3.60).

Changes in YARP

  • The main different was in the policy used in YARP to organize and search for configuration files has changed heavily: see ResourceFinder
  • Devices:
controlBoardWrapper2
analogServer 
virtualAnalogServer

from icubmod have been moved to YARP. The versions in icubmod are deprecated and will be removed.

  • Full revision of yarprun. Notice: now when you run yarprun server (e.g. yarprun --server /node) two processes with the same name are created and appear in the process list (the first one to receive commands and the second to fork processes). This is normal.

Things that change in iCub

  • ICUB_ROOT
    • Remove references to ICUB_ROOT in ResourceFinder configuration
    • No need to set ICUB_ROOT environment variable
    • $ICUB_ROOT/ICUB_ROOT.ini is obsolete
    • Files that used to be in $ICUB_ROOT/app are now in $ICUB_DIR/app or installed in /usr/local with the binaries (depending on how you compile the code) (see changes to the ResourceFinder in the previous section). If existing old files in $ICUB_ROOT/app should be removed.
  • Target install_application and ICUB_INSTALL_APPLICATIONS CMake flag removed, now applications and other files are with the binaries both in the build and in the installation directory
  • Updated installation instructions:

ICub Software Installation

  • Repository description Better_Repository and CMake templates in particular have been updated:

Simple template for modules in main

Simple template for libraries in main

Simple template for modules in contrib

Simple template for libraries in contrib

  • Improved but changed compilation of modules in contrib. Before you compile modules in contrib you have to set up the contrib package (this is described in the installation instructions)
  • CMake functions for applications like icub_app()/icub_app_install() are obsolete, use yarp_install() instead
  • YARP_ROBOT_NAME environment variable replaces ICUB_ROBOTNAME

List of incompatible changes

This is a list of incompatible changes from YARP 2.3 series to YARP 2.4

CMake

YARP_MODULE_PATH

cmake variable YARP_MODULE_PATH is a real "PATH" and therefore could be a list and not a single directory. This might break in a few cases (i.e. when used in include(${YARP_MODULE_PATH}/something.cmake)) There are 2 options to fix this:

  • Use the variable YARP_MODULE_DIR instead of YARP_MODULE_PATH:
    include(${YARP_MODULE_DIR}/something.cmake)
  • Add YARP_MODULE_PATH to the CMAKE_MODULE_PATH variable and use the filename without the path and the extension :
    set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${YARP_MODULE_PATH})
    include(something)

add_library inside a PLUGIN_LIBRARY block

In order to add a plugin, in YARP 2.3 you had to use add_library inside a YARP_{BEGIN,END}_PLUGIN_LIBRARY block. This is no creates a plugin, you should use yarp_add_plugin instead.

Imported Targets

In YARP 2.3 and previous versions, YARP cmake target were exported without namespace, starting from YARP 2.4 they are exported with the "YARP::" namespace. Therefore you can no longer link YARP_OS, but you have to link YARP::YARP_OS. If you are linking the ${YARP_LIBRARIES} variable, the behaviour is not changed.

YARP_ADMIN

The YARP_ADMIN environment variable is no longer considered by CMake.

yarp/os

  • The headers begin_pack_for_net.h and end_pack_for_net.h are deprecated in favour of the macros YARP_BEGIN_PACK and YARP_END_PACK in yarp/conf/system.h.
  • yarp::os::Module is deprecated and should be replaced by yarp::os::RFModule.
  • the header <yarp/os/Bottle.h> no longer includes <yarp/os/Value.h>, therefore this file must be included when calling yarp::os::Value methods.


GUIs and tools

  • yarpmanager tool was renamed yarpmanager-console
  • gyarpmanager GUI was renamed yarpmanager
  • gyarpbuilder GUI was renamed yarpbuilder