genmsg man page

genmsg — genmsg Documentation

Project genmsg exists in order to decouple code generation from .msg & .srv format files from the parsing of these files and from impementation details of the build system (project directory layout, existence or nonexistence of utilities like rospack, values of environment variables such as ROS_PACKAGE_PATH): i.e. none of these are required to be set in any particular way.

User Macro Reference

add_message_files(DIRECTORY dir FILES file1 [file2...] [PACKAGE pkgname] [NOINSTALL])
Parameters
·
DIRECTORY -- Directory containing messages. May be absolute or relative to CMAKE_CURRENT_SOURCE_DIR.
·
FILES -- Files containing messages, relative to msgdir
·
PACKAGE -- Optional alternate packagename (if the current project doesn't match the desired namespace for the messages)
·
NOINSTALL -- Do not automatically install the messages to the package's share/ directory.

Register the listed files as requiring message generation and installation.

add_service_files(DIRECTORY dir FILES file1 [file2...] [PACKAGE pkgname] [NOINSTALL])
Same as add_message_files... but for services.
generate_messages(DEPENDENCIES deps [LANGS lang1 lang2...])
Parameters
·
DEPENDENCIES -- Names of packages containing messages contained by messages in the current package. Got it? i.e. if one of our messages contains std_msgs.Header, std_msgs should appear in this list.
·
LANGS -- Restrict generation to the listed languages.

Triggers the generation of message generation targets. i.e. in project foo with generators gencpp and genpy accessible in the workspace, triggers creation of targets foo_gencpp and foo_genpy.

Genmsg Python API

Classes

class genmsg.MsgSpec(types, names, constants, text, full_name, package='', short_name='')

Container class for storing loaded msg description files. Field types and names are stored in separate lists with 1-to-1 correspondence. MsgSpec can also return an md5 of the source text.

fields()
Returns
zip list of types and names (e.g. [('int32', 'x'), ('int32', 'y')], [(str,str),]
has_header()
Returns
True if msg decription contains a 'Header header' declaration at the beginning, bool
parsed_fields()
Returns
list of Field classes, [Field,]

class genmsg.SrvSpec(request, response, text, full_name='', short_name='', package='')

class genmsg.Constant(type_, name, val, val_text)

Container class for holding a Constant declaration

Attributes:

·
type
·
name
·
val
·
val_text
class genmsg.Field(name, type)

Container class for storing information about a single field in a MsgSpec

Attributes:

·
name
·
type
·
base_type
·
is_array
·
array_len
·
is_builtin
·
is_header

Developer Documenation

Project genmsg exists in order to decouple code generation from impementation details of the build system (project directory layout, existence or nonexistence of utilities like rospack, values of environment variables such as ROS_PACKAGE_PATH): i.e. none of these are required to be set in any particular way.

Code generators expose a compiler-like interface that make all inputs, outputs and search paths explicit. For instance, the invocation of gencpp for ros message nav_msgs/Odometry.msg looks like this:

/ssd/catkin/test/src/gencpp/scripts/gen_cpp.py
/ssd/catkin/test/src/common_msgs/nav_msgs/msg/Odometry.msg
-Inav_msgs:/ssd/catkin/test/src/common_msgs/nav_msgs/msg
-Igeometry_msgs:/ssd/catkin/test/src/common_msgs/geometry_msgs/msg
-Istd_msgs:/ssd/catkin/test/src/std_msgs/msg
-p nav_msgs
-o /ssd/catkin/test/build/gen/cpp/nav_msgs
-e /ssd/catkin/test/src/gencpp/scripts

where the code generator (the first argument), is a python script gen_cpp.py. The commandline arguments have the following meanings:

/path/to/Some.msg
The flagless argument is the path to the input .msg file.
-I NAMESPACE:/some/path
find messages in NAMESPACE in directory /some/path
-p THIS_NAMESPACE
put generated message into namespace THIS_NAMESPACE
-o /output/dir
Generate code into directory /output/dir
-e /path/to/templates
Find empy templates in this directory

Code generators may not use any information other than what is provided on the commandline. Writing the generator

Code generators depend on genmsg to parse the .msg file itself. They then use the parse tree to generate code in whatever language or format they prefer.

A separate project must exists for each language you wish to generate for. Such a project contains:

·
A message_generator tag in the stack.xml file
·
Executable scripts for generating the code based on .msg/.srv files
·
Definitions of certain CMake macros to make the generator accessible by the build system.

Generator Scripts

The recommended way of implementing the generator is by using empy template files. See: http://www.alcyone.com/software/empy A empy template is a text file part of which can contain python code that is evaluated during code generation. genmsg includes python methods for parsing the command line arguments and performing the code generation very easily if the template model is used.

The script for generating cpp files looks as:

import sys
import genmsg.template_tools

msg_template_map = { 'msg.h.template':'@NAME@.h' }
srv_template_map = { 'srv.h.template':'@NAME@.h' }

if __name__ == "__main__":
  genmsg.template_tools.generate_from_command_line_options(sys.argv, msg_template_map, srv_template_map)

msg_template_map and srv_template_map defines the template files used for generating from .msg and .srv files respectively. The format is <type>_template_map = { '<template_filename>':'<output_file_name>' }. The entry @NAME@ will be replaced by the short name of the message such as String for String.msg etc. The call to generate_from_command_line_options will use the correct map depending on the file gives as command line argument. When a service is generated, two messages are also generated, namely the <SrvName>Request and <SrvName>Response.

genmsg will parse the respective .msg and .srv file and expose the information in three python variables awailable in the empy template. These are:

·
file_name_in (String) Filename of the source .msg /.srv file
·
spec (msggen.MsgSpec) Parsed specification of the .msg/.srv file
·
md5sum (String) MD5Sum of the msg/srv

See https://github.com/ros/gencpp/blob/mast… and https://github.com/ros/gencpp/blob/mast… for example template files.

If the language requires a common file to exists for all the generated source code files (Such as __init__.py for python) it is possible to specify a module_tempalte_map. See https://github.com/ros/genpybindings/bl… for example of this.

stack.xml

Each language is identified by a name which must be specified in the stack.xml file. The example entry for the generator for C++ is:

Catkin-ROS-Message-Generator: cpp

The project name for the generator with identifier X should be genX.

Providing cmake code to catkin

Generator packages define several macros (below), and use catkin mechanisms to make the definitions of these macros available, see catkin_project. catkin will generate calls to them for

·
each message
·
each service
·
once for the overall package

For a generator called X, in a package called genX:

_generate_msg_X(PACKAGE MESSAGE IFLAGS MSG_DEPS OUTDIR)
Parameters
·
PACKAGE -- name of package that the generated message MESSAGE is found in.
·
MESSAGE -- full path to .msg file
·
IFLAGS -- a list of flags in -I<package>:/path format
·
MSG_DEPS -- a list of .msg files on which this message depends
·
OUTDIR -- destination directory for generated files

There are two other macros, _generate_srv_X,

_generate_srv_X(PACKAGE SERVICE IFLAGS MSG_DEPS OUTDIR)
Parameters
·
PACKAGE -- name of package that the generated message MESSAGE is found in.
·
SERVICE -- full path to .srv file
·
IFLAGS -- a list of flags in -I<package>:/path format
·
MSG_DEPS -- a list of .msg files on which this message depends
·
OUTDIR -- destination directory for generated files

and

_generate_module_X(PACKAGE OUTDIR GENERATED_FILES)
Parameters
·
PACKAGE -- name of package
·
OUTDIR -- destination directory
·
GENERATED_FILES -- Files that were generated (from messages and services) for this package. Usually used to pass to the DEPENDS option of cmake's add_custom_command()

Generate any "module" code necessary, e.g. __init__.py for python or module.cpp for boost.python bindings.

Examples

Example projects that use this infrastructure are gencpp, genpy, and genpybindings, all found in the github repositories at http://github.com/ros.

Code generators may not use any information other than what is provided on the commandline.

Author

Willow Garage

Info

Jul 19, 2016 0.3.10 genmsg