1FFIFACEGEN(1)                    Fawkes Manual                   FFIFACEGEN(1)
2
3
4

NAME

6       ffifacegen - Fawkes interface code generator
7

SYNOPSIS

9       ffifacegen [-h] [-d dir] [-v] config.xml [config2.xml...]
10

DESCRIPTION

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
17   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
22       Example:
23
24           <?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
41   Constants
42       The constants are optional. It comprises constant values of arbitrary
43       types or enumerations. Example:
44
45           <constant type="int32" value="5" name="CONSTANT_NAME">Comment</constant>
46
47       Constants are exported as static class members of the interface. The
48       value of the field is a comment used for documentation purposes.
49
50       Example:
51
52           <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
58       Enumerations are symbolic names of type integer. The field text are
59       comments about the overall enumeration and the enumeration items.
60
61   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
74       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
79       Example:
80
81           <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
86   Messages
87       Messages are defined as sub-documents. Any number of messages can be
88       defined for an interface. Example:
89
90           <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
100       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

OPTIONS

107       -h
108           Show help instructions.
109
110       -d dir
111           Directory in which the resulting output files are generated. The
112           default is the current working directory.
113
114       -v
115           Verbose output to console.
116
117       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

EXAMPLES

123       ffifacegen MyInterface.xml
124           Create the source files as defined in MyInterface.xml in the
125           current working directory.
126
127       Also see TestInterface.xml in the source distribution for an example of
128       a full interface.
129

SEE ALSO

131       fawkes(8)
132

AUTHOR

134       Written by Tim Niemueller <niemueller@kbsg.rwth-aachen.de>
135

DOCUMENTATION

137       Documentation by Tim Niemueller <niemueller@kbsg.rwth-aachen.de>
138

FAWKES

140       Part of the Fawkes Robot Software Framework. Project website is at
141       http://www.fawkesrobotics.org
142
143
144
145Fawkes 1.3.0                      06/21/2022                     FFIFACEGEN(1)
Impressum