Qt for Python/GettingStarted: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Formatting)
 
(70 intermediate revisions by 13 users not shown)
Line 1: Line 1:
[[Category:Pythonic]]
[[Category:Qt for Python]]                                                                                                                              
== Considerations before starting ==
==Official documentation==


PySide2 supports Python 2 (recommended: 2.7 onwards, Compatibility module ''six'' installed) and Python 3 (recommended: 3.5 onwards).  
Refer to the [https://doc.qt.io/qtforpython/gettingstarted.html official docs] to start building and using Qt for Python.


On Windows, it is recommended to use Python 3 and build with MSVC2015. Python 2 requires building with MSVC2008.
==Using Qt Creator as a project explorer==                                      
 
Currently, only Qt 5.6 is supported. Qt needs to be build with the ''QtXmlPatterns'' module.
 
=== Development ===
 
Development happens in the dev branches of the [http://code.qt.io/cgit/pyside/pyside-setup.git/ repositories]. The top level repository has several submodules:
* sources/shiboken2: [http://code.qt.io/cgit/pyside/shiboken.git/ Shiboken Parser]
* sources/pyside2: [http://code.qt.io/cgit/pyside/pyside.git/ PySide 2]
* sources/pyside2-examples: [http://code.qt.io/cgit/pyside/examples.git/ Examples]
* sources/pyside2-tools: uic, rcc
* wiki: Wiki
 
Contributions follow the [[Qt_Project_Guidelines|standard process]].
 
Building requires [https://cmake.org/ CMake].
 
It is helpful to have debug binaries and/or symbols for Python available. On Windows, this is done choosing ''Customized Installation'' when installing python and ticking the respective check boxes. On Linux, debug packages can be installed in addition. For Ubuntu, the packages python3-dbg, libpython3-dbg provide a debug binary python3-dbg.
 
It is also recommended to use a [http://docs.python-guide.org/en/latest/dev/virtualenvs/ Virtual Environment] for testing to be able to always start from a clean base and avoid issues with write permissions in installations.
 
On Linux, the command
virtualenv -p /usr/bin/python3-dbg testenv
creates a Virtual Environment named ''testenv'' for debugging purposes. On Windows, an installation step may be required:
python -m pip install virtualenv
python -m virtualenv testenv
 
The Virtual Environment is activated by
  source testenv/bin/activate
or
CALL testenv\Scripts\activate.bat
 
Before building the first time, the  module [http://www.sphinx-doc.org/en/1.4.9/ Sphinx] should be installed into the virtual environment:
pip install sphinx
 
=== Building PySide2 ===
 
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.
 
Various ptions:
* --qmake=<binary> Path to ''qmake'' of the Qt library to be used
* --cmake=<binary> Path to ''cmake''
* --build-tests: Creates a directory containing the tests along with some helper packages
* --ignore-git: Prevents ''setup.py'' from cloning and checking out the submodules.
* --debug: Build in Debug mode
* --reuse-build: Rebuilds only modified files (currently does not work for typesystem xml files)
* --openssl: Path to OpenSSL
 
A typical invokation looks like:
setup.py install --build-tests
 
A successful build can be tested by running an example:
  python sources/pyside2-examples/examples/widgets/tetrix.py
 
Note: When local builds of Qt on Linux, the environment LD_LIBRARY_PATH needs to be set to point to the location of the Qt library when running examples, as otherwise they are not found by Python.
 
=== Running Test ===
 
Go to the build directory:
cd ~/pyside-setup/testenv_build/py3.5-qt5.6.3-64bit-release/pyside2/tests/QtGui
Run all tests in the module:
make test
Run only one test(qpainter_test):
ctest -R qpainter_test --verbose
 
=== Building the Documentation ===
 
This is currently unexplored terrain [https://bugreports.qt.io/browse/PYSIDE-363 PYSIDE-363].
* The sources are in pyside2/doc
* libXML2 and libXSLT should be present when building PySide2 (Ubuntu: apt-get install libxml2-dev libxslt1-dev)
* graphviz + dot should be installed
* QT_SRC_DIR needs to be set
* sphinx should be installed (pip install sphinx)
* qdoc3 is used to generate it
 
=== 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.
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.


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:                               


The steps for opening the projects in Qt Creator are:
#Open '''pyside-setup/sources/shiboken2/CMakeLists.txt''' and specify a 5.12+ Qt Kit to be used
# Open pyside-setup/sources/shiboken2/CMakeLists.txt, and specify a 5.6 Qt Kit to be used
#Build the project as usual (by pressing the '''build''' icon for instance)
# 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
# Open pyside-setup/sources/pyside2/CMakeLists.txt, and specify the same 5.6 Qt Kit
#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·
# 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.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
# An example path under MacOS is /Users/user/Dev/pyside2-setup/pyside_install/py2.7-qt5.6.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''')
# (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/qt56_source/include)
#Apply the CMake configuration changes (by pressing the button), and you should be able to build PySide
# 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==
                                                                                   
*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])
*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:


=== Build custom debug-enabled Python3 on Ubuntu ===
  python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
This is useful for debugging into the interpreter as well as into extensions.
Roughly the steps are the following:
  git clone https://github.com/python/cpython python3.6 && cd python3.6 && git checkout 3.6
sudo apt-get build-dep python3.5 # (at time of writing 3.6 was not packaged yet, but it doesn't matter, it's just build dependencies)
mkdir build_debug && cd build_debug
../configure --with-pydebug --enable-shared --prefix=/home/CHANGE_ME/python36_installed LDFLAGS="-Wl,--rpath=/home/CHANGE_ME/python36_installed/lib" # (you can modify the install path to any directory you swish, make sure to change it in the rpath setting as well)
make -j4 && make install
virtualenv -p /home/CHANGE_ME/python36_installed/bin/python3.6dm py36


After that you can build PySide2 using the custom Python interpreter, using the virtualenv you created in the last step. Make sure to change the paths to reflect your own directory structure.
*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>
cd /path/to/location/of/pyside/supermodule
dnf install graphviz.x86_64 #Fedora
python setup.py install --qmake=/home/CHANGE_ME/qt56/bin/qmake --cmake=/usr/bin/cmake --openssl=/usr/bin/openssl --debug --jobs=4 --ignore-git --build-tests
</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"