-Getting Started

-===============

-

-.. important:: This page is focused on building |project| **from source**.

- If you just want to install |pymodname|, you need to run: :command:`pip install pyside6`.

-

- For more details, refer to our :ref:`quick-start` guide. Additionally, you can check the

- :ref:`FAQ <faq>` related to the project.

-

-.. _Quick Start: quickstart.html

-

-General Requirements

---------------------

-

-The following prerequisites must be installed before you build |project|.

-On **Linux** you might get them with your operating system package manager, on **macOS**

-you might get them with ``brew``, and on **Windows** you can download the installer from each

-website.

-

-* **Python**: 3.9+ `[official Python website] <https://www.python.org/downloads/>`_

-* **Qt:** 6.8+ `[online installer] <https://download.qt.io/official_releases/online_installers/>`_

-* **CMake:** 3.18+ `[official CMake website] <https://cmake.org/download/>`_

-* **Git:** 2.0+. `[official Git website] <https://git-scm.com/downloads>`_

-* **libclang:** The libclang library, recommended: version 16+ for 6.8+.

- Prebuilt versions for each OS can be `downloaded here`_.

-* Check the `Supported Platforms of Qt`_

-

-.. _downloaded here: https://download.qt.io/development_releases/prebuilt/libclang/

-.. _`Supported Platforms of Qt` : https://doc.qt.io/qt-6/supported-platforms.html

-

-Guides per platform

--------------------

-

-.. toctree::

- :maxdepth: 1

- :hidden:

-

- linux.rst

- macOS.rst

- windows.rst

- package_details.rst

- porting_from2.rst

-

-You can refer to the following pages for platform specific instructions:

-

-.. grid:: 1 3 3 3

- :gutter: 2

-

- .. grid-item-card::

- :img-top: ../images/windows.svg

- :class-item: text-center

-

- +++

- .. button-ref:: windows

- :color: primary

- :outline:

- :expand:

-

- Windows

-

- .. grid-item-card::

- :img-top: ../images/macos.svg

- :class-item: text-center

-

- +++

- .. button-ref:: macOS

- :color: primary

- :outline:

- :expand:

-

- macOS

-

- .. grid-item-card::

- :img-top: ../images/linux.svg

- :class-item: text-center

-

- +++

- .. button-ref:: linux

- :color: primary

- :outline:

- :expand:

-

- Linux

-

-.. important:: |project| does not yet support WebAssembly and the mobile operating systems (Android or iOS).

- Most Linux-based embedded OS provide PySide with their official

- package manager (for example, `Raspbian`_ and `ArchlinuxARM`_).

-

-.. _Raspbian: https://www.raspbian.org/

-.. _ArchlinuxARM: https://archlinuxarm.org/

-

-A normal building command will look like this::

-

- python setup.py install --qtpaths=/path/to/qtpaths \

- --ignore-git \

- --debug \

- --build-tests \

- --parallel=8 \

- --verbose-build \

- --module-subset=Core,Gui,Widgets

-

-Which will build and install the project with **debug** symbols, including the **tests**,

-using **ninja** (instead of make), and considering only the **module subset** of

-:mod:`QtCore <PySide6.QtCore>`, :mod:`QtGui <PySide6.QtGui>`, and

-:mod:`QtWidgets <PySide6.QtWidgets>`.

-

-`CMake Unity Build Mode`_ is used by default for speed-up.

-

-Other important options to consider are:

- * ``--cmake``, to specify the path to the cmake binary,

- * ``--reuse-build``, to rebuild only the modified files,

- * ``--openssl=/path/to/openssl/bin``, to use a different path for OpenSSL,

- * ``--standalone``, to copy over the Qt libraries into the final package to make it work on other

- machines,

- * ``--build-docs``, to enable the documentation build.

- * ``--doc-build-online``, to build documentation using the online template (by

- default it uses the offline)

-

-Testing the installation

-------------------------

-

-Once the installation finishes, you will be able to execute any of our examples::

-

- python examples/widgets/widgets/tetrix.py

-

-Running Tests

--------------

-

-Using the ``--build-tests`` option will enable us to run all the auto tests inside the project::

-

- python testrunner.py test > testlog.txt

-

-.. note:: On Windows, don't forget to have qtpaths in your path

- (:command:`set PATH=C:\\\Path\\\to\\\Qt\\\6.4.0\\\msvc2019_64\\\bin;%PATH%`)

-

-You can also run a specific test (for example ``qpainter_test``) by running::

-

- ctest -R qpainter_test --verbose

-

-.. _cross_compilation:

-

-Cross Compilation

------------------

-

-Starting from 6.3, it is possible to cross-compile Shiboken (module), and

-PySide. This functionality is still in Technical Preview, which means it could

-change in the future releases.

-

-.. important:: The only supported configuration is using a host Linux

- machine to cross-compile to a Linux target platform.

-

-Cross compiling software is a valid use case that many projects rely on,

-however, it is a complicated process that might fail due to many reasons.

-

-Before starting with the process, it is important to understand the details of

-the build system, and the goal of cross compilation.

-

-In the build process, a ``Host`` is the computer you are currently using to

-compile, and a ``Target`` is your embedded device that you are compiling for.

-

-Qt for Python is being built using setuptools, and relies on a ``setup.py`` file

-that is called recursively to build Shiboken (module),

-Shiboken (generator), and PySide. As the generator is creating

-the wrappers for the bindings, it's not cross compiled

-for the target.

-Only the Shiboken (module) and PySide are cross compiled.

-

-The building process requires a Qt installation, and a Python interpreter

-on both the host, and the target. The used Qt versions on both platforms

-should have the same minor version. That is, Qt 6.3 (host)

-cannot be used with a Qt 6.2 (target), or the other way around.

-

-.. note:: It is recommended to use the same version of Qt on both host and target to avoid possible

- unconventional errors.

-

-Prerequisites

-~~~~~~~~~~~~~

-

-First and foremost, you need to have access to the target device because you

-need to copy several system files (sysroot). We recommend a Linux OS that has

-the latest Qt versions, like `Manjaro ARM`_ or `Archlinux ARM`_.

-

-* (target) Install Qt 6.3+ on the system using the package manager.

-* (host) Install Qt 6.3+ on the system using the package manager or Qt

- Installer.

-* (target, host) Install the library and development packages that provide

- C++ headers, linkers, libraries, and compilers.

-* (target, host) Install Python interpreter v3.7 or later

-* (target, host) Install CMake 3.17+

-

-After installing these prerequisites, copy the ``target`` sysroot to your

-``host`` computer. This process is tricky, because copying system files from

-another computer might cause problems with the symbolic links. Here you

-have two options to achieve that.

-

-Option A: Copying the files

-***************************

-

-Create a directory to copy the sysroot of your target device,

-for example ``rpi-sysroot``, and perform the copy on your host computer:

-

-.. code-block:: bash

-

- rsync -vR --progress -rl --delete-after --safe-links \

- USERNAME@TARGET_IP:/{lib,usr,opt/vc/lib} rpi-sysroot/

-

-Ensure to replace ``USERNAME`` and ``TARGET_IP`` with your system appropriate

-values.

-

-Option B: Packaging the file system

-***********************************

-

-Create a package for your sysroot in your target:

-

-.. code-block:: bash

-

- tar cfJ ~/sysroot.tar.xz /lib /usr /opt/vc/lib

-

-Copy the package from the target to your host:

-

-.. code-block:: bash

-

- rsync -vR --progress USERNAME@TARGET_IP:sysroot.tar.xz .

-

-Once you have the tar file, unpack it inside a ``rpi-sysroot`` directory.

-

-Fix Symlinks

-************

-

-It is recommended to run the following script to fix

-most of the issues you would find with symbolic links:

-

-.. code-block:: python

-

- import sys

- from pathlib import Path

- import os

-

- # Take a sysroot directory and turn all the absolute symlinks and turn them into

- # relative ones such that the sysroot is usable within another system.

-

- if len(sys.argv) != 2:

- print(f"Usage is {sys.argv[0]} <sysroot-directory>")

- sys.exit(-1)

-

- topdir = Path(sys.argv[1]).absolute()

-

- def handlelink(filep, subdir):

- link = filep.readlink()

- if str(link)[0] != "/":

- return

- if link.startswith(topdir):

- return

- relpath = os.path.relpath((topdir / link).resolve(), subdir)

- os.unlink(filep)

- os.symlink(relpath, filep)

-

- for f in topdir.glob("**/*"):

- if f.is_file() and f.is_symlink():

- handlelink(f, f.parent)

-

-Setting up the toolchain

-~~~~~~~~~~~~~~~~~~~~~~~~

-

-To perform the cross compilation, you need a special set of compilers,

-libraries, and headers, which runs on the host architecture, but generates

-(binaries/executables) for a target architecture.

-For example, from x86_64 to aarch64.

-

-It is recommended to use the official 10.2 `ARM Developer cross compilers`_,

-which you can find on their official website. For this tutorial, we choose

-``aarch64`` target architecture and we will assume that you downloaded the

-`gcc-arm-10.2-2020.11-x86_64-aarch64-none-linux-gnu.tar.xz`_ file,

-and unpacked it.

-

-With those compilers, now you need a CMake toolchain file. This is

-a configuration file to set the compilers and sysroot information, together

-with extra options like compilation flags, and other details. You can use the

-following file as an example, but keep in mind they might vary:

-

-.. code-block:: cmake

-

- # toolchain-aarch64.cmake

- cmake_minimum_required(VERSION 3.18)

- include_guard(GLOBAL)

-

- set(CMAKE_SYSTEM_NAME Linux)

- set(CMAKE_SYSTEM_PROCESSOR aarch64)

-

- set(TARGET_SYSROOT /path/to/your/target/sysroot)

- set(CROSS_COMPILER /path/to/your/crosscompiling/compilers/)

-

- set(CMAKE_SYSROOT ${TARGET_SYSROOT})

-

- set(ENV{PKG_CONFIG_PATH} "")

- set(ENV{PKG_CONFIG_LIBDIR} ${CMAKE_SYSROOT}/usr/lib/pkgconfig:${CMAKE_SYSROOT}/usr/share/pkgconfig)

- set(ENV{PKG_CONFIG_SYSROOT_DIR} ${CMAKE_SYSROOT})

-

- set(CMAKE_C_COMPILER ${CROSS_COMPILER}/aarch64-none-linux-gnu-gcc)

- set(CMAKE_CXX_COMPILER ${CROSS_COMPILER}/aarch64-none-linux-gnu-g++)

-

- set(QT_COMPILER_FLAGS "-march=armv8-a")

- set(QT_COMPILER_FLAGS_RELEASE "-O2 -pipe")

- set(QT_LINKER_FLAGS "-Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed")

-

- set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)

- set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)

- set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

- set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

-

- include(CMakeInitializeConfigs)

-

- function(cmake_initialize_per_config_variable _PREFIX _DOCSTRING)

- if (_PREFIX MATCHES "CMAKE_(C|CXX|ASM)_FLAGS")

- set(CMAKE_${CMAKE_MATCH_1}_FLAGS_INIT "${QT_COMPILER_FLAGS}")

-

- foreach (config DEBUG RELEASE MINSIZEREL RELWITHDEBINFO)

- if (DEFINED QT_COMPILER_FLAGS_${config})

- set(CMAKE_${CMAKE_MATCH_1}_FLAGS_${config}_INIT "${QT_COMPILER_FLAGS_${config}}")

- endif()

- endforeach()

- endif()

-

- if (_PREFIX MATCHES "CMAKE_(SHARED|MODULE|EXE)_LINKER_FLAGS")

- foreach (config SHARED MODULE EXE)

- set(CMAKE_${config}_LINKER_FLAGS_INIT "${QT_LINKER_FLAGS}")

- endforeach()

- endif()

-

- _cmake_initialize_per_config_variable(${ARGV})

- endfunction()

-

-You need to adjust the paths in these two lines::

-

- set(TARGET_SYSROOT /path/to/your/target/sysroot)

- set(CROSS_COMPILER /path/to/your/crosscompiling/compilers/)

-

-and replace them with the sysroot directory (the one we called ``rpi-sysroot``),

-and the compilers (the ``gcc-arm-10.2-2020.11-x86_64-aarch64-none-linux-gnu/bin`` directory).

-

-

-Cross compiling PySide

-~~~~~~~~~~~~~~~~~~~~~~

-

-After you have installed the prerequisites and copied the necessary files, you

-should have the following:

-

-* The compilers to cross compile (``gcc-argm-10.2-...``),

-* The target sysroot (``rpi-sysroot``),

-* The toolchain cmake file (``toolchain-aarch64.cmake``),

-* The ``pyside-setup`` repository,

-

-An example of the ``setup.py`` invocation might look like the following:

-

-.. code-block:: bash

-

- python setup.py bdist_wheel \

- --parallel=8 --ignore-git --reuse-build --standalone --limited-api=yes \

- --cmake-toolchain-file=/opt/toolchain-aarch64.cmake \

- --qt-host-path=/opt/Qt/6.3.0/gcc_64 \

- --plat-name=linux_aarch64

-

-Depending on the target platform, you could use ``linux_armv7``,

-``linux_aarch64``, etc.

-

-For embedded platforms, which typically do not have Qt and its tools fully

-built, the option ``--no-qt-tools`` can be used to prevent the bundling of the

-tools.

-

-If the process succeeds, you will find the target wheels in your ``dist/``

-directory, for example:

-

-.. code-block:: bash

-

- PySide6-6.3.0-6.3.0-cp36-abi3-manylinux2014_aarch64.whl

- shiboken6-6.3.0-6.3.0-cp36-abi3-manylinux2014_aarch64.whl

-

-

-Troubleshooting

-***************

-

-* If the auto-detection mechanism fails to find the Python or Qt installations

- you have in your target device, you can use two additional options::

-

- --python-target-path=...

-

- and::

-

- --qt-target-path=...

-

-* In case the automatic build of the host Shiboken (generator) fails,

- you can specify the custom path using::

-

- --shiboken-host-path=...

-

-.. _`Manjaro ARM`: https://manjaro.org/download/#ARM

-.. _`Archlinux ARM`: https://archlinuxarm.org

-.. _`ARM Developer Cross Compilers`: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads

-.. _`gcc-arm-10.2-2020.11-x86_64-aarch64-none-linux-gnu.tar.xz`: https://developer.arm.com/-/media/Files/downloads/gnu-a/10.2-2020.11/binrel/gcc-arm-10.2-2020.11-x86_64-aarch64-none-linux-gnu.tar.xz

-

-.. _building_documentation:

-

-Building the documentation

---------------------------

-

-Starting from 6.3, the documentation is not being built by default.

-When using the second option described in this section, make sure to use the

-``--build-docs`` option.

-

-Install the specific documentation requirements in your Python virtual

-environment::

-

- pip install -r requirements-doc.txt

-

-You can find the ``requirements-doc.txt`` file in the root of the repository.

-

-Starting from 5.15, there are two options to build the documentation:

-

-1. Building the base documentation (no API)

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The process of parsing Qt headers to generate the PySide API documentation can take several

-minutes, this means that modifying a specific section of the documentation we currently have, might

-become a hard task. You may only care about the base documentation, which comprises all the

-documentation except for the API documentation.

-

-To generate this, execute the following command::

-

- python setup.py build_base_docs

-

-This will generate an ``html/`` directory with the following structure::

-

- html

- └── pyside6

- ├── index.html

- ├── ...

- └── shiboken6

- ├── index.html

- └── ...

-

-so you can open the main page ``html/pyside6/index.html`` on your browser to check the generated

-files.

-

-This is useful when updating the general sections of the documentation, adding tutorials,

-modifying the build instructions, and more.

-

-.. note:: In case you are interested in only generating the Example Gallery,

- you would need to run ``python tools/example_gallery/main.py`` to

- generate the examples ``documentation`` for the gallery. This will

- also be used internally by the ``build_base_docs`` target

-

-

-2. Building the documentation (Base + API)

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The documentation is being generated using **qdoc** to get the API information, and also **sphinx**

-for the local Python related notes.

-

-The system requires the ``libxml2`` and ``libxslt`` libraries.

-

-After installing ``graphviz`` (included in the ``requirements-doc.txt`` file),

-the ``dot`` command needs to be in PATH, otherwise,

-the process will fail. Installing ``graphviz`` system-wide is also an option.

-

-Since the process relies on a Qt installation, you need to specify where the

-``qtbase`` directory of a Qt source tree is located by passing it to

-the command line option ``--qt-src-dir``.

-

-Once the common ``setup.py`` build process finishes (remember to use

-``--build-docs`` to enable the documentation build, and ``--doc-build-online``

-to get the HTML files), you can go to the generated

-``build/<your_env_name>/build/pyside6`` directory, and run::

-

- ninja apidoc

-

-You can add ``-j X``, to perform the build process in parallel with

-X processes.

-

-.. note:: The :command:`apidoc` make target builds offline documentation in ``QCH``

- (Qt Compressed Help) format by default. You can switch to building for the

- online use with the ``--doc-build-online`` configure option.

-

-The target executes several steps:

-

-#. The ``qdoc`` tool is run over the Qt source code to produce documentation in WebXML format.

-#. ``shiboken6`` is run to extract the functions for which bindings exist from WebXML and convert it into RST.

-#. ``sphinx`` is run to produce the documentation in HTML format.

-

-Re-running the command will not execute step 1 unless the file

-``qdoc-output/webxml/qtcore-index.webxml`` is removed from the build tree.

-Similarly, step 2 will not be executed unless the file ``base/PySide6/QtCore/index.rst``

-is removed.

-

-Finally, you will get a ``html`` directory containing all the generated documentation. The offline

-help files, ``PySide.qch`` and ``Shiboken.qch``, can be moved to any directory of your choice. You

-can find ``Shiboken.qch`` in the build directory, ``build/<your_env_name>/build/shiboken6/doc/html``.

-

-If you want to temporarily change a ``.rst`` file to examine the impact on

-formatting, you can re-run ``sphinx`` in the ``doc`` directory::

-

- sphinx-build base html

-

-Viewing offline documentation

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The offline documentation (QCH) can be viewed using the *Qt Creator* IDE or

-*Qt Assistant*, which is a standalone application for viewing QCH files.

-

-To view the QCH using *Qt Creator*, following the instructions outlined in

-`Using Qt Creator Help Mode <https://doc.qt.io/qtcreator/creator-help.html>`_.

-If you chose to use *Qt Assistant* instead, use the following command to register

-the QCH file before launching *Qt Assistant*::

-

- assistant -register PySide.qch

-

-Troubleshooting documentation

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The documentation uses intersphinx to link from the PySide to the

-Shiboken documentation. This can fail if

-

-* the default ``QCH`` format is used; in which case the required ``objects.inv``

- files are not generated. Use ``--doc-build-online``.

-* base and full doc builds are mixed, resulting in wrong values for the

- intersphinx location in the CMake files. Re-run ``cmake`` to fix this.

-

-Using the internal tools

-------------------------

-

-A set of tools can be found under the ``tools/`` directory inside the ``pyside-setup`` repository.

-

-* ``checklibs.py``: Script to analyze dynamic library dependencies of Mach-O binaries.

- To use this utility, just run::

-

- python checklibs.py /path/to/some.app/Contents/MacOS/Some

-

- This script was fetched from this repository_.

-

-* ``create_changelog.py``: Script used to create the CHANGELOG that you can find in the ``dist/``

- directory. Usage::

-

- python create_changelog.py -r 6.0.1 -v v6.0.0..6.0 -t bug-fix

-

-* ``debug_windows.py``: This script can be used to find out why PySide modules

- fail to load with various DLL errors like Missing DLL or Missing symbol in DLL.

-

- You can think of it as a Windows version of :command:`ldd` / ``LD_DEBUG``.

-

- Underneath, it uses the :command:`cdb.exe` command line debugger and the :command:`gflags.exe`

- tool, which are installed with the latest Windows Kit.

-

- The aim is to help developers debug issues that they may encounter using the PySide imports on

- Windows. The user should then provide the generated log file.

-

- Incidentally it can also be used for any Windows executables, not just Python.

- To use it just run::

-

- python debug_windows.py

-

-* ``missing_bindings.py``: This script is used to compare the state of PySide and PyQt

- regarding available modules and classses. This content is displayed in our `wiki page`_,

- and can be used as follows::

-

- python missing_bindings.py --qt-version 6.0.1 -w all

-

-.. note:: The script relies on BeautifulSoup to parse the content and generate a list of the

- missing bindings.

-

-.. _repository: https://github.com/liyanage/macosx-shell-scripts/

-.. _`wiki page`: https://wiki.qt.io/Qt_for_Python_Missing_Bindings

-.. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/

-.. _`CMake Unity Build Mode` : https://cmake.org/cmake/help/latest/prop_tgt/UNITY_BUILD.html

-Getting Started on Linux

-==========================

-

-Requirements

-------------

-

-* GCC

-* ``sphinx`` package for the documentation (optional).

-* Depending on your linux distribution, the following dependencies might also be required:

-

- * ``libgl-dev``, ``python-dev``, and ``python-setuptools``.

-* Check the platform dependencies of `Qt for Linux/X11`_.

-

-Building from source

---------------------

-

-Creating a virtual environment

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The ``venv`` module allows you to create a local, user-writeable copy of a python environment into

-which arbitrary modules can be installed and which can be removed after use::

-

- python -m venv testenv

- source testenv/bin/activate

-

-will create and use a new virtual environment, which is indicated by the command prompt changing.

-

-Setting up CLANG

-~~~~~~~~~~~~~~~~

-

-If you don't have libclang already in your system, you can download from the Qt servers::

-

- wget https://download.qt.io/development_releases/prebuilt/libclang/libclang-release_18.1.5-based-linux-Rhel8.6-gcc10.3-x86_64.7z

-

-Extract the files, and leave it on any desired path, and set the environment

-variable required::

-

- 7z x libclang-release_18.1.5-based-linux-Rhel8.6-gcc10.3-x86_64.7z

- export LLVM_INSTALL_DIR=$PWD/libclang

-

-Getting the source

-~~~~~~~~~~~~~~~~~~

-

-Cloning the official repository can be done by::

-

- git clone https://code.qt.io/pyside/pyside-setup

-

-Checking out the version that we want to build, for example 6.8::

-

- cd pyside-setup && git checkout 6.8

-

-Install the general dependencies::

-

- pip install -r requirements.txt

-

-For building the documentation::

-

- pip install -r requirements-doc.txt

-

-.. note:: Keep in mind you need to use the same version as your Qt installation.

- Additionally, :command:`git checkout -b 6.8 --track origin/6.8` could be a better option

- in case you want to work on it.

-

-Building and Installing (setuptools)

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The ``setuptools`` approach uses the ``setup.py`` file to execute the build,

-install, and packaging steps.

-

-Check your Qt installation path, to specifically use that version of qtpaths to build PySide.

-for example, :command:`/opt/Qt/6.8.0/gcc_64/bin/qtpaths`.

-

-Build can take a few minutes, so it is recommended to use more than one CPU core::

-

- python setup.py build --qtpaths=/opt/Qt/6.8.0/gcc_64/bin/qtpaths --build-tests --ignore-git --parallel=8

-

-To install on the current directory, just run::

-

- python setup.py install --qtpaths=/opt/Qt/6.8.0/gcc_64/bin/qtpaths --build-tests --ignore-git --parallel=8

-

-Building and Installing (cmake)

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The ``setuptools`` approach includes internal ``CMake`` calls when

-building and installing the project, but a CMake-only approach is only

-recommended for packaging the project for distribution builds.

-

-Assumming that Qt is in PATH, for example, the configure step can be done with::

-

- cmake -B /path/to/the/build/directory \

- -S /path/to/the/pyside-setup \

- -DCMAKE_INSTALL_PREFIX=/where/to/install \

- -DPython_EXECUTABLE=/path/to/interpreter

-

-.. note:: You can add `-DFORCE_LIMITED_API=yes` in case you want to have a

- build which will be compatible with Python 3.7+.

-

-and then for building::

-

- cmake --build /path/to/the/build/directory --parallel X

-

-where `X` is the amount of processes you want to use.

-Finally, the install step can be done with::

-

- cmake --install /path/to/the/build/directory

-

-.. note:: You can build only pyside6 or only shiboken6 by using

- the diferent source directories with the option `-S`.

-

-

-Test installation

-~~~~~~~~~~~~~~~~~

-

-You can execute one of the examples to verify the process is properly working.

-Remember to properly set the environment variables for Qt and PySide::

-

- python examples/widgets/widgets/tetrix.py

-

-.. _`Qt for Linux/X11`: https://doc.qt.io/qt-6/linux.html

-Getting Started on macOS

-========================

-

-Requirements

-------------

-

-* `XCode`_ 8.2 (macOS 10.11), 8.3.3 (macOS 10.12), 9 (macOS 10.13), 10.1 (macOS 10.14)

-* ``sphinx`` package for the documentation (optional).

-* Depending on your OS, the following dependencies might also be required:

-

- * ``libgl-dev``, ``python-dev``, and ``python-setuptools``.

-

-* Check the platform dependencies of `Qt for macOS`_.

-

-.. _XCode: https://developer.apple.com/xcode/

-.. _`Qt for macOS`: https://doc.qt.io/qt-6/macos.html

-

-Building from source

---------------------

-

-Creating a virtual environment

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The ``venv`` module allows you to create a local, user-writeable copy of a python environment into

-which arbitrary modules can be installed and which can be removed after use::

-

- python -m venv testenv # your interpreter could be called 'python3'

- source testenv/bin/activate

-

-will create and use a new virtual environment, which is indicated by the command prompt changing.

-

-Setting up CLANG

-~~~~~~~~~~~~~~~~

-

-If you don't have libclang already in your system, you can download from the Qt servers::

-

- wget https://download.qt.io/development_releases/prebuilt/libclang/libclang-release_18.1.5-based-macos-universal.7z

-

-Extract the files, and leave it on any desired path, and set the environment

-variable required::

-

- 7z x libclang-release_18.1.5-based-macos-universal.7z

- export LLVM_INSTALL_DIR=$PWD/libclang

-

-Getting PySide

-~~~~~~~~~~~~~~

-

-Cloning the official repository can be done by::

-

- git clone https://code.qt.io/pyside/pyside-setup

-

-Checking out the version that we want to build, for example, 6.8::

-

- cd pyside-setup && git checkout 6.8

-

-Install the general dependencies::

-

- pip install -r requirements.txt

-

-For building the documentation::

-

- pip install -r requirements-doc.txt

-

-.. note:: Keep in mind you need to use the same version as your Qt installation

-

-Building PySide

-~~~~~~~~~~~~~~~

-

-Check your Qt installation path, to specifically use that version of qtpaths to build PySide.

-for example, ``/opt/Qt/6.8.0/gcc_64/bin/qtpaths``.

-

-Build can take a few minutes, so it is recommended to use more than one CPU core::

-

- python setup.py build --qtpaths=/opt/Qt/6.8.0/gcc_64/bin/qtpaths --build-tests --ignore-git --parallel=8

-

-Installing PySide

-~~~~~~~~~~~~~~~~~

-

-To install on the current directory, just run::

-

- python setup.py install --qtpaths=/opt/Qt/6.8.0/gcc_64/bin/qtpaths --build-tests --ignore-git --parallel=8

-

-Test installation

-~~~~~~~~~~~~~~~~~

-

-You can execute one of the examples to verify the process is properly working.

-Remember to properly set the environment variables for Qt and PySide::

-

- python examples/widgets/widgets/tetrix.py

-.. _package_details:

-

-Package Details

-===============

-

-Having a large project as the Qt Framework available from one simple

-installation line::

-

- pip install pyside6

-

-is really beneficial,

-but it might be confusing to newcomers.

-

-Besides your IDE, you don't need to install anything else to develop your

-Qt application, because the same command installs many tools

-that will help you design UIs, use QML types, generate

-files automatically, translate applications, etc.

-

-Package Dependencies

---------------------

-

-.. image:: packages.png

- :width: 400

- :alt: Packages structure and dependency

-

-Starting from 6.3.0, the ``pyside6`` package (wheel) is almost empty,

-and only includes references to other packages that are required

-to properly use all the modules.

-This packages are:

-

-* ``pyside6-essentials``, `essential Qt modules <https://pypi.org/project/PySide6-Essentials/>`_,

-* ``pyside6-addons``, `additional Qt modules <https://pypi.org/project/PySide6-Addons/>`_,

-* ``shiboken6``, a utility Python module.

-

-You can verify this by running ``pip list`` to check the installed

-packages in your Python (virtual) environment::

-

- (env) % pip list

- Package Version

- ------------------ -------

- pip 22.0.4

- PySide6 6.3.0

- PySide6-Addons 6.3.0

- PySide6-Essentials 6.3.0

- setuptools 58.1.0

- shiboken6 6.3.0

-

-Both ``pyside6-essentials`` and ``pyside6-addons`` contain Qt binaries

-(``.so``, ``.dll``, or ``.dylib``) that are used by the Python wrappers

-that enable you to use the Qt modules from Python.

-For example, in the ``QtCore`` module, you will find

-on Linux:

-

-* ``PySide6/QtCore.abi3.so``, and

-* ``PySide6/Qt/lib/libQt6Core.so.6``

-

-inside the ``site-packages`` directory of your (virtual) environment.

-The first is the *importable* module which depends on the second file

-which is the original QtCore library.

-

-.. note:: The package ``shiboken6-generator`` is not a dependency,

- and it's not available on PyPi. The reason, is that it depends on

- ``libclang``, which is a large library that we don't package, and

- requires a special configuration for you to use. Check the `Shiboken

- Documentation`_ for more details.

-

-..

- Adding the full URL because it's a different sphinx project.

-.. _`Shiboken Documentation`: https://doc.qt.io/qtforpython/shiboken6/gettingstarted.html

-

-Tools Included

---------------

-

-PySide6 comes bundled with a set of tools that assist in making the development experience with

-PySide6 more efficient. The list of tools can be found :ref:`here <package_tools>`.

-Porting Applications from PySide2 to PySide6

-============================================

-

-Module Availability

--------------------

-

-Qt for Python 6.2.0 provides all modules planned for inclusion in Qt 6.

-

-Module-Level Changes

---------------------

-

-* The modules *QtMacExtras*, *Qt Quick Controls 1*, *QtWinExtras*,

- *QtXmlPatterns* and *QtX11Extras* have been removed.

-* ``QStateMachine`` and related classes have been extracted to a new

- *QtStateMachine* module.

-* The modules *QtWebKit* and *QtWebKitWidgets* have been replaced by the new

- *QtWebEngineCore*, *QtWebEngineQuick* and *QtWebEngineWidgets* modules.

-* ``QXmlReader`` and related classes (*SAX API*) have been removed.

-* The content of the *QtOpenGL* module has been replaced. The class

- ``QGLWidget`` and related classes (``QGLContext``, ``QGLFunctions``,

- ``QGLShaderProgram``) have been removed. Parts of the *Open GL*

- functionality from *QtGui* have been extracted into this module, for example

- ``QOpenGLBuffer`` and ``QOpenGLShaderProgram``.

- There is a new module *QtOpenGLWidgets* which contains the class

- ``QOpenGLWidget``, a replacement for ``QGLWidget``.

-

-As *Open GL* is phasing out,

-`QRhi <https://doc.qt.io/qt-6/topics-graphics.html>`_ should be considered

-for graphics applications.

-

-Imports

--------

-

-The first thing to do when porting applications is to replace the

-import statements:

-

-.. code-block:: python

-

- from PySide2.QtWidgets import QApplication

- from PySide2 import QtCore

-

-needs to be changed to:

-

-.. code-block:: python

-

- from PySide6.QtWidgets import QApplication

- from PySide6 import QtCore

-

-

-Some classes are in a different module now, for example

-``QAction`` and ``QShortcut`` have been moved from ``QtWidgets`` to ``QtGui``.

-

-For *Qt Charts* and *Qt Data Visualization*, the additional namespaces have been

-removed. It is now possible to use:

-

-.. code-block:: python

-

- from PySide6.QtCharts import QChartView

-

-directly.

-

-

-Class/Function Deprecations

----------------------------

-

-Then, the code base needs to be checked for usage of deprecated API and adapted

-accordingly. For example:

-

-* The High DPI scaling attributes ``Qt.AA_EnableHighDpiScaling``,

- ``Qt.AA_DisableHighDpiScaling`` and ``Qt.AA_UseHighDpiPixmaps`` are

- deprecated. High DPI is by default enabled in Qt 6 and cannot be turned off.

-* ``QDesktopWidget`` has been removed. ``QScreen`` should be used instead,

- which can be retrieved using ``QWidget.screen()``,

- ``QGuiApplication.primaryScreen()`` or ``QGuiApplication.screens()``.

-* ``QFontMetrics.width()`` has been renamed to ``horizontalAdvance()``.

-* ``QMouseEvent.pos()`` and ``QMouseEvent.globalPos()`` returning a ``QPoint``

- as well as ``QMouseEvent.x()`` and ``QMouseEvent.y()`` returning ``int``

- are now deprecated. ``QMouseEvent.position()`` and

- ``QMouseEvent.globalPosition()`` returning a ``QPointF`` should be used

- instead.

-* ``Qt.MidButton`` has been renamed to ``Qt.MiddleButton``.

-* ``QOpenGLVersionFunctionsFactory.get()`` instead of

- ``QOpenGLContext.versionFunctions()`` should be used to obtain

- *Open GL* functions.

-* ``QRegExp`` has been replaced by ``QRegularExpression``.

-* ``QWidget.mapToGlobal()`` and ``QWidget.mapFromGlobal()`` now also accept

- and return ``QPointF``.

-* Functions named ``exec_`` (classes ``QCoreApplication``, ``QDialog``,

- ``QEventLoop``) have been renamed to ``exec`` which became possible

- in Python 3.

-

-More information can be found in the

-`Porting to Qt 6 <https://doc.qt.io/qt-6/portingguide.html>`_ Guide

-and the `Qt 6.2 Documentation <https://doc.qt.io/qt-6/index.html>`_ .

-Getting Started on Windows

-==========================

-

-The Qt library has to be built with the same version of MSVC as Python and PySide, this can be

-selected when using the online installer.

-

-Requirements

-------------

-

-* `MSVC2022`_ for Python 3 on Windows,

-* `OpenSSL`_ (optional for SSL support, Qt must have been configured using the same SSL library).

-* ``sphinx`` package for the documentation (optional).

-* Check the platform dependencies of `Qt for Windows`_.

-

-.. note:: The Python provided by the Microsoft Store is not compatible with PySide. Please

- use https://www.python.org/downloads/ to get a Python Interpreter.

-

-.. _MSVC2022: https://visualstudio.microsoft.com/downloads/

-.. _OpenSSL: https://sourceforge.net/projects/openssl/

-.. _`Qt for Windows`: https://doc.qt.io/qt-6/windows.html

-

-Building from source on Windows 10

-----------------------------------

-

-Creating a virtual environment

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-

-The ``venv`` module allows you to create a local, user-writeable copy of a python environment into

-which arbitrary modules can be installed and which can be removed after use::

-

- python -m venv testenv

- call testenv\Scripts\activate

-

-will create and use a new virtual environment, which is indicated by the command prompt changing.

-

-Setting up CLANG

-~~~~~~~~~~~~~~~~

-

-libclang can be downloaded from the

-`Qt servers <https://download.qt.io/development_releases/prebuilt/libclang>`_.

-for example, ``libclang-release_18.1.5-based-windows-vs2019_64.7z``.

-

-Note that from version 12 onwards, the prebuilt Windows binaries from

-`LLVM <https://www.llvm.org>`_ no longer contain CMake configuration files; so

-they can no longer be used.

-

-Extract the files, and leave it on any desired path, for example, ``c:``,

-and set the environment variable required::

-

- set LLVM_INSTALL_DIR=c:\libclang

- set PATH=C:\libclang\bin;%PATH%

-

-Getting PySide

-~~~~~~~~~~~~~~

-

-Cloning the official repository can be done by::

-

- git clone https://code.qt.io/pyside/pyside-setup

-

-Checking out the version that we want to build, for example, 6.8::

-

- cd pyside-setup && git checkout 6.8

-

-Install the general dependencies::

-

- pip install -r requirements.txt

-

-For building the documentation::

-

- pip install -r requirements-doc.txt

-

-.. note:: Keep in mind you need to use the same version as your Qt installation

-

-Building PySide

-~~~~~~~~~~~~~~~

-

-Check your Qt installation path, to specifically use that version of qtpaths to build PySide.

-for example, ``C:\Qt\6.8.0\msvc2019_64\bin\qtpaths.exe``.

-

-Build can take a few minutes, so it is recommended to use more than one CPU core::

-

- python setup.py build --qtpaths=c:\path\to\qtpaths.exe --openssl=c:\path\to\openssl\bin --build-tests --ignore-git --parallel=8

-

-.. _creating_windows_debug_builds:

-

-Creating Debug Builds

-~~~~~~~~~~~~~~~~~~~~~

-

-* Choose *Custom Installation* when installing Python and tick the options for

- debug binaries and libraries

-

-* Use ``venv`` to create a virtual environment and pass the debug binary::

-

- python_d.exe -m venv testenv_d

-

-* Use ``python_d.exe`` to invoke ``setup.py``

-

-.. note:: Make sure you add the ``--debug`` option to the ``python setup.py install`` to produce a debug build

-

-

-Installing PySide

-~~~~~~~~~~~~~~~~~

-

-To install on the current directory, just run::

-

- python setup.py install --qtpaths=c:\path\to\qtpaths.exe --openssl=c:\path\to\openssl\bin --build-tests --ignore-git --parallel=8

-

-Test installation

-~~~~~~~~~~~~~~~~~

-

-You can execute one of the examples to verify the process is properly working.

-Remember to properly set the environment variables for Qt and PySide::

-

- python examples/widgets/widgets/tetrix.py