| GirToBac 0.0 Create FB Headers from GObject Introspection *.gir files

- Main Page
- Tutorial
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Enumerations Macros Pages
GirToBac_Tutorial.bi
Go to the documentation of this file.
1 /'* \file GirToBac_Tutorial.bi
2 \brief Context of the manual
3
4 This file doesn't contain any source code. Instead it contains the
5 context of this manual in comment blocks. For convenience reasons
6 it's named as a source file to get auto-scanned by Doxygen.
7
8 '/
9
10 /'* \page tutorial Tutorial
11 \tableofcontents
12
13 This project is about a new header generator for the <A
14 HREF="http://www.freebasic.net">FreeBasic (FB)</A> programming
15 language. It creates FB headers by scanning <em>*.gir</em> files.
16
17 <em>*.gir</em> files are generated by the GObject-Introspection
18 (GI) technology. GNOME libraries based on GLib/GObject use these
19 technology to support polyglot application development. This means a
20 library developed in C will be used in higher level programming
21 languages like JavaScript, Python, Vala or others. The GI system
22 helps to auto-generate bindings for these high-level programming
23 languages.
24
25 GirToBac is the first attempt to connect FreeBasic (FB) to these
26 supports. It reads the GI <em>*.gir</em> files (generated during
27 compilation of the C library) and transforms their context to FB
28 headers. Some manual control is needed to adapt the output. This is
29 done by a configuration file (one for each <em>*.gir</em> file).
30 These configuration files can be re-used for up-dated <em>*.gir</em>
31 files further on.
32
33
34 \section principle How does this work?
35
36 GirToBac is a command line tool, being shipped as FB source code.
37 The code needs to get compiled first. The executable expects one
38 parameter, the name of the <em>*.gir</em> file (maybe prepended by
39 its path). It loads this file and additionally a configuration file
40 with the same base-name and the suffix \em .GirToBac (if present in
41 the current folder). Then the context of the <em>*.gir</em> file gets
42 translated to FB source by respecting the rules in the configuration
43 file. The result gets written to the current folder as an FB header
44 file named after the basename and with suffix \em .bi (overwriting
45 existent files). In best case the header contains all information to
46 use the library in FB source code.
47
48 The headers are designed to be stored in one directory, one header
49 for each library (= dll binary). Each header loads the dependencies
50 its library is based on, so the user need not care about
51 chaining-up. Just load the highest level header and your source
52 contains all dependencies (the binaries must have been installed
53 befor).
54
55 To generate an FB header the <em>*.gir</em> files gets scanned
56 several times:
57
58 -# First, some constants get \#DEFINEd and TYPE aliases and
59 ENUM blocks gets translated.
60 -# In the second pass UNIONs, TYPEs and callback prototypes are
61 done. Some of them are based on others and fbc need to read them
62 in the logical order (use the control file to re-order).
63 -# The last step is to translate static SUBs/FUNCTIONs
64 declarations.
65
66
67 \section differences What's new, what's different?
68
69 There're small differences between the headers generated by GirToBac
70 and to the headers shipped with FreeBasic up to version fbc-0.90. GI
71 (in its <em>*.gir</em> files) only supports constant macros (a
72 string or numerical constant behind the \#define keyword). But the
73 files don't contain any code-generating macros nor inline functions.
74
75 So the GirToBac generated FB headers just contain macros for
76 constants. In addition, some standard macros for the GObject-classes
77 (for C-styled headers) are generated by GirToBac.
78
79 The lack of code creating macros seems to be no big deal, since the
80 GI-libraries are used without these macros in the above mentioned
81 high-level programming languages for years. (In the translation
82 process the missing macros are an advantage, since un-needed macros
83 and pre-processors need no manual removing.) But sometimes it may be
84 better to have some further macro support. In this cases it's
85 possible to extend the GirToBac header with a conventional
86 header-subset containing the missing macros.
87
88 GirToBac currently generates headers in a classic (C-like) style.
89 Additionally it's prepared to generate OOP wrappers for GI libraries
90 as well. Most of the high-level languages are OOP languages and GI
91 is used for translating the GObject C code into real classes. The
92 <em>*.gir</em> files contain all informations to wrap a C library
93 in real FB objects with CONSTRUCTORs , SUBs, FUNCTIONs, PROPERTYs,
94 ... This can help to make FB code more readable and to better
95 support memory management.
96
97 Unfortunatelly the inheritance support in FB is currently (fbc-0.90.1)
98 limited (ie. FB cannot extend a type by several interfaces). And
99 some other features are not well prepared for that style of library
100 bindings (ie EXPLICIT statement in ENUM blocks). So the development
101 of the OOP features in GirToBac is stopped ATM and we have to wait
102 for advanced features in the FB compiler.
103
104
105 \section start How to get started?
106
107 As an example the file <em>example/Gio-2.0.gir</em> is shipped with
108 these archive. You can make your first translation using these file
109 and compare the output against the file <em>Gir/Gio-2.0.bi.org</em>
110 to check the GirToBac executable and get familar with how to call
111 GirToBac.
112
113 Follow these steps:
114
115 - Preparation
116 -# Download and extract GirToBac
117 -# Jump to \em src directory and compile the source code
118 \code fbc -wall GirToBac.bas \endcode
119 - Translation
120 -# Jump to folder \em Gir and call GirToBac to create a new header
121 \code ../src/GirToBac ../example/Gio-2.0 \endcode
122 -# Compare the new file <em>Gio-2.0.bi</em> against the original
123 shipped in the archive
124 \code diff Gio-2.0.bi Gio-2.0.bi.org \endcode
125 (There should be no output from diff -> files are equal.)
126 -# To use headers from GirToBac in your FB source move the folder
127 \em Gir in your \em freebasic/include path. Use
128 \code #INCLUDE ONCE "Gir/NAME.bi" \endcode
129 in the code and replace \em NAME by the libraries name
130 (ie \em Gio-2.0).
131
132
133 \section girs How to get and translate *.gir files?
134
135 A set of GLib headers was created during the development of GirToBac
136 for testing purposes. First check if your header is included. You
137 can download at http://www.freebasic-portal.de/downloads/???. If
138 your library isn't included or isn't up-to-date, you need do make
139 your customized translation.
140
141 <em>*.gir</em> files get generated when a GI-library gets compiled.
142 So you can either get them by downloading the source package of a
143 library and compile it (and all its dependencies, using option
144 <em>--enable-introspection</em>). Thats's the way to go on windows
145 systems.
146
147 On LINUX systems the <em>*.gir</em> files are provided in the
148 package management system. Their names start by \em gir* (ie \em
149 gir1.2-glib-2.0). You can either install them individually or (as a
150 dependency) by installing the libraries \em -dev package (ie \em
151 libglib-2.0-dev). (You'll need the later to compile your source.)
152
153 Create your header by following these steps:
154
155 - Preparation
156 -# Create your output folder (usually <em>.../freebasic/include/Gir</em>)
157 -# Copy basis header <em>Gir/_GirToBac-0.0.bi</em> in your output folder
158 (or install the header set mentioned above).
159 -# Download and extract the <em>*.gir</em> file
160 (ie <em>/usr/lib/girepository-1.0/Xyz-1.0.gir</em>)
161 - Translation
162 -# Jump to your output folder and call GirToBac for translation
163 \code /PATH/TO/GirToBac /usr/lib/girepository-1.0/Xyz-1.0 \endcode
164 -# Create a test file (ie \em test.bas in any folder) containing the line
165 \code #INCLUDE ONCE "Gir/Xyz-1.0.bi" \endcode
166 and compile it
167 \code fbc -wall test.bas \endcode
168 -# In case of no compiler errors you're done (the linker may report
169 that \em -lXyz-1.0 is missing because you didn't install the
170 binaries yet)
171 -# Otherwise see section \ref errorfix. Create a control file (ie
172 <em>Xyz-1.0.GirToBac</em>) in the output folder and add entries.
173 Recompile the \em test.bas code until \em fbc doesn't complain
174 any error.
175
176
177 \section errorfix How to fix Problems?
178
179 Here's a brief summary of the most common problems when compiling the
180 test code (\em test.bas) and how to fix them. A control file in
181 your output folder (<em>.../freebasic/include/Gir</em>) is used to
182 add some translation rules. It's named after the inputs base name
183 with suffix \em GirToBac (ie \em Xyz-1.0.GirToBac for a \em
184 Xyz-1.0.gir file). The rules are specified in XML syntax (see
185 section \ref controlfile). Depending on the error messages thrown by
186 the fbc when compiling the test file, different entries should be
187 done:
188
189 - <B>Duplicated definition ...</B> There's a naming conflict. This
190 usually happens because C syntax is case-sensitve and FBs isn't.
191 Or it happens when an FB keyword is used as a symbol name in C
192 code. Here you should change the FB name to make it unique
193 (usually by adding an underscre character, but also consider to
194 use an ALIAS statement). Example:
195 \code <name search='window' add='_' /> \endcode
196
197 - <B>Expected identifier ...</B> There's a conflict between the C
198 type name and an FB keyword. Or a C type is used that wasn't
199 priviously specified. Rename the type to make it unique or known.
200 Example:
201 \code <type search='int' replace='INTEGER' /> \endcode
202
203 - <B>Illegal specification ...</B> The symbol named in the error
204 message isn't specified befor this position (code line). Its
205 declaration needs to get move forward. Example:
206 \code <first search='synbol_name' /> \endcode </TD>
207
208 - <B>File not found, "Xyz-0.0.bi"</B> The library depends on an other
209 library which isn't translated jet. Download the <em>Xyz-0.0.gir</em>
210 file and translate it first. Then continue with the original
211 translation.
212
213 You may face further problems or error messages when compiling the
214 test file. Sorry, it's not possible to cover all of them here. If you
215 cannot handle an issue don't hasitate to ask for help at
216 http://www.freebasic.net/forum in the \em Libraries subforum.
217
218
219 \section controlfile The control file (*.GirToBac)
220
221 Similar to the <em>*.gir</em> files a control file is XML
222 formated and is named by the same base-name with suffix
223 <em>*.GirToBac</em>. Each control file contains adaption rules for
224 one <em>*.gir</em> file, so each <em>*.gir</em> file
225 may have one <em>*.GirToBac</em> file (located in the output
226 folder). Ie when the GirToBac tool gets called by
227
228 \code ../src/GirToBac ../example/Gio-2.0 \endcode
229
230 it loads the file "Gio-2.0.gir" form directory <em>../example</em> and
231 "Gio-2.0.GirToBac" (if present in the current folder). If the later
232 isn't present, translation gets done without any rules. The
233 generated output gets written to the file "Gio-2.0.bi" in the
234 current folder (where GirToBac is called from).
235
236 Adaption rules may get specified for
237
238 - naming conflicts in variable names (because C naming is
239 case-sensitive and FB's isn't)
240 - typing conflicts in type names (GI is work in process, some C
241 types are untranslated in the <em>*.gir</em> files, currently)
242 - reordering of declarations (the <em>*.gir</em> files contain the
243 symbol declarations in alphabetical order. Since fbc is a single
244 pass compiler it needs to re-order some of them in logical order.)
245
246 Therefor the parser for the configuration file understands three
247 XML-tags and -- depending on the tag -- the attribute \em add and \em
248 replace:
249
250 - <b>name</b> to adapt a symbol name (\em search contains a single word,
251 attribute \em add and \em replace).
252 Example:
253 \code <name search='gtk_stock_add' add='_ ALIAS "gtk_stock_add"' /> \endcode
254 or
255 \code <name search='GTK_RC_STYLE' replace='_GTK_RC_STYLE' /> \endcode
256 - <b>type</b> to adapt types (\em search contains any text, attribute
257 \em add and \em replace).
258 Example:
259 \code <type search='GIconv' add=' PTR' /> \endcode
260 or
261 \code
262 <type search='int' replace='gint32' />
263 <type search='const char* const' replace='CONST gchar PTR CONST' /> \endcode
264 - <b>first</b> to prepend the symbol (\em search contains a single word,
265 no attribute) declaration befor the rest.
266 Example:
267 \code
268 <first search='GtkWidget' />
269 <first search='GtkWidgetClass' />
270 \endcode
271
272 The text in the attribute \em search needs to be specified
273 case-sensitive. It may contain more then one word in case of a \em
274 type rule, but just one word for \em name and \em first rules.
275 \em replace and \em add attributes are used as-is in the output. See
276 <em>*.GirToBac</em> files in folder \em Gir for further examples.
277
278 GirToBac reports duplicated tags while reading the control file. The
279 first tag gets used in that case and all further get skipped. After
280 translating the <em>*.gir</em> file, GirToBac reports about
281 nonexistent symbols (defined in a \em search attribute but not
282 existing in the <em>*.gir</em> file). Removing the corresponding
283 tags from the control file speads up the translation process.
284
285 The control files should be shipped together with the translated
286 header files. On one hand side this helps the users to learn about
287 the differences between C and FB source. On the other hand side the
288 control file helps anyone who want to generate an up-date for the
289 header, further on.
290
291 Have fun, share your results.
292
293 '/