GirToBac  0.2
Create FB Headers from GObject Introspection *.gir files
 All Classes Files Functions Variables Enumerations Enumerator 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 [FreeBasic
14 (FB)](http://www.freebasic.net) programming language. It creates FB
15 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 before).
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 -w all 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  The only output from diff should be (no further differences)
126  \code
127 4c4
128 < ' Auto-translated from file ../example/Gio-2.0.gir
129 ---
130 > ' Auto-translated from file Gio-2.0.gir \endcode
131  -# To use headers from GirToBac in your FB source, move the folder
132  \em Gir and its files in your \em freebasic/include path. Then use
133  \code #INCLUDE ONCE "Gir/NAME.bi" \endcode
134  in your code and replace \em NAME by the libraries name
135  (ie \em Gio-2.0).
136 
137 
138 \section girs How to get and translate *.gir files?
139 
140 A set of GLib headers was created during the development of GirToBac
141 for testing purposes. First check if your header is included. You
142 can download at
143 http://www.freebasic-portal.de/downloads/bibliotheken/gtk-3-header-dateien-fuer-freebasic-191.html
144 If your library isn't included or isn't up-to-date, you need do make
145 your customized translation.
146 
147 <em>*.gir</em> files get generated when a GI-library gets compiled.
148 So you can either get them by downloading the source package of a
149 library and compile it (and all its dependencies, using option
150 <em>--enable-introspection=yes</em>). Thats's the way to go on windows
151 systems.
152 
153 On LINUX systems the <em>*.gir</em> files are provided in the package
154 management system. They're included in the *-dev packages (hopefully
155 this will change in near future). Ie \em Gtk-3.0.gir is in package \em
156 libgtk-3-dev on Debian based systems. (You'll need this package to
157 compile your source.)
158 
159 Create your header by following these steps:
160 
161 - Preparation
162  -# Create your output folder (usually <em>.../freebasic/include/Gir</em>)
163  -# Copy basis header <em>Gir/_GirToBac-0.0.bi</em> in your output folder
164  (or install the header set mentioned above).
165  -# Download and extract the <em>*.gir</em> file
166  (ie <em>/usr/lib/girepository-1.0/Xyz-1.0.gir</em>)
167 - Translation
168  -# Jump to your output folder and call GirToBac for translation
169  \code /PATH/TO/GirToBac /usr/lib/girepository-1.0/Xyz-1.0 \endcode
170  -# Create a test file (ie \em test.bas in any folder) containing the line
171  \code #INCLUDE ONCE "Gir/Xyz-1.0.bi" \endcode
172  and compile it
173  \code fbc -wall test.bas \endcode
174  -# In case of no compiler errors you're done (the linker may report
175  that \em -lXyz-1.0 is missing because you didn't install the
176  binaries yet)
177  -# Otherwise see section \ref errorfix. Create a control file (ie
178  <em>Xyz-1.0.GirToBac</em>) in the output folder and add entries.
179  Recompile the \em test.bas code until \em fbc doesn't complain
180  any error.
181 
182 
183 \section errorfix How to fix Problems?
184 
185 Here's a brief summary of the most common problems when compiling the
186 test code (\em test.bas) and how to fix them. A control file in
187 your output folder (<em>.../freebasic/include/Gir</em>) is used to
188 add some translation rules. It's named after the inputs base name
189 with suffix \em GirToBac (ie \em Xyz-1.0.GirToBac for a \em
190 Xyz-1.0.gir file). The rules are specified in XML syntax (see
191 section \ref controlfile). Depending on the error messages thrown by
192 the fbc when compiling the test file, different entries should be
193 done:
194 
195 - <B>Duplicated definition ...</B> There's a naming conflict. This
196  usually happens because C syntax is case-sensitve and FBs isn't.
197  Or it happens when an FB keyword is used as a symbol name in C
198  code. Here you should change the FB name to make it unique
199  (usually by adding an underscre character, but also consider to
200  use an ALIAS statement). Example:
201  \code <name search='window' add='_' /> \endcode
202 
203 - <B>Expected identifier ...</B> There's a conflict between the C
204  type name and an FB keyword. Or a C type is used that wasn't
205  priviously specified. Rename the type to make it unique or known.
206  Example:
207  \code <type search='int' replace='gint' /> \endcode
208 
209 - <B>Illegal specification ...</B> The symbol named in the error
210  message isn't specified before this position (code line). Its
211  declaration needs to get move forward. Example:
212  \code <first search='synbol_name' /> \endcode </TD>
213 
214 - <B>File not found, "Xyz-0.0.bi"</B> The library depends on an other
215  library which isn't translated jet. Download the <em>Xyz-0.0.gir</em>
216  file and translate it first. Then continue with the original
217  translation.
218 
219 You may face further problems or error messages when compiling the
220 test file. Sorry, it's not possible to cover all of them here. If you
221 cannot handle an issue don't hasitate to ask for help at
222 http://www.freebasic.net/forum in the \em Libraries subforum.
223 
224 
225 \section controlfile The control file (*.GirToBac)
226 
227 Similar to the <em>*.gir</em> files a control file is XML
228 formated and is named by the same base-name with suffix
229 <em>*.GirToBac</em>. Each control file contains adaption rules for
230 one <em>*.gir</em> file, so each <em>*.gir</em> file
231 may have one <em>*.GirToBac</em> file (located in the output
232 folder). Ie when the GirToBac tool gets called by
233 
234 \code ../src/GirToBac ../example/Gio-2.0 \endcode
235 
236 it loads the file <em>Gio-2.0.gir</em> form directory
237 <em>../example</em> and file <em>Gio-2.0.GirToBac</em> (if present in
238 the current folder). If the later isn't present, translation gets done
239 without any rules. The generated output gets written to the file
240 <em>Gio-2.0.bi</em> in the current folder (where GirToBac is called
241 from).
242 
243 Adaption rules may get specified for
244 
245 - a mismatch between the library name and its internal namespace
246 - naming conflicts in variable names (because C naming is
247  case-sensitive and FB's isn't)
248 - typing conflicts in type names (GI is work in process, some C
249  types are untranslated in the <em>*.gir</em> files, currently)
250 - reordering of declarations (the <em>*.gir</em> files contain the
251  symbol declarations in alphabetical order. Since fbc is a single
252  pass compiler it needs to re-order some of them in logical order.)
253 - a symbol check to switch off a dummy header when the complete header
254  is in use.
255 - a missmatch between the library name and the name declared in the
256  <em>*.gir</em> file.
257 
258 Therefor the parser for the configuration file understands six XML-tags
259 and -- depending on the tag type -- the attributes \em name, \em add
260 and \em replace:
261 
262 - <b>binary</b> to override the name of the binary. This is useful if
263  the .gir file doesn't contain the right library name.
264  Example (cairo):
265  \code <binary name='cairo' /> \endcode
266 - <b>check</b> to enclose the complete header source by
267  \code
268 #IFNDEF symbol
269 ...
270 #ENDIF \endcode
271  This is useful for a dummy binding that contains just a few type
272  declarations. To avoid interferences with the complete binding, the
273  dummy source can get switched of.
274  Example (cairo):
275  \code <check name='CAIRO_H' /> \endcode
276 - <b>pack</b> to adapt the library namespace (attribute \em name
277  contains the new name in camel case letters).
278  Example (GLib):
279  \code <pack name='G' /> \endcode
280  or (GooCanvas):
281  \code <pack name='Goo' /> \endcode
282 - <b>name</b> to adapt a symbol name (\em search contains a single word,
283  further attributes \em add or \em replace).
284  Example:
285  \code <name search='gtk_stock_add' add='_ ALIAS "gtk_stock_add"' /> \endcode
286  or
287  \code <name search='GTK_RC_STYLE' replace='_GTK_RC_STYLE' /> \endcode
288 - <b>type</b> to adapt types (\em search contains any text, further
289  attributes \em add or \em replace).
290  Example:
291  \code <type search='GIconv' add=' PTR' /> \endcode
292  or
293  \code
294  <type search='void' replace='ANY' />
295  <type search='const char* const' replace='CONST gchar PTR CONST' /> \endcode
296 - <b>first</b> to prepend the symbol (\em search contains a single word,
297  no attribute) declaration before the rest.
298  Example:
299  \code
300  <first search='GtkWidget' />
301  <first search='GtkWidgetClass' />
302  \endcode
303 
304 The text in the attribute \em search needs to be specified
305 case-sensitive. It may contain more then one word in case of a \em
306 type rule, but just one word for \em name and \em first rules.
307 \em replace and \em add attributes are used as-is in the output. See
308 <em>*.GirToBac</em> files in folder \em Gir for further examples.
309 
310 GirToBac reports duplicated tags while reading the control file. The
311 first tag gets used in that case and all further get skipped. After
312 translating the <em>*.gir</em> file, GirToBac reports about
313 nonexistent symbols (defined in a \em search attribute but not
314 existing in the <em>*.gir</em> file). Removing the corresponding
315 tags from the control file speads up the translation process.
316 
317 The control files should be shipped together with the translated
318 header files. On one hand side this helps the users to learn about
319 the differences between C and FB source. On the other hand side the
320 control file helps anyone who want to generate an up-date for the
321 header, further on.
322 
323 
324 Have fun, share your results.
325 
326 */
327 
328 /** \page changelog Changelog
329 \tableofcontents
330 
331 \section v-0-2 GirToBac-0.2
332 
333 New:
334 - GirToBac source 32/64 bit ready.
335 - Translated header code 32/64 bit ready.
336 - Self translated GLib header in use, see [GnomeHeaders-1.0](http://www.freebasic-portal.de/downloads/bibliotheken/gtk-3-header-dateien-fuer-freebasic-191.html).
337 - Configuraton file attributes \em binary, \em check and \em pack.
338 - Caller / callee graphs in the documentation.
339 
340 Bugfixes:
341 - Gir attribute "throws" now recognized in all functions.
342 - String literals (instead of `!@"..."` now correct `@!"..."` is used).
343 - Minor adaptions in the documentation.
344 
345 */