1.. _gen-overview:
2
3******************
4Generator Overview
5******************
6
7The following diagram summarizes Shiboken's role in the Qt for Python
8project.
9
10.. image:: images/qtforpython-underthehood.png
11
12An XML typesystem file is used to specify the types to be exposed to Python
13and to apply modifications to properly represent and manipulate the types in
14the Python World. For example, you can remove and add methods to certain types,
15and also modify the arguments of each method. These actions are inevitable to
16properly handle the data structures or types.
17
18The final outcome of this process is a set of wrappers written in CPython,
19which can be used as a module in your Python code.
20
21In a few words, the Generator is a utility that parses a collection of header and
22typesystem files, generating other files (code, documentation, etc.) as result.
23
24Creating new bindings
25=====================
26
27.. figure:: images/bindinggen-development.png
28   :scale: 80
29   :align: center
30
31   Creating new bindings
32
33Each module of the generator system has an specific role.
34
351. Provide enough data about the classes and functions.
362. Generate valid code, with modifications from typesystems and injected codes.
373. Modify the API to expose the objects in a way that fits you target language best.
384. Insert customizations where handwritten code is needed.
39
40.. figure:: images/shibokenqtarch.png
41   :scale: 80
42   :align: center
43
44   Runtime architecture
45
46The newly created binding will run on top of Shiboken which takes
47care of interfacing Python and the underlying C++ library.
48
49Handwritten inputs
50==================
51
52Creating new bindings involves creating two pieces of "code": the typesystem and
53the inject code.
54
55:typesystem: XML files that provides the developer with a tool to customize the
56             way that the generators will see the classes and functions. For
57             example, functions can be renamed, have its signature changed and
58             many other actions.
59:inject code: allows the developer to insert handwritten code where the generated
60              code is not suitable or needs some customization.
61
62.. _command-line:
63
64Command line options
65********************
66
67Usage
68-----
69
70::
71
72   shiboken [options] header-file(s) typesystem-file
73
74
75Options
76-------
77
78``--disable-verbose-error-messages``
79    Disable verbose error messages. Turn the CPython code hard to debug but saves a few kilobytes
80    in the generated binding.
81
82.. _parent-heuristic:
83
84``--enable-parent-ctor-heuristic``
85    This flag enable an useful heuristic which can save a lot of work related to object ownership when
86    writing the typesystem.
87    For more info, check :ref:`ownership-parent-heuristics`.
88
89.. _pyside-extensions:
90
91``--enable-pyside-extensions``
92    Enable pyside extensions like support for signal/slots. Use this if you are creating a binding based
93    on PySide.
94
95.. _return-heuristic:
96
97``--enable-return-value-heuristic``
98    Enable heuristics to detect parent relationship on return values.
99    For more info, check :ref:`return-value-heuristics`.
100
101.. _avoid-protected-hack:
102
103``--avoid-protected-hack``
104    Avoid the use of the '#define protected public' hack.
105
106.. _use-isnull-as-nb_nonzero:
107
108``--use-isnull-as-nb_nonzero``
109    If a class have an isNull() const method, it will be used to
110    compute the value of boolean casts
111
112.. _api-version:
113
114``--api-version=<version>``
115    Specify the supported api version used to generate the bindings.
116
117.. _documentation-only:
118
119``--documentation-only``
120    Do not generate any code, just the documentation.
121
122.. _drop-type-entries:
123
124``--drop-type-entries="<TypeEntry0>[;TypeEntry1;...]"``
125    Semicolon separated list of type system entries (classes, namespaces,
126    global functions and enums) to be dropped from generation. Values are
127    fully qualified Python type names ('Module.Class'), but the module can
128    be omitted ('Class').
129
130.. _generation-set:
131
132``--generation-set``
133    Generator set to be used (e.g. qtdoc).
134
135.. _skip-deprecated:
136
137``--skip-deprecated``
138    Skip deprecated functions.
139
140.. _diff:
141
142``--diff``
143    Print a diff of wrapper files.
144
145.. _dryrun:
146
147``--dryrun``
148    Dry run, do not generate wrapper files.
149
150.. _--project-file:
151
152``--project-file=<file>``
153    Text file containing a description of the binding project.
154    Replaces and overrides command line arguments.
155
156.. _include-paths:
157
158``-I<path>, --include-paths=<path>[:<path>:...]``
159    Include paths used by the C++ parser.
160
161... _system-include-paths:
162
163``-isystem<path>, --system-include-paths=<path>[:<path>:...]``
164    System include paths used by the C++ parser
165
166.. _framework-include-paths:
167
168``-F<path>, --framework-include-paths=<path>[:<path>:...]``
169    Framework include paths used by the C++ parser
170
171.. _language-level:
172
173``--language-level=, -std=<level>``
174    C++ Language level (c++11..c++17, default=c++14)
175
176.. _typesystem-paths:
177
178``-T<path>, --typesystem-paths=<path>[:<path>:...]``
179    Paths used when searching for type system files.
180
181.. _output-directory:
182
183``--output-directory=[dir]``
184    The directory where the generated files will be written.
185
186.. _license-file=[license-file]:
187
188``--license-file=[license-file]``
189    File used for copyright headers of generated files.
190
191.. _no-suppress-warnings:
192
193``--no-suppress-warnings``
194    Show all warnings.
195
196.. _silent:
197
198``--silent``
199    Avoid printing any message.
200
201.. _debug-level:
202
203``--debug-level=[sparse|medium|full]``
204    Set the debug level.
205
206.. _help:
207
208``--help``
209    Display this help and exit.
210
211.. _version:
212
213``--version``
214    Output version information and exit.
215
216QtDocGenerator Options
217----------------------
218
219.. _doc-parser:
220
221``--doc-parser=<parser>``
222    The documentation parser used to interpret the documentation
223    input files (qdoc|doxygen).
224
225.. _documentation-code-snippets-dir:
226
227``--documentation-code-snippets-dir=<dir>``
228    Directory used to search code snippets used by the documentation.
229
230.. _documentation-data-dir:
231
232``--documentation-data-dir=<dir>``
233    Directory with XML files generated by documentation tool.
234
235.. _documentation-extra-sections-dir=<dir>:
236
237``--documentation-extra-sections-dir=<dir>``
238    Directory used to search for extra documentation sections.
239
240.. _library-source-dir:
241
242``--library-source-dir=<dir>``
243    Directory where library source code is located.
244
245.. _additional-documentation:
246
247``--additional-documentation=<file>``
248   List of additional XML files to be converted to .rst files
249   (for example, tutorials).
250
251.. _project-file:
252
253********************
254Binding Project File
255********************
256
257Instead of directing the Generator behavior via command line, the binding
258developer can write a text project file describing the same information, and
259avoid the hassle of a long stream of command line arguments.
260
261.. _project-file-structure:
262
263The project file structure
264==========================
265
266Here follows a comprehensive example of a generator project file.
267
268    .. code-block:: ini
269
270         [generator-project]
271         generator-set = path/to/generator/CHOICE_GENERATOR
272         header-file = DIR/global.h" />
273         typesystem-file = DIR/typesystem_for_your_binding.xml
274         output-directory location="OUTPUTDIR" />
275         include-path = path/to/library/being/wrapped/headers/1
276         include-path = path/to/library/being/wrapped/headers/2
277         typesystem-path = path/to/directory/containing/type/system/files/1
278         typesystem-path = path/to/directory/containing/type/system/files/2
279         enable-parent-ctor-heuristic
280
281
282Project file tags
283=================
284
285The generator project file tags are in direct relation to the
286:ref:`command line arguments <command-line>`. All of the current command line
287options provided by |project| were already seen on the
288:ref:`project-file-structure`, for new command line options provided by
289additional generator modules (e.g.: qtdoc, Shiboken) could also be used in the
290generator project file following simple conversion rules.
291
292For tags without options, just write as an empty tag without any attributes.
293Example:
294
295    .. code-block:: bash
296
297         --BOOLEAN-ARGUMENT
298
299becomes
300
301    .. code-block:: ini
302
303         BOOLEAN-ARGUMENT
304
305and
306
307    .. code-block:: bash
308
309         --VALUE-ARGUMENT=VALUE
310
311becomes
312
313    .. code-block:: ini
314
315         VALUE-ARGUMENT = VALUE
316
317
318