# CMake super project
For development convenience, a CMake super project is included in the root of the repository.

The super project can be built using standalone CMake, or using an IDE's CMake integration
(Qt Creator for example).

Nevertheless the default build process is done via setup.py, in which case each of the
sub-projects are built and installed separately, as mentioned, the super project is just
for development convenience.

## IDE (Qt Creator) case

When using an IDE, just open the root CMakeLists.txt file as a new project, and make sure to
specify the following things:

 * LLVM_INSTALL_DIR - the environment variable should point to your libclang library location
 * Qt               - either select a Qt Kit when configuring the project, or make sure that the
                      qmake binary is present in the PATH environment variable.
 * Python           - the PATH environment variable should also point to the Python interpreter
                      which you wish to use for building the projects (can either be a system
                      interpreter, or a virtualenv one for example)

Once that is done, just re-run CMake, so that it picks up the new environment values.
If needed, all other cache variables defined by the project files can be re-adjusted
(for example FORCE_LIMITED_API).

## Command line CMake case

When building using the command line CMake binary, make sure to invoke it in a separate
build directory, and not in the root source directory.

Make sure you have the correct environment variables set up, as described in the previous section.

The invocation would then look like:
```bash
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
# make or nmake or msbuild or jom
```

# Qt For Python

Qt For Python is the [Python Qt bindings project](http://wiki.qt.io/PySide2), providing
access to the complete Qt 5.x framework as well as to generator tools for rapidly
generating bindings for any C++ libraries.

shiboken2 is the generator used to build the bindings.

See README.pyside2.md and README.shiboken2.md for details.

# PySide2

### Introduction

PySide2 is the official Python module from the
[Qt for Python project](http://wiki.qt.io/Qt_for_Python),
which provides access to the complete Qt 5.12+ framework.

The Qt for Python project is developed in the open, with all facilities you'd expect
from any modern OSS project such as all code in a git repository and an open
design process. We welcome any contribution conforming to the
[Qt Contribution Agreement](https://www.qt.io/contributionagreement/).

### Installation

Since the release of the [Technical Preview](https://blog.qt.io/blog/2018/06/13/qt-python-5-11-released/)
it is possible to install via `pip`, both from Qt's servers
and [PyPi](https://pypi.org/project/PySide2/):

    pip install PySide2

#### Dependencies

PySide2 versions following 5.12 use a C++ parser based on
[Clang](http://clang.org/). The Clang library (C-bindings), version 6.0 or
higher is required for building. Prebuilt versions of it can be downloaded from
[download.qt.io](http://download.qt.io/development_releases/prebuilt/libclang/).

After unpacking the archive, set the environment variable *LLVM_INSTALL_DIR* to
point to the folder containing the *include* and *lib* directories of Clang:

    7z x .../libclang-release_60-linux-Rhel7.2-gcc5.3-x86_64-clazy.7z
    export LLVM_INSTALL_DIR=$PWD/libclang

On Windows:

    7z x .../libclang-release_60-windows-vs2015_64-clazy.7z
    SET LLVM_INSTALL_DIR=%CD%\libclang

### Building from source

For building PySide2 from scratch, please read about
[getting started](https://wiki.qt.io/Qt_for_Python/GettingStarted).
This process will include getting the code:

    git clone https://code.qt.io/pyside/pyside-setup
    cd pyside-setup
    git branch --track 5.12 origin/5.12
    git checkout 5.12

then install the dependencies, and following the instructions per platform.
A common build command will look like:

    python setup.py install --qmake=<path/to/qmake/> --parallel=8 --build-tests

You can obtain more information about the options to build PySide
and Shiboken in [our wiki](https://wiki.qt.io/Qt_for_Python/).

### Documentation and Bugs

You can find more information about the PySide2 module API in the
[official Qt for Python documentation](https://doc.qt.io/qtforpython/).

If you come across any issue, please file a bug report at our
[JIRA tracker](https://bugreports.qt.io/projects/PYSIDE) following
our [guidelines](https://wiki.qt.io/Qt_for_Python/Reporting_Bugs).

### Community

Check *#qt-pyside*, our official IRC channel on FreeNode,
or contact us via our [mailing list](http://lists.qt-project.org/mailman/listinfo/pyside).

### Licensing

PySide2 is available under both Open Source (LGPLv3/GPLv2) and commercial license.
Using PyPi is the recommended installation source, because the content of the wheels is valid for both cases.
For more information, refer to the [Qt Licensing page](https://www.qt.io/licensing/).

# Shiboken2-generator

Shiboken is the generator used by the Qt for Python project.
It outputs C++ code for CPython extensions, which can be compiled
and transformed into a Python module.

C++ projects based on Qt can be wrapped, but also projects
which are not related to Qt.

## How does it work?

Shiboken uses an API Extractor that does most of the job,
but it requires a typesystem (XML file) to customize how the
C++ classes/methods will be exposed to Python.

The typesystem allows you to remove arguments from signatures,
modify return types, inject code and add conversion rules
from the C++ data types to Python data types, manipulate
the ownership of the objects, etc.

# Examples

An example related to wrap a C++ library not depending on Qt
can be found in our [repository](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples/samplebinding).

Additionally, you can find a couple of tests inside the
[git repository](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/sources/shiboken2/tests).

For a more advanced case regarding extending a Qt/C++ application
with Python bindings based on the idea of the PySide module,
you can check the [scriptableapplication](https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples/scriptableapplication)
example in our repository.

# Documentation

You can find more information about Shiboken in our
[official documentation page](https://doc.qt.io/qtforpython/shiboken2/).

# Shiboken2 module

The purpose of the [shiboken2 Python module](https://wiki.qt.io/Qt_for_Python/Shiboken)
is to access information related to the binding generation that could be used to integrate
C++ programs to Python, or even to get useful information to debug
an application.

Mostly the idea is to interact with Shiboken objects,
where one can check if it is valid, or if the generated Python wrapper
is invalid after the underlying C++ object has been destroyed.

More information on the available functions can be found
in our [official documentation](https://doc.qt.io/qtforpython/shiboken2/shibokenmodule.html)