Qt for Python/GettingStarted: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(Formatting)
 
(10 intermediate revisions by 5 users not shown)
Line 1: Line 1:
[[Category:Qt for Python]]                                                                                                                                 
[[Category:Qt for Python]]                                                                                                                                 
== Getting Started ==                                                                                                                                                  
==Official documentation==
You can install PySide2 via [https://pypi.org/project/PySide2/ PyPi], using [https://download.qt.io/official_releases/QtForPython/ Qt-servers] or by building the source package yourself.                   
                                                                                   
After cloning the official repository you must follow the instructions for         
your specific system.                                                                                                                                                   
=== Platform Requirements ===                                                                                                                                         
* '''Python''':                                                                       
** Python 3.5+ and Python 2.7
*** (Please notice there is a known issue with Python 3.6.0, [https://wiki.qt.io/Qt_for_Python/Considerations read more].)
* '''Qt''':                                                                             
** 5.11 is recommended
* '''libclang''':                                                                         
** The libclang library (C-bindings), version 5.0 or higher is required for building starting from the PySide2 5.11 branch onwards (recommended: version 6 for PySide2 5.12).
** Prebuilt versions of it can be downloaded from [http://download.qt.io/development_releases/prebuilt/libclang/ download.qt.io].
* '''CMake (version >= 3.1 required) ''':                                                                         
** The build system required by for building PySide2.


=== Pre-built Wheels ===
Refer to the [https://doc.qt.io/qtforpython/gettingstarted.html official docs] to start building and using Qt for Python.


Official release wheels of Qt For Python can be installed regularly via pip:
==Using Qt Creator as a project explorer==                                      
 
Qt Creator 4.0+ can be used to open the PySide and Shiboken CMakeLists.txt files as projects, and thus provide usual IDE features for developing PySide - project file navigation, code completion (C++ only), following symbols under cursor (C++ only), syntax highlighting, locator usage, debugging, etc.
pip install pyside2
 
Pre-release (snapshot) wheels containing the latest code changes are available at http://download.qt.io/snapshots/ci/pyside/
 
For example you can install the latest 5.11 snapshot wheel using:
 
pip install --index-url=http://download.qt.io/snapshots/ci/pyside/5.11/latest/ pyside2 --trusted-host download.qt.io
 
=== Building PySide2 ===                                                                                       
The building processes are covered in the platform pages.                                                                                                              
* [[Qt_for_Python_GettingStarted/Windows|Windows]]
* [[Qt_for_Python_GettingStarted/X11|Linux/X11]]                                                     
* [[Qt_for_Python_GettingStarted/MacOS|macOS]]
* Mobile platforms are currently not supported (iOS, Android)
==== setup.py build script ====                                                                                                                                         
The script ''setup.py'' in the [http://code.qt.io/cgit/pyside/pyside-setup.git/ top level repository] is used to build and install the PySide2 package. It takes a mode argument (''build'' or ''install'') and several options (more options are documented in setup.py itself).·                                                                                   
The main options are:                                                               
* ''--qmake=/path/to/qmake'': Path to ''qmake'' of the Qt library to be used                   
* ''--cmake=/path/to/cmake'': Path to ''cmake'' binary                                               
* ''--build-tests'': Builds tests along with some helper packages
* ''--ignore-git'': Prevents ''setup.py'' from cloning and checking out the git submodules.
* ''--debug'': Build in Debug mode (some restrictions apply to Windows, see [[Qt_for_Python_GettingStarted/Windows#Build_considerations|Build considerations]])
* ''--reuse-build'': Rebuilds only modified files
* ''--openssl=C:\Dev\qtdev\OpenSSL-Win64\bin'': Path to OpenSSL's bindir which contains dlls (Only required for Windows PySide2 packages)
* ''--j / parallel #'' : Number of # processes to use when building
* ''--standalone'': Copies over the Qt libraries (and other library dependencies) into the PySide2 package to make it work on other machines (on Windows all builds are standalone, even without specifying the command line argument).
* ''--verbose'': Prints all compiler invocations when building the package.
 
A typical invocation looks like:                                                   
python setup.py install --build-tests --j 4                                                                                                                     
A successful build can be tested by running an example:                             
  python examples/widgets/widgets/tetrix.py                                                                                                 
You can search for working examples by typing                                       
  cd sources/examples                                                       
  git grep "PySide2 port"
 
=== Running Tests ===                                                               
To perform all the available tests, just execute:                                                                                   
python testrunner.py test  > testlog.txt
 
Note that to successfully run the tests on Windows you need to point the PATH environment variable to the Qt libdir:
set PATH=E:\Qt\5.11\msvc2015_64\bin;%PATH%
 
Run only one test(qpainter_test):                                                                                                                                     
ctest -R qpainter_test --verbose
 
=== Building the Documentation ===                                                 
                                                                                      
                                                                                      
This is currently possible on Linux and macOS hosts only. Before you build pyside2, ensure that the following requirements are met, to be able to build documentation:
Currently, there is a limitation that Shiboken has to be built first using the terminal because the installed shiboken CMake packages will have to be specified for the PySide project in Qt Creator.
* Install libXML2 and libXSLT before building PySide2 (Ubuntu: apt-get install libxml2-dev libxslt1-dev)
* Set QT_SRC_DIR with the path to qtbase, if you don't want to build documentation based on the Qt sources under <QT_PKG_ROOT>/<QT_VERSION>/Src/qtbase.
* Install graphviz (including dot) and sphinx (pip install graphviz sphinx)


Once your pyside2 is built, navigate to the ''*_build/*_release/pyside2'' directory and run: <syntaxhighlight>
The steps for opening the projects in Qt Creator are:                               
make apidoc
</syntaxhighlight>
 
The build first runs qdoc on the Qt sources in $QT_SRC_DIR to generate the webxml files, which are then parsed by shiboken to
generate reStructuredText files. In the final step, sphinx is run on the rst files to generate HTMLs.
 
You could also use the ''docrsts'' make target to generate only the reStructuredText files.


=== Using Qt Creator as a project explorer ===                                     
#Open '''pyside-setup/sources/shiboken2/CMakeLists.txt''' and specify a 5.12+ Qt Kit to be used
Qt Creator 4.0+ can be used to open the PySide and Shiboken CMakeLists.txt files as projects, and thus provide usual IDE features for developing PySide - project file navigation, code completion (C++ only), following symbols under cursor (C++ only), syntax highlighting, locator usage, debugging, etc.
#Build the project as usual (by pressing the '''build''' icon for instance)
                                                                                   
#Open '''pyside-setup/sources/pyside2/CMakeLists.txt''' and specify the same 5.12+ Qt Kit
Currently there is a limitation that Shiboken has to be built first using the terminal, because the installed shiboken CMake packages will have to be specified for the PySide project in Qt Creator.
#Go to the projects tab, and under the Build / CMake section find the Shiboken2_DIR setting. You have to specify the path to the folder where the Shiboken CMake package was installed when you compiled Shiboken from the terminal·
                                                                                   
#An example path under macOS is '''/Users/user/Dev/pyside2-setup/pyside_install/py3.6-qt5.12.1-64bit-debug/lib/cmake/Shiboken2-2.0.0'''. The path has to be adjusted depending on the user folder name, the version of python and qt, etc
The steps for opening the projects in Qt Creator are:                               
#(Optional) On MacOS you also have to set the '''ALTERNATIVE_QT_INCLUDE_DIR''' setting to the Qt kit include path (e.g. '''/Users/user/Dev/qt511_source/include''')
# Open pyside-setup/sources/shiboken2/CMakeLists.txt, and specify a 5.11 Qt Kit to be used
#Apply the CMake configuration changes (by pressing the button), and you should be able to build PySide
# Build the project as usual (by pressing the build icon for instance)              
# Open pyside-setup/sources/pyside2/CMakeLists.txt, and specify the same 5.11 Qt Kit
# Go to projects tab, and under the Build / CMake section find the Shiboken2_DIR setting. You have to specify the path to the folder where the Shiboken CMake package was installed when you compiled Shiboken from the terminal·
# An example path under MacOS is /Users/user/Dev/pyside2-setup/pyside_install/py3.6-qt5.11.1-64bit-debug/lib/cmake/Shiboken2-2.0.0. The path has to be adjusted depending on the user folder name, the version of python and qt, etc
# (Optional) On MacOS you also have to set the ALTERNATIVE_QT_INCLUDE_DIR setting to the Qt kit include path (e.g. /Users/user/Dev/qt511_source/include)                                                                                                                                                                                                                                                                                                                                  
# Apply the CMake configuration changes (by pressing the button), and you should be able to build PySide
                                                                                      
                                                                                      
Now you can use the project explorer to look through the source cpp files, python files, use the locator feature to open files and file classes / methods, and other features that Qt Creator provides.
Now you can use the project explorer to look through the source cpp files, python files, use the locator feature to open files and file classes / methods, and other features that Qt Creator provides.


== Troubleshooting / Known Issues ==
==Troubleshooting / Known Issues==
                                                                                      
                                                                                      
* Qt 5.9 does not work with OpenSSL 1.1                                         
*Qt 5.9 does not work with OpenSSL 1.1                                         
** When doing a custom Qt build (some unspecified versions for now), It is necessary to have an OpenSSL version of 1.0.x, since there are compatibility issues with newer versions of OpenSSL ([https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes#Qt see details])
**When doing a custom Qt build (some unspecified versions for now), It is necessary to have an OpenSSL version of 1.0.x, since there are compatibility issues with newer versions of OpenSSL ([https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes#Qt see details])
* PySide2 looks at the system installation if the local Qt version does not have a required module
*PySide2 looks at the system installation if the local Qt version does not have a required module
**The only workaround is to uninstall any module from the system, then PySide2 can look at only the Qt path currently being use.
**The only workaround is to uninstall any module from the system, then PySide2 can look at only the Qt path currently being use.
* Qt packages that directly link to OpenSSL (as opposed to runtime discovery) are not currently supported.
*Qt packages that directly link to OpenSSL (as opposed to runtime discovery) are not currently supported.
* Make sure that the Python environment location where the PySide2 package will be installed is writable (otherwise you might get various permission denied errors). The install location can be found with 99% probability by running:
*Make sure that the Python environment location where the PySide2 package will be installed is writable (otherwise you might get various permission denied errors). The install location can be found with 99% probability by running:
 
  python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
  python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
*Building failing because graphviz wasn't found. If you're using pyenv and installed it using pip, try to install it using your package manager:<syntaxhighlight>
dnf install graphviz.x86_64 #Fedora
</syntaxhighlight>
*20220727 Urgent update: If you build PySide with a custom built Python, you should build python with the following options: <syntaxhighlight lang="shell">
PYTHON_CONFIGURE_OPTS="--enable-shared --with-trace-refs"
</syntaxhighlight>For example:<syntaxhighlight lang="shell">
PYTHON_CONFIGURE_OPTS="--enable-shared --with-trace-refs" pyenv install -kg 3.9.13
</syntaxhighlight>This makes PySide2 work without the limited API. <br />

Latest revision as of 14:08, 27 July 2022

Official documentation

Refer to the official docs to start building and using Qt for Python.

Using Qt Creator as a project explorer

Qt Creator 4.0+ can be used to open the PySide and Shiboken CMakeLists.txt files as projects, and thus provide usual IDE features for developing PySide - project file navigation, code completion (C++ only), following symbols under cursor (C++ only), syntax highlighting, locator usage, debugging, etc.

Currently, there is a limitation that Shiboken has to be built first using the terminal because the installed shiboken CMake packages will have to be specified for the PySide project in Qt Creator.

The steps for opening the projects in Qt Creator are:

  1. Open pyside-setup/sources/shiboken2/CMakeLists.txt and specify a 5.12+ Qt Kit to be used
  2. Build the project as usual (by pressing the build icon for instance)
  3. Open pyside-setup/sources/pyside2/CMakeLists.txt and specify the same 5.12+ Qt Kit
  4. Go to the projects tab, and under the Build / CMake section find the Shiboken2_DIR setting. You have to specify the path to the folder where the Shiboken CMake package was installed when you compiled Shiboken from the terminal·
  5. An example path under macOS is /Users/user/Dev/pyside2-setup/pyside_install/py3.6-qt5.12.1-64bit-debug/lib/cmake/Shiboken2-2.0.0. The path has to be adjusted depending on the user folder name, the version of python and qt, etc
  6. (Optional) On MacOS you also have to set the ALTERNATIVE_QT_INCLUDE_DIR setting to the Qt kit include path (e.g. /Users/user/Dev/qt511_source/include)
  7. Apply the CMake configuration changes (by pressing the button), and you should be able to build PySide

Now you can use the project explorer to look through the source cpp files, python files, use the locator feature to open files and file classes / methods, and other features that Qt Creator provides.

Troubleshooting / Known Issues

  • Qt 5.9 does not work with OpenSSL 1.1
    • When doing a custom Qt build (some unspecified versions for now), It is necessary to have an OpenSSL version of 1.0.x, since there are compatibility issues with newer versions of OpenSSL (see details)
  • PySide2 looks at the system installation if the local Qt version does not have a required module
    • The only workaround is to uninstall any module from the system, then PySide2 can look at only the Qt path currently being use.
  • Qt packages that directly link to OpenSSL (as opposed to runtime discovery) are not currently supported.
  • Make sure that the Python environment location where the PySide2 package will be installed is writable (otherwise you might get various permission denied errors). The install location can be found with 99% probability by running:
python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
  • Building failing because graphviz wasn't found. If you're using pyenv and installed it using pip, try to install it using your package manager:
    dnf install graphviz.x86_64 #Fedora
  • 20220727 Urgent update: If you build PySide with a custom built Python, you should build python with the following options: 
    PYTHON_CONFIGURE_OPTS="--enable-shared --with-trace-refs"
    For example:
    PYTHON_CONFIGURE_OPTS="--enable-shared --with-trace-refs" pyenv install -kg 3.9.13
    This makes PySide2 work without the limited API.
Retrieved from "https://wiki.qt.io/index.php?title=Qt_for_Python/GettingStarted&oldid=39702"