1FFIFACEGEN(1) Fawkes Manual FFIFACEGEN(1)
2
6 ffifacegen - Fawkes interface code generator
7
9 ffifacegen [-h] [-d dir] [-v] config.xml [config2.xml...]
10
12 The interface generator takes an XML interface definition file as input
13 and generates C and Lua/C code. If this code is compiled into a shared
14 library it can be used to access a blackboard interface from C++ or Lua
15 applications.
16 Definition File Format
18 The interface is defined by an interface document specifying one
19 <interface> element. It comprises (optional) constants, (mandatory)
20 data fields, and (optional) messages.
21 Example:
23 <?xml version="1.0" encoding="UTF-8"?>
25 <!DOCTYPE interface SYSTEM "interface.dtd">
26 <interface name="NameThisInterface" author="Author Name" year="2010">
27 <constants>
28 <!-- constant definitions -->
29 </constants>
30 <data>
31 <comment>Commentary on interface.</comment>
32 <!-- field definitions -->
33 </data>
34 <message name="MessageTypeName">
35 <comment>Set the test int to the given value.</comment>
36 <!-- reference and field definitions -->
37 </message>
38 <!-- Any number of additional message types -->
39 </interface>
40 Constants
42 The constants are optional. It comprises constant values of arbitrary
43 types or enumerations. Example:
44 <constant type="int32" value="5" name="CONSTANT_NAME">Comment</constant>
46 Constants are exported as static class members of the interface. The
48 value of the field is a comment used for documentation purposes.
49 Example:
51 <enum name="TestEnum">
53 <comment>Demonstrating enums</comment>
54 <item name="TEST_ENUM_1">Item 1</item>
55 <item name="TEST_ENUM_2">Item 2</item>
56 </enum>
57 Enumerations are symbolic names of type integer. The field text are
59 comments about the overall enumeration and the enumeration items.
60 Fields
62 Data is stored in fields in the interfaces. Data can be one of the
63 following types: * string * byte (equivalent to uint8) * char
64 (equivalent to char) * int8 * uint8 * int16 * uint16 * int32 * uint32 *
65 int64 * uint64 (not recommended, see below) * bool * float * double *
66 custom enum types (as specified in the constants) Note that uint64 (and
67 to some degree int64) can cause problems. Lua for example supports
68 integers only up to 52 bits. Java does not support unsigned types,
69 therefore it is limited to int64 (although not supported as of now, it
70 may be in the future). If you think that you need 64 bit integers and
71 need the full range, be aware of these problems and state this clearly
72 in the documentation of the module in question.
73 Number and boolean types can be used to form statically sized arrays.
75 For this add an attribute length with the number of elements in the
76 array. The same attribute must be given for strings to denote the
77 maximum length (including null termination).
78 Example:
80 <field type="bool" name="test_bool">Test Bool</field>
82 <field type="int32" name="test_int">Test integer</field>
83 <field type="string" length="30" name="test_string">A test string</field>
84 <field type="int32" length="30" name="test_array">Integer array</field>
85 Messages
87 Messages are defined as sub-documents. Any number of messages can be
88 defined for an interface. Example:
89 <message name="SetTestInt">
91 <comment>Set the test int to the given value.</comment>
92 <ref>test_int</ref>
93 </message>
94 <message name="Calculate">
95 <comment>Adds Summand and Addend.</comment>
96 <field type="int32" name="summand">Summand</field>
97 <field type="int32" name="addend">Addend</field>
98 </message>
99 The <ref> field can be used to reference fields of the interface. An
101 appropriate field with the given name and the same type as in the
102 interface is then added. Fields can otherwise be specified in the same
103 way they are for the interface. References and fields can be mixed in a
104 message.
105
107 -h
108 Show help instructions.
109 -d dir
111 Directory in which the resulting output files are generated. The
112 default is the current working directory.
113 -v
115 Verbose output to console.
116 config.xml...
118 Any number of XML interface definition files as described above.
119 The appropriate files are generated for each of the given input
120 files.
121
123 ffifacegen MyInterface.xml
124 Create the source files as defined in MyInterface.xml in the
125 current working directory.
126 Also see TestInterface.xml in the source distribution for an example of
128 a full interface.
129
131 fawkes(8)
132
134 Written by Tim Niemueller <niemueller@kbsg.rwth-aachen.de>
135
137 Documentation by Tim Niemueller <niemueller@kbsg.rwth-aachen.de>
138
140 Part of the Fawkes Robot Software Framework. Project website is at
141 http://www.fawkesrobotics.org
142Fawkes 1.3.0 04/12/2022 FFIFACEGEN(1)