1GENMSG(1) genmsg GENMSG(1)
2
6 genmsg - genmsg Documentation
7 Project genmsg exists in order to decouple code generation from .msg &
9 .srv format files from the parsing of these files and from impementa‐
10 tion details of the build system (project directory layout, existence
11 or nonexistence of utilities like rospack, values of environment vari‐
12 ables such as ROS_PACKAGE_PATH): i.e. none of these are required to be
13 set in any particular way.
14
16 add_message_files(DIRECTORY dir FILES file1 [file2...] [PACKAGE pkg‐
17 name] [NOINSTALL])
18 Parameters
20 · DIRECTORY – Directory containing messages. May be
22 absolute or relative to CMAKE_CURRENT_SOURCE_DIR.
23 · FILES – Files containing messages, relative to msgdir
25 · PACKAGE – Optional alternate packagename (if the cur‐
27 rent project doesn’t match the desired namespace for
28 the messages)
29 · NOINSTALL – Do not automatically install the messages
31 to the package’s share/ directory.
32 Register the listed files as requiring message generation and
34 installation.
35 add_service_files(DIRECTORY dir FILES file1 [file2...] [PACKAGE pkg‐
37 name] [NOINSTALL])
38 Same as add_message_files… but for services.
39 generate_messages(DEPENDENCIES deps [LANGS lang1 lang2...])
41 Parameters
43 · DEPENDENCIES – Names of packages containing messages
45 contained by messages in the current package. Got it?
46 i.e. if one of our messages contains std_msgs.Header,
47 std_msgs should appear in this list.
48 · LANGS – Restrict generation to the listed languages.
50 Triggers the generation of message generation targets. i.e. in
52 project foo with generators gencpp and genpy accessible in the
53 workspace, triggers creation of targets foo_gencpp and
54 foo_genpy.
55
57 Classes
58 class genmsg.MsgSpec(types, names, constants, text, full_name, pack‐
59 age='', short_name='')
60 Container class for storing loaded msg description files. Field
61 types and names are stored in separate lists with 1-to-1 corre‐
62 spondence. MsgSpec can also return an md5 of the source text.
63 fields()
65 Returns
67 zip list of types and names (e.g. [(‘int32’, ‘x’),
68 (‘int32’, ‘y’)], [(str,str),]
69 has_header()
71 Returns
73 True if msg decription contains a ‘Header header’
74 declaration at the beginning, bool
75 parsed_fields()
77 Returns
79 list of Field classes, [Field,]
80 class genmsg.SrvSpec(request, response, text, full_name='',
82 short_name='', package='')
83 class genmsg.Constant(type_, name, val, val_text)
85 Container class for holding a Constant declaration
86 Attributes:
88 · type
90 · name
92 · val
94 · val_text
96 class genmsg.Field(name, type)
98 Container class for storing information about a single field in
99 a MsgSpec
100 Attributes:
102 · name
104 · type
106 · base_type
108 · is_array
110 · array_len
112 · is_builtin
114 · is_header
116
118 Project genmsg exists in order to decouple code generation from impe‐
119 mentation details of the build system (project directory layout, exis‐
120 tence or nonexistence of utilities like rospack, values of environment
121 variables such as ROS_PACKAGE_PATH): i.e. none of these are required to
122 be set in any particular way.
123 Code generators expose a compiler-like interface that make all inputs,
125 outputs and search paths explicit. For instance, the invocation of
126 gencpp for ros message nav_msgs/Odometry.msg looks like this:
127 /ssd/catkin/test/src/gencpp/scripts/gen_cpp.py
129 /ssd/catkin/test/src/common_msgs/nav_msgs/msg/Odometry.msg
130 -Inav_msgs:/ssd/catkin/test/src/common_msgs/nav_msgs/msg
131 -Igeometry_msgs:/ssd/catkin/test/src/common_msgs/geometry_msgs/msg
132 -Istd_msgs:/ssd/catkin/test/src/std_msgs/msg
133 -p nav_msgs
134 -o /ssd/catkin/test/build/gen/cpp/nav_msgs
135 -e /ssd/catkin/test/src/gencpp/scripts
136 where the code generator (the first argument), is a python script
138 gen_cpp.py. The commandline arguments have the following meanings:
139 /path/to/Some.msg
141 The flagless argument is the path to the input .msg file.
142 -I NAMESPACE:/some/path
144 find messages in NAMESPACE in directory /some/path
145 -p THIS_NAMESPACE
147 put generated message into namespace THIS_NAMESPACE
148 -o /output/dir
150 Generate code into directory /output/dir
151 -e /path/to/templates
153 Find empy templates in this directory
154 Code generators may not use any information other than what is provided
156 on the commandline. Writing the generator
157 Code generators depend on genmsg to parse the .msg file itself. They
159 then use the parse tree to generate code in whatever language or format
160 they prefer.
161 A separate project must exists for each language you wish to generate
163 for. Such a project contains:
164 · A message_generator tag in the stack.xml file
166 · Executable scripts for generating the code based on .msg/.srv files
168 · Definitions of certain CMake macros to make the generator accessible
170 by the build system.
171 Generator Scripts
173 The recommended way of implementing the generator is by using empy tem‐
174 plate files. See: http://www.alcyone.com/software/empy A empy template
175 is a text file part of which can contain python code that is evaluated
176 during code generation. genmsg includes python methods for parsing the
177 command line arguments and performing the code generation very easily
178 if the template model is used.
179 The script for generating cpp files looks as:
181 import sys
183 import genmsg.template_tools
184 msg_template_map = { 'msg.h.template':'@NAME@.h' }
186 srv_template_map = { 'srv.h.template':'@NAME@.h' }
187 if __name__ == "__main__":
189 genmsg.template_tools.generate_from_command_line_options(sys.argv, msg_template_map, srv_template_map)
190 msg_template_map and srv_template_map defines the template files used
192 for generating from .msg and .srv files respectively. The format is
193 <type>_template_map = { '<template_filename>':'<output_file_name>' }.
194 The entry @NAME@ will be replaced by the short name of the message such
195 as String for String.msg etc. The call to generate_from_com‐
196 mand_line_options will use the correct map depending on the file gives
197 as command line argument. When a service is generated, two messages
198 are also generated, namely the <SrvName>Request and <SrvName>Response.
199 genmsg will parse the respective .msg and .srv file and expose the
201 information in three python variables awailable in the empy template.
202 These are:
203 · file_name_in (String) Filename of the source .msg /.srv file
205 · spec (msggen.MsgSpec) Parsed specification of the .msg/.srv file
207 · md5sum (String) MD5Sum of the msg/srv
209 See https://github.com/ros/gencpp/blob/master/scripts/msg.h.template
211 and https://github.com/ros/gencpp/blob/master/scripts/srv.h.template
212 for example template files.
213 If the language requires a common file to exists for all the generated
215 source code files (Such as __init__.py for python) it is possible to
216 specify a module_tempalte_map. See
217 https://github.com/ros/genpybindings/blob/master/scripts/module.cpp.template
218 for example of this.
219 stack.xml
221 Each language is identified by a name which must be specified in the
222 stack.xml file. The example entry for the generator for C++ is:
223 Catkin-ROS-Message-Generator: cpp
225 The project name for the generator with identifier X should be genX.
227 Providing cmake code to catkin
229 Generator packages define several macros (below), and use catkin mecha‐
230 nisms to make the definitions of these macros available, see
231 catkin_project. catkin will generate calls to them for
232 · each message
234 · each service
236 · once for the overall package
238 For a generator called X, in a package called genX:
240 _generate_msg_X(PACKAGE MESSAGE IFLAGS MSG_DEPS OUTDIR)
242 Parameters
244 · PACKAGE – name of package that the generated message
246 MESSAGE is found in.
247 · MESSAGE – full path to .msg file
249 · IFLAGS – a list of flags in -I<package>:/path format
251 · MSG_DEPS – a list of .msg files on which this message
253 depends
254 · OUTDIR – destination directory for generated files
256 There are two other macros, _generate_srv_X,
258 _generate_srv_X(PACKAGE SERVICE IFLAGS MSG_DEPS OUTDIR)
260 Parameters
262 · PACKAGE – name of package that the generated message
264 MESSAGE is found in.
265 · SERVICE – full path to .srv file
267 · IFLAGS – a list of flags in -I<package>:/path format
269 · MSG_DEPS – a list of .msg files on which this message
271 depends
272 · OUTDIR – destination directory for generated files
274 and
276 _generate_module_X(PACKAGE OUTDIR GENERATED_FILES)
278 Parameters
280 · PACKAGE – name of package
282 · OUTDIR – destination directory
284 · GENERATED_FILES – Files that were generated (from mes‐
286 sages and services) for this package. Usually used to
287 pass to the DEPENDS option of cmake’s add_custom_com‐
288 mand()
289 Generate any “module” code necessary, e.g. __init__.py for
291 python or module.cpp for boost.python bindings.
292 Examples
294 Example projects that use this infrastructure are gencpp, genpy, and
295 genpybindings, all found in the github repositories at
296 http://github.com/ros.
297 Code generators may not use any information other than what is provided
299 on the commandline.
300
302 Willow Garage
303
305 2011, Willow Garage
3060.3.10 Feb 09, 2018 GENMSG(1)