Difference between revisions of "Qt for Python/GettingStarted"

From Qt Wiki
Jump to: navigation, search
m
(Formatting of main wiki)
Line 1: Line 1:
 
[[Category:PySide]]                                                                   
 
[[Category:PySide]]                                                                   
 
                                                                                      
 
                                                                                      
== Install PySide2 ==                                                              
+
== Getting Started ==                                                                                                                                                  
                                                                                   
 
 
You can install PySide2 by building the source package yourself.                     
 
You can install PySide2 by building the source package yourself.                     
 
                                                                                      
 
                                                                                      
 
After clonning the official repository you must follow the instructions for           
 
After clonning the official repository you must follow the instructions for           
your specific system.                                                              
+
your specific system.                                                                                                                                                  
                                                                                   
+
=== Platform Requirements ===                                                                                                                                          
=== Platform Requirements ===                                                      
+
* '''Python''':                                                                         
                                                                                   
+
** Python 3 (version >= 3.5 recommended) and Python 2 (version >= 2.7 recommended).
'''Python''':                                                                         
+
* '''Qt''':                                                                               
* PySide2 supports Python 2 (version >= 2.7 recommended) and Python 3 (version >= 2.5 recommended).
+
** 5.6 onward are supported, but 5.9 (recommended).
'''Qt''':                                                                               
+
* '''CLANG''':                                                                           
* Currently, Qt 5.6 and Qt 5.9 onwards are supported (Qt needs to be built with the ''QtXmlPatterns'' module).
+
** The Clang library (C-bindings), version 3.9 or higher is required for building.
* Note that the branch of the [https://code.qt.io/cgit/pyside/pyside-setup.git pyside-setup] repository must match that of the Qt version used.
+
** Prebuilt versions of it can be downloaded from [http://download.qt.io/development_releases/prebuilt/libclang/ download.qt.io].
* PySide versions following 5.6 (so 5.9 and dev) use a C++ parser based on [http://clang.org/ Clang]).·
+
* '''CMake''':                                                                           
'''CLANG''':                                                                           
+
** Required by the building system.                                               
* The Clang library (C-bindings), version 3.9 or higher is required for building.
+
=== Building PySide2 ===                                                                                       
* Prebuilt versions of it can be downloaded from [http://download.qt.io/development_releases/prebuilt/libclang/ download.qt.io].
+
The building processes are covered in the platform pages.                                                                                                              
'''CMake''':                                                                           
 
* Required by the building system.                                               
 
                                                                                   
 
The building processes are covered in the platform pages.                          
 
                                                                                   
 
 
* [[PySide2_Windows|Windows]]                                                           
 
* [[PySide2_Windows|Windows]]                                                           
 
* [[PySide2_X11|Linux/X11]]                                                       
 
* [[PySide2_X11|Linux/X11]]                                                       
* [[PySide2_MacOS| macOS]]
+
* [[PySide2_MacOS| macOS]]                                                                                  
                                                                                   
+
==== setup.py build script ====                                                                                                                                        
==== 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 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:                                                                 
 
The main options are:                                                                 
* --qmake=<binary> Path to ''qmake'' of the Qt library to be used                     
+
* ''--qmake=BIN'': Path to ''qmake'' of the Qt library to be used                     
* --cmake=<binary> Path to ''cmake''                                                 
+
* ''--cmake=BIN'': Path to ''cmake''                                                 
* --build-tests: Creates a directory containing the tests along with some helper packages
+
* ''--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.·  
+
* ''--ignore-git'': Prevents ''setup.py'' from cloning and checking out the submodules.·  
* --debug: Build in Debug mode                                                       
+
* ''--debug'': Build in Debug mode                                                       
* --reuse-build: Rebuilds only modified files (currently does not work for typesystem xml files)
+
* ''--reuse-build'': Rebuilds only modified files (currently does not work for typesystem xml files)
* --openssl: Path to OpenSSL                                                        
+
* ''--openssl=BIN'': Path to OpenSSL's binary
* --jobs : Number of threads to use when building                                  
+
* ''--jobs=#'': Number of # threads to use when building                                                                                                                        
                                                                                   
 
 
A typical invocation looks like:                                                     
 
A typical invocation looks like:                                                     
> python setup.py install --build-tests --jobs=4                                    
+
python setup.py install --build-tests --jobs=4                                                                                                                      
                                                                                   
 
 
A successful build can be tested by running an example:                               
 
A successful build can be tested by running an example:                               
python sources/pyside2-examples/examples/widgets/widgets/tetrix.py              
+
  python sources/examples/widgets/widgets/tetrix.py                                                                                                
                                                                                   
 
 
You can search for working examples by typing                                         
 
You can search for working examples by typing                                         
   cd sources/pyside2-examples                                                         
+
   cd sources/examples                                                         
   git grep "PySide2 port"                                                          
+
   git grep "PySide2 port"                                                                                
                                                                                   
 
Note: When doing 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. On macOS you will need to set either the DYLD_LIBRARY_PATH or DYLD_FRAMEWORK_PATH environment variables.
 
                                                                                   
 
 
=== Running Tests ===                                                                 
 
=== Running Tests ===                                                                 
                                                                                   
+
To perform all the available tests, just execute:                                                                                   
  python testrunner.py test  > testlog.txt                                          
+
  python testrunner.py test  > testlog.txt                                                                                                                            
                                                                                   
+
Run only one test(qpainter_test):                                                                                                                                    
Run only one test(qpainter_test):                                                  
+
  ctest -R qpainter_test --verbose                                                                                                                                        
                                                                                   
 
  ctest -R qpainter_test --verbose                                                  
 
                                                                                   
 
 
=== Building the Documentation ===                                                   
 
=== Building the Documentation ===                                                   
 
                                                                                      
 
                                                                                      
Line 70: Line 52:
 
* QT_SRC_DIR needs to be set                                                         
 
* QT_SRC_DIR needs to be set                                                         
 
* sphinx should be installed (pip install sphinx)                                     
 
* sphinx should be installed (pip install sphinx)                                     
* qdoc3 is used to generate it                                                      
+
* qdoc3 is used to generate it                                                                                                                                                                                                            
                                                                                   
 
                                                                                   
 
 
=== Using Qt Creator as a project explorer ===                                       
 
=== 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.
Line 89: Line 69:
 
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 ===                                                               
+
== Troubleshooting ==                                                               
 
                                                                                      
 
                                                                                      
 
* PySide2 5.9 does not work with OpenSSL 1.1                                         
 
* PySide2 5.9 does not work with OpenSSL 1.1                                         
It is necessary to have OpenSSL 1.0.x to work around Qt and PySide v5.9, since there are compatibility issues with newer versions of OpenSSL ([https://wiki.openssl.org/index.php/OpenSSL_1.1.0_Changes#Qt see details])
+
**It is necessary to have OpenSSL 1.0.x to work around Qt and PySide v5.9, 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.
 +
* Missing libraries when trying examples
 +
** When doing 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. On macOS you will need to set either the DYLD_LIBRARY_PATH or DYLD_FRAMEWORK_PATH environment variables.

Revision as of 10:32, 29 January 2018


Getting Started

You can install PySide2 by building the source package yourself.

After clonning the official repository you must follow the instructions for your specific system.

Platform Requirements

  • Python:
    • Python 3 (version >= 3.5 recommended) and Python 2 (version >= 2.7 recommended).
  • Qt:
    • 5.6 onward are supported, but 5.9 (recommended).
  • CLANG:
    • The Clang library (C-bindings), version 3.9 or higher is required for building.
    • Prebuilt versions of it can be downloaded from download.qt.io.
  • CMake:
    • Required by the building system.

Building PySide2

The building processes are covered in the platform pages.

setup.py build script

The script setup.py in the 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=BIN: Path to qmake of the Qt library to be used
  • --cmake=BIN: 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=BIN: Path to OpenSSL's binary
  • --jobs=#: Number of # threads to use when building

A typical invocation looks like:

python setup.py install --build-tests --jobs=4                                                                                                                       

A successful build can be tested by running an example:

 python sources/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                                                                                                                             

Run only one test(qpainter_test):

ctest -R qpainter_test --verbose                                                                                                                                         

Building the Documentation

This is currently unexplored terrain 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.

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.6 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.6 Qt Kit
  4. 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·
  5. 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
  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/qt56_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

  • PySide2 5.9 does not work with OpenSSL 1.1
    • It is necessary to have OpenSSL 1.0.x to work around Qt and PySide v5.9, 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.
  • Missing libraries when trying examples
    • When doing 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. On macOS you will need to set either the DYLD_LIBRARY_PATH or DYLD_FRAMEWORK_PATH environment variables.