diff options
Diffstat (limited to 'sources/shiboken6/doc/shibokengenerator.rst')
| -rw-r--r-- | sources/shiboken6/doc/shibokengenerator.rst | 126 |
1 files changed, 95 insertions, 31 deletions
diff --git a/sources/shiboken6/doc/shibokengenerator.rst b/sources/shiboken6/doc/shibokengenerator.rst index ee0b54800..14340ab69 100644 --- a/sources/shiboken6/doc/shibokengenerator.rst +++ b/sources/shiboken6/doc/shibokengenerator.rst @@ -49,15 +49,24 @@ care of interfacing Python and the underlying C++ library. Handwritten inputs ================== -Creating new bindings involves creating two pieces of "code": the typesystem and -the inject code. - -:typesystem: XML files that provides the developer with a tool to customize the +Creating new bindings involves creating several pieces of "code": the header, +the typesystem and, in most cases, the injected code. + +**header** A header with ``#include`` directives listing all the headers of the + desired classes. This header is not referenced by the generated code. + Alternatively, it is possible to pass a list of the headers of the + desired classes directly on the command line. In this case, + the command line option ``--use-global-header`` should be passed as + well to prevent the headers from being suppressed in the generated + code. + +::ref:`typesystem`: XML files that provides the developer with a tool to customize the way that the generators will see the classes and functions. For example, functions can be renamed, have its signature changed and many other actions. -:inject code: allows the developer to insert handwritten code where the generated - code is not suitable or needs some customization. +::ref:`inject code <codeinjectionsemantics>`: allows the developer to insert + handwritten code where the generated code is not suitable or + needs some customization. .. _command-line: @@ -103,11 +112,30 @@ Options ``--avoid-protected-hack`` Avoid the use of the '#define protected public' hack. -.. _use-isnull-as-nb_nonzero: +.. _use-isnull-as-nb-bool: + +``--use-isnull-as-nb-bool`` + If a class has an isNull() const method, it will be used to + compute the value of boolean casts (see :ref:`bool-cast`). + The legacy option ``--use-isnull-as-nb_nonzero`` has the + same effect, but should not be used any more. + +``--lean-headers`` + Forward declare classes in module headers instead of including their class + headers where possible. + +.. _use-operator-bool-as-nb-bool: + +``--use-operator-bool-as-nb-bool`` + If a class has an operator bool, it will be used to compute + the value of boolean casts (see :ref:`bool-cast`). + The legacy option ``--use-operator-bool-as-nb_nonzero`` has the + same effect, but should not be used any more. -``--use-isnull-as-nb_nonzero`` - If a class have an isNull() const method, it will be used to - compute the value of boolean casts +.. _no-implicit-conversions: + +``--no-implicit-conversions`` + Do not generate implicit_conversions for function arguments. .. _api-version: @@ -127,6 +155,15 @@ Options fully qualified Python type names ('Module.Class'), but the module can be omitted ('Class'). +.. _conditional_keywords: + +``-keywords=keyword1[,keyword2,...]`` + A comma-separated list of keywords for conditional typesystem parsing + (see :ref:`conditional_processing`). + +``--use-global-header`` + Use the global headers passed on the command line in generated code. + .. _generation-set: ``--generation-set`` @@ -165,12 +202,21 @@ Options When '-' is passed as the first option in the list, none of the options built into shiboken will be added, allowing for a complete replacement. +``--compiler=<type>`` + Emulated compiler type (g++, msvc, clang) + +``--compiler-path=<file>`` + Path to the compiler for determining builtin include paths + +``--platform=<file>`` + Emulated platform (windows, darwin, unix) + .. _include-paths: ``-I<path>, --include-paths=<path>[:<path>:...]`` Include paths used by the C++ parser. -... _system-include-paths: +.. _system-include-paths: ``-isystem<path>, --system-include-paths=<path>[:<path>:...]`` System include paths used by the C++ parser @@ -180,6 +226,12 @@ Options ``-F<path>, --framework-include-paths=<path>[:<path>:...]`` Framework include paths used by the C++ parser +.. _force-process-system-include-paths: + +``--force-process-system-include-paths=<path>[:<path>:...]`` + Include paths that are considered as system headers by the C++ parser, + but should still be processed to extract types + .. _language-level: ``--language-level=, -std=<level>`` @@ -205,6 +257,10 @@ Options ``--no-suppress-warnings`` Show all warnings. +``--log-unmatched`` + Prints :ref:`suppress-warning` and :ref:`rejection` elements that were + not matched. This is useful for cleaning up old type system files. + .. _silent: ``--silent`` @@ -220,6 +276,9 @@ Options ``--help`` Display this help and exit. +``--print-builtin-types`` + Print information about builtin types + .. _version: ``--version`` @@ -260,6 +319,12 @@ QtDocGenerator Options List of additional XML files to be converted to .rst files (for example, tutorials). +``--inheritance-file=<file>`` + Generate a JSON file containing the class inheritance. + +``--disable-inheritance-diagram`` + Disable the generation of the inheritance diagram. + .. _project-file: ******************** @@ -277,18 +342,18 @@ The project file structure Here follows a comprehensive example of a generator project file. - .. code-block:: ini +.. code-block:: ini - [generator-project] - generator-set = path/to/generator/CHOICE_GENERATOR - header-file = DIR/global.h" /> - typesystem-file = DIR/typesystem_for_your_binding.xml - output-directory location="OUTPUTDIR" /> - include-path = path/to/library/being/wrapped/headers/1 - include-path = path/to/library/being/wrapped/headers/2 - typesystem-path = path/to/directory/containing/type/system/files/1 - typesystem-path = path/to/directory/containing/type/system/files/2 - enable-parent-ctor-heuristic + [generator-project] + generator-set = path/to/generator/CHOICE_GENERATOR + header-file = DIR/global.h" /> + typesystem-file = DIR/typesystem_for_your_binding.xml + output-directory location="OUTPUTDIR" /> + include-path = path/to/library/being/wrapped/headers/1 + include-path = path/to/library/being/wrapped/headers/2 + typesystem-path = path/to/directory/containing/type/system/files/1 + typesystem-path = path/to/directory/containing/type/system/files/2 + enable-parent-ctor-heuristic Project file tags @@ -304,26 +369,25 @@ generator project file following simple conversion rules. For tags without options, just write as an empty tag without any attributes. Example: - .. code-block:: bash +.. code-block:: bash - --BOOLEAN-ARGUMENT + --BOOLEAN-ARGUMENT becomes - .. code-block:: ini +.. code-block:: ini - BOOLEAN-ARGUMENT + BOOLEAN-ARGUMENT and - .. code-block:: bash +.. code-block:: bash - --VALUE-ARGUMENT=VALUE + --VALUE-ARGUMENT=VALUE becomes - .. code-block:: ini - - VALUE-ARGUMENT = VALUE +.. code-block:: ini + VALUE-ARGUMENT = VALUE |