diff options
Diffstat (limited to 'sources/pyside6/doc/gettingstarted')
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/index.rst | 572 | ||||
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/linux.rst | 119 | ||||
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/macOS.rst | 89 | ||||
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/package_details.rst | 75 | ||||
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/packages.png | bin | 0 -> 12157 bytes | |||
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/porting_from2.rst | 94 | ||||
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/windows.rst | 114 |
7 files changed, 1063 insertions, 0 deletions
diff --git a/sources/pyside6/doc/gettingstarted/index.rst b/sources/pyside6/doc/gettingstarted/index.rst new file mode 100644 index 000000000..51d8bea26 --- /dev/null +++ b/sources/pyside6/doc/gettingstarted/index.rst @@ -0,0 +1,572 @@ +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 diff --git a/sources/pyside6/doc/gettingstarted/linux.rst b/sources/pyside6/doc/gettingstarted/linux.rst new file mode 100644 index 000000000..eb1b5869d --- /dev/null +++ b/sources/pyside6/doc/gettingstarted/linux.rst @@ -0,0 +1,119 @@ +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 diff --git a/sources/pyside6/doc/gettingstarted/macOS.rst b/sources/pyside6/doc/gettingstarted/macOS.rst new file mode 100644 index 000000000..accffbe92 --- /dev/null +++ b/sources/pyside6/doc/gettingstarted/macOS.rst @@ -0,0 +1,89 @@ +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 diff --git a/sources/pyside6/doc/gettingstarted/package_details.rst b/sources/pyside6/doc/gettingstarted/package_details.rst new file mode 100644 index 000000000..113edb686 --- /dev/null +++ b/sources/pyside6/doc/gettingstarted/package_details.rst @@ -0,0 +1,75 @@ +.. _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>`. diff --git a/sources/pyside6/doc/gettingstarted/packages.png b/sources/pyside6/doc/gettingstarted/packages.png Binary files differnew file mode 100644 index 000000000..57e7ca47d --- /dev/null +++ b/sources/pyside6/doc/gettingstarted/packages.png diff --git a/sources/pyside6/doc/gettingstarted/porting_from2.rst b/sources/pyside6/doc/gettingstarted/porting_from2.rst new file mode 100644 index 000000000..6699f54e0 --- /dev/null +++ b/sources/pyside6/doc/gettingstarted/porting_from2.rst @@ -0,0 +1,94 @@ +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>`_ . diff --git a/sources/pyside6/doc/gettingstarted/windows.rst b/sources/pyside6/doc/gettingstarted/windows.rst new file mode 100644 index 000000000..4451bb1fd --- /dev/null +++ b/sources/pyside6/doc/gettingstarted/windows.rst @@ -0,0 +1,114 @@ +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 |
