summaryrefslogtreecommitdiffstats
path: root/doc/faq.rst
blob: 38cc3f186e55b339eb790a052b10b00ddfd5cab4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
**************************
Frequently Asked Questions
**************************

This is a list of Frequently Asked Questions about |project|.  Feel free to
suggest new entries!

General
=======

What is the generator?
----------------------

Here the name generator refers actually to a program composed of a set of
*generator classes* that output different resources based on information
contained inside C++ header files.

What is the API Extractor?
--------------------------

It is a library that parses C++ header files and builds a data model around
them in order to ease the work of manipulating these data inside
*generators*.


Is there any similar tools around?
----------------------------------

The generator framework actually started as a fork of the qtscriptgenerator,
with the focus on python bindings instead of QtScript. After some time, the
python-specific code was split from the the header parsing and data model
code. The former became what we call *generator* while the latter is now
called *API Extractor*.

What's the relationship between the generator and the API Extractor?
--------------------------------------------------------------------

The generator system relies heavily in the API Extractor classes, using
them as syntatic sugar to access the data model of the classes being
wrapped.

What are the dependencies to run the generator?
-----------------------------------------------

API Extractor, QtCore and QtXml.

Creating bindings
=================

Can I wrap non-Qt libraries?
----------------------------

Although it's not yet well tested, there's a good chance that non-Qt 
libraries can be wrapped using the generator. But remember that
generator injects runtime dependency on Qt for the generated binding.

Is there any runtime dependency on the generated binding?
---------------------------------------------------------

Yes. Only libshiboken, and the obvious Python interpreter
and the C++ library that is being wrapped.

What do I have to do to create my bindings?
-------------------------------------------

.. todo: put link to typesystem documentation

Most of the work is already done by the API Extractor. The developer creates
a typesystem file with any customization wanted in the generated code, like
removing classes or changing method signatures. The generator will output
the .h and .cpp files with the CPython code that will wrap the target
library for python.

Is there any recommended build system?
--------------------------------------

Both API Extractor and generator uses and recommends the CMake build system.

Can I write closed-source bindings with the generator?
------------------------------------------------------

Yes, as long as you use a LGPL version of Qt, due to runtime requirements.

What is 'inject code'?
----------------------

That's how we call customized code that will be *injected* into the
generated at specific locations. They are specified inside the typesytem.

How can I document my project?
------------------------------

The generator also can generate the API documentation based on the
C++ headers documentation using the qdoc syntax. Optionally you can
inject documentation at specific parts. Likewise *inject code*, the
customized documentation is specified inside the typesystem.

Other
=====

Is there any current limitation within the generator/API Extractor?
-------------------------------------------------------------------

The generator currently does not automatically detects implicit C++
type conversions. Also the code snippets in function signature and
examples are still in C++ inside the generated documentation.