Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
doc:catkin_migration [2014/07/10 12:34]
admin
doc:catkin_migration [2014/12/07 07:53]
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. ​ ​Please check for [[https://github.com/knowrob/knowrob/issues/18|package ​names that may have changed]]. +  * Update the CMakeLists.txt ​and update all changed package names also thereRemove all rosbuild and old rosjava statements, e.g. those for generating .owl from .owl.in files. 
-    ​* Remove all rosbuild ​and old rosjava ​statements, e.g. for generating ​.owl from .owl.in files.+ 
 +===== Converting Java packages ===== 
 + 
 +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 ==== 
 + 
 +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: 
 + 
 +    ​json_prolog_msgs ​       <-- catkin package 
 +      |- srv 
 +      |- package.xml 
 +      \- ... 
 +       
 +    json_prolog ​            <​-- catkin package 
 +      |- gradle ​            <​-- gradle wrapper needed for compiling the rosjava code 
 +      |- json_prolog ​       <-- rosjava subproject 
 +      |     |- src         
 +      |     \- build.gradle 
 +      | 
 +      |- json_prolog_msgs ​  <​-- rosjava subproject for the custom service definitions 
 +      |     \- build.gradle 
 +      | 
 +      |- build.gradle 
 +      |- gradlew 
 +      |- package.xml 
 +      \- ... 
 + 
 + 
 +==== JAR files and build dependencies ==== 
 +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> 
 +    dependencies { 
 +      /* Dependency on a rosjava ​project in the same catkin package */  
 +      compile project(':​json_prolog_msgs'​) 
 +       
 +      /* Dependency on a rosjava project in another catkin package */ 
 +      compile '​org.ros.rosjava_core:​rosjava:​[0.1,)' 
 +   
 +      /* Dependency on external jar files (will be downloaded from mavencentral */ 
 +      compile '​net.sf.json-lib:​json-lib:​2.4:​jdk15'​ 
 +    } 
 +</​code>​ 
 +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 ==== 
 + 
 +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 codeThe 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: 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 subprojects,​ it cannot be used to collect the classpath elements ​from all dependenciesThe 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 themYou need to add the following statement to the build.gradle of the respective (exporting) subproject:​ 
 +<code java> 
 +    task writeClasspath << { 
 +        buildDir.mkdirs() 
 +        new File(buildDir,​ "​classpath.txt"​).text = configurations.runtime.asPath + 
 +                                                  ":"​ + buildDir + "/​libs/"​ + 
 +                                                  project.name + "​-"​ + 
 +                                                  project.version + "​.jar"​ + "​\n"​ 
 +    } 
 +</​code>​ 
 +... and add the writeClasspath task to the CMakeLists.txt:​ 
 +    catkin_rosjava_setup(installApp publishMavenJavaPublicationToMavenRepository writeClasspath) 
  
  
Line 20: Line 82:
  
  
-===== Converting Java packages ​===== +  * 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> 
 +    <​launch>​ 
 +       <​param name="​initial_package"​ type="​string"​ value="<​pkg_name>"​ /> 
 +       <​param name="​initial_goal"​ type="​string"​ value="​owl_parse('​package://<​pkg_name>/​owl/​file.owl'​)"​ /> 
 +        
 +       <​node name="​json_prolog"​ pkg="​json_prolog"​ type="​json_prolog_node"​ cwd="​node"​ output="​screen"​ /> 
 +    </​launch>​ 
 +    </​code>​ 
 +  * Replace all *.cs.tum.edu-IRIs with knowrob.org. You can use the following command to replace them in most common files in all subfolders of the current directory:​ 
 +     <​code bash> 
 +     $ rosrun rosprolog migrate_owl_iri 
 +     </​code>​
  
  
Line 27: Line 100:
  
 The changes have been ticketed at the knowrob repository for Milestone 1. Please have a look here for a list of changes: The changes have been ticketed at the knowrob repository for Milestone 1. Please have a look here for a list of changes:
-https://​github.com/​knowrob/​knowrob/​issues?​milestone=1+https://​github.com/​knowrob/​knowrob/​issues?​q=is%3Aissue+milestone%3A1.0+