Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
doc:catkin_migration [2014/09/10 15:52]
admin [Changelog]
doc:catkin_migration [2014/12/07 07:53] (current)
admin
Line 1: Line 1:
 ====== Migrating to the catkinized version of KnowRob ====== ====== Migrating to the catkinized version of KnowRob ======
  
-Starting from ROS hydro/​indigo,​ KnowRob has switched to the catkin buildsystem and the [[http://​wiki.ros.org/​rosjava|'​new'​ rosjava]]. This page explains the steps that are needed for transforming packages that have been built for the old version to the new KnowRob.+Starting from ROS hydro/​indigo,​ KnowRob has switched to the catkin buildsystem and the [[http://​wiki.ros.org/​rosjava|'​new'​ rosjava]]. This page explains the steps that are needed for transforming packages that have been built for the old version to the new KnowRob. ​**This page is aimed at maintainers of KnowRob packages that would like to upgrade them from the rosbuild- to the catkin-based version.**
  
 ===== Catkinization ===== ===== Catkinization =====
  
-As a first step, you can use the [[http://​wiki.ros.org/​catkin/​migrating_from_rosbuild#​Migration_Help_-_.22Catkinize.22_Scripts|'​catkinize'​ scripts]] that generate ​something ​like a valid catkin package from your rosbuild packages. The following manual steps are then +As a first step, you can use the [[http://​wiki.ros.org/​catkin/​migrating_from_rosbuild#​Migration_Help_-_.22Catkinize.22_Scripts|'​catkinize'​ scripts]] that generates ​something ​close to a valid catkin package from your rosbuild packages. The following manual steps are then 
-  * Clean up the package.xml,​ e.g. setting the author and maintainer names and emails. Please check for [[https://​github.com/​knowrob/​knowrob/​issues/​18|package names that may have changed]]. +  * Clean up the package.xml,​ e.g. setting the author and maintainer names and emails. Please check for package names in KnowRob  ​[[https://​github.com/​knowrob/​knowrob/​issues/​18|that may have changed]]. 
-  * Update the CMakeLists.txt, also update changed package names. Remove all rosbuild and old rosjava statements, e.g. for generating .owl from .owl.in files.+  * Update the CMakeLists.txt ​and update ​all changed package names also there. Remove all rosbuild and old rosjava statements, e.g. those for generating .owl from .owl.in files.
  
 ===== Converting Java packages ===== ===== Converting Java packages =====
  
-Rosjava uses the gradle ​builsystem ​that is at the moment (07/2014) only loosely integrated with catkin. Therefore, some things like dependencies ​need to be specified multiple times. Make sure to read the official documentation in the [[http://​wiki.ros.org/​rosjava|ROS wiki]] as well as the [[http://​rosjava.github.io/​rosjava_core/​latest/​|rosjava_core Sphinx documentation]] carefully to understand the main concepts first. ​+Rosjava uses the gradle ​buildsystem ​that is at the moment (12/2014) only loosely integrated with catkin. Therefore, some information such as dependencies ​needs to be specified multiple times. Make sure to read the official documentation in the [[http://​wiki.ros.org/​rosjava|ROS wiki]] as well as the [[http://​rosjava.github.io/​rosjava_core/​latest/​|rosjava_core Sphinx documentation]] carefully to understand the main concepts first. ​
  
 ==== Package structure ==== ==== Package structure ====
  
-There is a one-to-many relation between catkin packages and rosjava sub-projects as described [[http://​wiki.ros.org/​rosjava/​Anatomy%20of%20a%20RosJava%20Package|here]]. This structure has been adopted in KnowRob: In each KnowRob package that contains Java code, there is a folder with the same name containing the respective rosjava subproject. In case the package requires custom messages, there is another [[http://​wiki.ros.org/​rosjava/​Tutorials/​hydro/​Unofficial%20Messages|subfolder with the name of the message package]]. ​ +There is a one-to-many relation between catkin packages and "rosjava sub-projects" ​as described [[http://​wiki.ros.org/​rosjava/​Anatomy%20of%20a%20RosJava%20Package|here]]. This structure has been adopted in KnowRob: In each KnowRob package that contains Java code, there is a folder with the same name containing the respective rosjava subproject. In case the package requires custom messages, there is another [[http://​wiki.ros.org/​rosjava/​Tutorials/​hydro/​Unofficial%20Messages|subfolder with the name of the message package]]. This structure can be created using the tools in [[http://​wiki.ros.org/​rosjava_build_tools/​Tutorials/​hydro/​Creating%20Rosjava%20Packages|rosjava_build_tools]]. For example, the json_prolog package (depending on the service defined in json_prolog_msgs) looks like this:
-This structure can be created using the tools in [[http://​wiki.ros.org/​rosjava_build_tools/​Tutorials/​hydro/​Creating%20Rosjava%20Packages|rosjava_build_tools]]. +
- +
-For example, the json_prolog package (depending on the service defined in json_prolog_msgs) looks like this:+
  
     json_prolog_msgs ​       <-- catkin package     json_prolog_msgs ​       <-- catkin package
Line 38: Line 35:
       |- package.xml       |- package.xml
       \- ...       \- ...
 +
  
 ==== JAR files and build dependencies ==== ==== JAR files and build dependencies ====
-Rosjava is now based on Maven that '​magically' ​maintains jar files for dependendies. The following snippet explains how dependencies are specified in the build.gradle of the respective subproject:+Rosjava is now based on Maven that maintains ​a central repository of jar files for dependencies. The following snippet explains how dependencies are specified in the build.gradle of the respective subproject:
 <code java> <code java>
     dependencies {     dependencies {
Line 54: Line 52:
 </​code>​ </​code>​
 You can use the service at http://​gradleplease.appspot.com/​ to generate the lines to be put into the build.gradle You can use the service at http://​gradleplease.appspot.com/​ to generate the lines to be put into the build.gradle
 +
  
 ==== Run dependencies when calling Java from Prolog ==== ==== Run dependencies when calling Java from Prolog ====
  
-In the '​normal'​ case, the classpath for a rosjava node only needs to contain ​the dependencies of the package the node is located in. With json_prolog,​ we however have a special case: It serves as launcher for other packages (e.g. knowrob_vis) that may also contain Java code. We therefore ​need to add the Java dependencies of json_prolog itself AND the dependencies of the packages to be launched ​to the classpath.+In the '​normal'​ case, the classpath for a rosjava node only contains ​the dependencies of that program itself. With json_prolog,​ we however have a special case: It serves as launcher for other packages (e.g. knowrob_vis) that may also contain Java code. The classpath ​therefore ​needs to contain ​the Java dependencies of json_prolog itself AND the dependencies of the packages to be launched.
  
-This is not easy with the existing tools (since the exporting ​packages are not by themselves ​catkin packages)so we had to find another solution: During compilation,​ gradle creates a file '​classpath.txt'​ with the dependencies ​of the respective package. At runtime, rosprolog and json_prolog collect these files and assemble the overall classpath from them. You need to add the following statement to the build.gradle of the respective (exporting) subproject:+This is not easy with the existing tools: From json_prolog,​ we launch //​catkin ​packages//, but the dependencies we need are specified ​by the //rosjava subprojects//​ inside those catkin packages. Since catkin is not aware of these subprojectsit cannot be used to collect the classpath elements from all dependencies. The current workaround is the following: During compilation,​ gradle creates a file '​classpath.txt'​ with the classpath elements ​of the respective package. At runtime, rosprolog and json_prolog collect these files and assemble the overall classpath from them. You need to add the following statement to the build.gradle of the respective (exporting) subproject:
 <code java> <code java>
     task writeClasspath << {     task writeClasspath << {
Line 71: Line 70:
 ... and add the writeClasspath task to the CMakeLists.txt:​ ... and add the writeClasspath task to the CMakeLists.txt:​
     catkin_rosjava_setup(installApp publishMavenJavaPublicationToMavenRepository writeClasspath)     catkin_rosjava_setup(installApp publishMavenJavaPublicationToMavenRepository writeClasspath)
 +
 +
  
 ===== Adapting OWL and Prolog files to the new libraries ===== ===== Adapting OWL and Prolog files to the new libraries =====
Line 81: Line 82:
  
  
-  * Update launch files to the new json_prolog interface:+  * Update launch files to the new json_prolog interface. The //​initial_package//​ parameter specifies the package to be loaded when the node is launched (similar to the package you give as argument to '​rosprolog'​). The //​initial_goal//​ is called immediately after KnowRob has been started and can for instance be used to load data from an OWL file.
     <code xml>     <code xml>
     <​launch>​     <​launch>​
Line 94: Line 95:
      $ rosrun rosprolog migrate_owl_iri      $ rosrun rosprolog migrate_owl_iri
      </​code>​      </​code>​
 +
 +
 ===== Changelog ===== ===== Changelog =====