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
Last revision Both sides next revision
doc:catkin_migration [2014/07/10 12:34]
admin
doc:catkin_migration [2014/09/10 15:52]
admin [Changelog]
Line 7: Line 7:
 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 generate something like 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 [[https://​github.com/​knowrob/​knowrob/​issues/​18|package names 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, also update changed ​package names. Remove all rosbuild and old rosjava statements, e.g. 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 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. ​
 +
 +==== 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 '​magically'​ maintains jar files for dependendies. 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 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.
 +
 +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:
 +<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)
  
 ===== Adapting OWL and Prolog files to the new libraries ===== ===== Adapting OWL and Prolog files to the new libraries =====
Line 20: Line 81:
  
  
-===== Converting Java packages ​===== +  * Update launch files to the new json_prolog interface:​ 
- +    <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>​
 ===== Changelog ===== ===== Changelog =====
  
 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+