Differences

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

Link to this comparison view

Next revision		Previous revision
Last revisionBoth sides next revision
doc:catkin_migration [2014/07/10 12:24] – created admindoc:catkin_migration [2014/09/10 15:52] – [Changelog] admin
Line 5: Line 5:
 ===== 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 
 +  * 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, also update changed package names. Remove all rosbuild and old rosjava statements, e.g. 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. 
 +
 +==== 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 =====
 +
 +  * Replace all references to 'ias_knowledge_base' with knowrob_common. Please also check for other [[https://github.com/knowrob/knowrob/issues/18|package names that may have changed]].
 +  * Rename all *.owl.in and *.pl.in files into *.owl and *.pl. Replace the @LOCAL_PACKAGE_PATH@ (or similar) directives with URLs of the form package://<ros_pkg_name>/local/path/to/file.owl, e.g. package://knowrob_common/owl/knowrob.owl. This new syntax works for loading OWL files both from OWL and Prolog files.
 +  * Remove the 'false, false, true' arguments from all owl_parse() statements. The new syntax is simply
 +
 +    owl_parse('package://<ros_pkg_name>/local/path/to/file.owl').
  
  
 +  * 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+