## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links
## note.0=[[rosjava/Tutorials/hydro/Installation|Installation]]
## note.1=[[rosjava_build_tools/Tutorials/hydro/Creating Rosjava Packages|Creating Rosjava Packages]]
## descriptive title for the tutorial
## title = Unofficial Messages
## multi-line description to be displayed in search
## description = Generating java artifacts for your own, unreleased message packages.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=[[rosjava/Tutorials/hydro/To Build with Catkin or Gradle|To Build with Catkin or Gradle]]
## next.1.link=
## what level user is this tutorial for
## level= BeginnerCategory
## keywords = rosjava
####################################
<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

= Unofficial Messages =

You can also generate code for your own non-released packages by creating a subproject in one of your gradle repositories. 

This will also work for manually testing and building artifacts of released packages - just make sure the version number of your modified msg package is greater than the last officially released version.

== Example ==

A good example of a mixed set of non-released and version bumped testing release packages can be found in [[https://github.com/robotics-in-concert/rocon_rosjava_msgs|rocon_rosjava_msgs]].

== Artifact Generator ==

This method generates a single artifact for a single unreleased message package. It can get tedious if you want to generate code for alot of message packages, but it is by far the easiest method.

 * Create a regular `foo_msgs` package with your custom msgs and srvs.
 * Create a gradle-catkin package 'myjava_messages'
 * Create a gradle subproject in here called `foo_msgs`
 * Add `foo_msgs` as a build_depends to `myjava_messages/package.xml`
 * Add `foo_msgs` to `myjava_messages/settings.gradle`
 * Add build rules and logic to your `myjava_messages/build.gradle` and `myjava_messages/foo_msgs/build.gradle`.

=== Catkin Create ===

You can simplify the process some with the wizards from [[rosjava_build_tools]],  There are two constraints that is important in order to make this process as automatic and simple as possible:

||<#FFFF00> Your message package name will be in the same group as the official message artifacts in 'org.ros.rosjava_messages'. ||

||<#FFFF00> It will use open ranged versions for any message package dependencies (e.g. [0.1,)). ||

Example:

{{{
> cd src
> catkin_create_pkg foo_msgs std_msgs
> cd foo_msgs
# Add your messages to foo_msgs
# Don't forget to add message_generation/runtime depends
# in CMakeLists.txt and package.xml
> cd ../
# Good idea to include message package build_depends to your package
# - rosjava_bootstrap : for the message_generation tools
# - rosjava_messages  : for any official message artifacts you depend on
# - foo_msgs          : the unofficial package dependency you will need
> catkin_create_rosjava_pkg myjava_messages rosjava_bootstrap rosjava_messages foo_msgs
> cd myjava_messages
> catkin_create_rosjava_msg_project foo_msgs
> cd ../..
> catkin_make
}}}

=== Manually ===

You can of course set up foo_msg's `build.gradle` file manually and remove the constraints above. You'll just need to pay attention to get the dependencies and versions correct.

=== Under the Hood ===

Example generated code for the above is in [[attachment:foo.tar.gz]]. The meaningful snippets that are added to your package/project are outlined below. Should be self-explanatory.

'''myjava_messages/package.xml'''

{{{
?xml version="1.0"?>
<package>
  <name>myjava_messages</name>
  ...
  <!-- The message generator tools -->
  <build_depend>rosjava_bootstrap</build_depend>
  <!-- If foo_msgs depends on other official message artifacts -->
  <build_depend>rosjava_messages</build_depend>
  <build_depend>foo_msgs</build_depend>
  <!-- If foo_msgs depends on other unofficial messages, add them here -->
</package>
}}}
'''myjava_messages/settings.gradle'''

{{{
include 'foo_msgs'
}}}
'''myjava_messages/build.gradle'''

{{{
...

apply plugin: 'catkin'
project.catkin.tree.generate()

...
}}}
'''myjava_messages/foo_msgs/build.gradle'''

{{{
try {
    project.catkin.tree.generateMessageArtifact(project, 'foo_msgs')
} catch (NullPointerException e) {
    println("Couldn't find foo_msgs on the ROS_PACKAGE_PATH")
}
}}}

The generated artifact would appear in `myjava_messages/devel/share/maven/com/github/rosjava/myjava_messages/foo_msgs` when built.

== Alternative Methods ==

You can also spawn multiple packages at once with some gradle-groovy logic - look to the scripts in [[https://github.com/rosjava/rosjava_messages|rosjava_messages]] for hints on how to do that.

Another alternative is to bundle multiple message packages into the one rosjava artifact (or even all message packages on ROS_PACKAGE_PATH), but that requires looking into the functionality provided by the ros gradle plugins and the message_generation library in [[rosjava_bootstrap]].

Both of these methods go beyond this tutorial - if you would like more information, ask on the  [[https://groups.google.com/group/ros-sig-java|sig mailing list]].

## AUTOGENERATED DO NOT DELETE
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE