1|project| Getting Started 2========================== 3 4This page is focused on building |project| from source, if you just want to install |pymodname| 5with ``pip`` you need to run:: 6 7 pip install pyside2 8 9for more details, refer to our `Quick Start`_ guide. Additionally, you can 10check the :ref:`FAQ <faq>` related to the project. 11 12.. _Quick Start: quickstart.html 13 14General Requirements 15-------------------- 16 17 * **Python**: 3.5+ and 2.7 18 * **Qt:** 5.12+ is recommended 19 * **libclang:** The libclang library, recommended: version 10 for PySide2 5.15. 20 Prebuilt versions of it can be `downloaded here`_. 21 * **CMake:** 3.1+ is needed. 22 23.. _downloaded here: http://download.qt.io/development_releases/prebuilt/libclang/ 24 25Guides per platform 26------------------- 27 28You can refer to the following pages for platform specific instructions: 29 30 * `Windows`_ 31 * `macOS`_ 32 * `Linux`_ 33 * Mobile platforms (iOS/Android) **(no support)** 34 * Embedded platforms **(no official support)** 35 36 .. note:: Most Linux-based embedded OS provide PySide2 with their official 37 package manager (e.g. `Raspbian`_ and `ArchlinuxARM`_). 38 39.. _Windows: gettingstarted-windows.html 40.. _macOS: gettingstarted-macOS.html 41.. _Linux: gettingstarted-linux.html 42.. _Raspbian: https://www.raspbian.org/ 43.. _ArchlinuxARM: https://archlinuxarm.org/ 44 45A normal building command will look like this:: 46 47 python setup.py install --qmake=/path/to/qmake \ 48 --ignore-git \ 49 --debug \ 50 --build-tests \ 51 --parallel=8 \ 52 --make-spec=ninja \ 53 --verbose-build \ 54 --module-subset=Core,Gui,Widgets 55 56Which will build and install the project with **debug** symbols, including the **tests**, 57using **ninja** (instead of make), and considering only the **module subset** of QtCore, QtGUI 58and QtWidgets. 59 60Other important options to consider are: 61 * ``--cmake``, to specify the path to the cmake binary, 62 * ``--reuse-build``, to rebuild only the modified files, 63 * ``--openssl=/path/to/openssl/bin``, to use a different path for OpenSSL, 64 * ``--standalone``, to copy over the Qt libraries into the final package 65 to make it work on other machines, 66 * ``--doc-build-online``, to build documentation using the online template. 67 68Testing the installation 69------------------------ 70 71Once the installation finishes, you will be able to execute any of our examples:: 72 73 python examples/widgets/widgets/tetrix.py 74 75Running Tests 76------------- 77 78Using the ``--build-tests`` option will enable us to run all the auto tests inside the project:: 79 80 python testrunner.py test > testlog.txt 81 82.. note:: On Windows, don't forget to have qmake in your path 83 (``set PATH=E:\Path\to\Qt\5.15\msvc2017_64\bin;%PATH%``) 84 85You can also run a specific test (for example ``qpainter_test``) by running:: 86 87 ctest -R qpainter_test --verbose 88 89Building the documentation 90-------------------------- 91 92Starting from 5.15, there are two options to build the documentation: 93 941. Building rst-only documentation (no API) 95~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 96 97The process of parsing Qt headers to generate the PySide API documentation can take several 98minutes, this means that modifying a specific section of the rst files we currently have, might 99become a hard task. 100 101For this, you can install ``sphinx`` on a virtual environment, and execute the following command:: 102 103 python setup.py build_rst_docs 104 105which will generate a ``html/`` directory with the following structure:: 106 107 html 108 └── pyside2 109 ├── index.html 110 ├── ... 111 └── shiboken2 112 ├── index.html 113 └── ... 114 115so you can open the main page ``html/pyside2/index.html`` on your browser to check the generated 116files. 117 118This is useful when updating the general sections of the documentation, adding tutorials, 119modifying the build instructions, and more. 120 1212. Building the documentation (rst + API) 122~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 123 124The documentation is being generated using **qdoc** to get the API information, and also **sphinx** 125for the local Python related notes. 126 127The system required ``libxml2`` and ``libxslt``, also on the Python environment, ``sphinx`` and 128``graphviz`` need to be installed before running the installation process:: 129 130 pip install graphviz sphinx 131 132After installing ``graphviz``, the ``dot`` command needs to be in PATH, otherwise, 133the process will fail. Installing ``graphviz`` system-wide is also an option. 134 135Since the process rely on a Qt installation, you need to specify where the ``qtbase`` directory 136you will use with your ``qmake`` is located:: 137 138 export QT_SRC_DIR=/path/to/qtbase 139 140Once the build process finishes, you can go to the generated ``*_build/*_release/pyside2`` 141directory, and run:: 142 143 make apidoc 144 145.. note:: The ``apidoc`` make target builds offline documenation in QCH (Qt Creator Help) format 146 by default. You can switch to building for the online use with the ``--doc-build-online`` 147 configure option. 148 149Finally, you will get a ``html`` directory containing all the generated documentation. The offline 150help files, ``PySide.qch`` and ``Shiboken.qch``, can be moved to any directory of your choice. You 151can find ``Shiboken.qch`` in the build directory, ``*_build\*_release\shiboken2\doc\html``. 152 153Viewing offline documentation 154~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 155 156The offline documentation (QCH) can be viewed using the Qt Creator IDE or Qt Assistant, which is 157a standalone application for viewing QCH files. 158 159To view the QCH using Qt Creator, following the instructions outlined in 160`Using Qt Creator Help Mode <https://doc.qt.io/qtcreator/creator-help.html>`_. If you chose to 161use Qt Assistant instead, use the following command to register the QCH file before launching 162Qt Assistant: 163 164 assistant -register PySide.qch 165 166.. note:: Qt Assistant renders the QCH content using the QTextBrowser backend, which supports 167 a subset of the CSS styles, However, Qt Creator offers an alternative litehtml-based 168 backend, which offers better browsing experience. At the moment, this is not the default 169 backend, so you have to select the litehtml backend 170 explicitly under the ``General`` tab in ``Qt Creator >> Tools >> Options >> Help``. 171 172Using the internal tools 173------------------------ 174 175A set of tools can be found under the ``tools/`` directory inside the ``pyside-setup`` repository. 176 177* ``checklibs.py``: Script to analyze dynamic library dependencies of Mach-O binaries. 178 To use this utility, just run:: 179 180 python checklibs.py /path/to/some.app/Contents/MacOS/Some 181 182 This script was fetched from this repository_. 183 184* ``create_changelog.py``: Script used to create the CHANGELOG that you can find in the ``dist/`` 185 directory. Usage:: 186 187 python create_changelog.py -r 5.15.1 -v v5.15.0..5.15 -t bug-fix 188 189* ``debug_windows.py``: This script can be used to find out why PySide2 modules 190 fail to load with various DLL errors like Missing DLL or Missing symbol in DLL. 191 192 You can think of it as a Windows version of ``ldd`` / ``LD_DEBUG``. 193 194 Underneath it uses the ``cdb.exe`` command line debugger, and the ``gflags.exe`` tool, both 195 installed with the latest Windows Kit. 196 197 The aim is to ask users to run this script when they encounter PySide2 imports not working on 198 Windows. The user should then provide the generated log file. 199 200 Incidentally it can also be used for any Windows executables, not just Python. 201 To use it just run:: 202 203 python debug_windows.py 204 205* ``missing_bindings.py``: This script is used to compare the state of PySide2 and PyQt5 206 regarding available modules and classses. This content is displayed in our `wiki page`_, 207 and can be used as follows:: 208 209 python missing_bindings.py --qt-version 5.15.1 -w all 210 211 Please keep in mind we rely on BeautifulSoup_ to parse the content, so you will be to install 212 it besides PySide2 and PyQt5 (Including additional modules like DataVisualiztion, QtCharts, 213 WebEngine, etc). 214 215 216.. _repository: https://github.com/liyanage/macosx-shell-scripts/ 217.. _`wiki page`: https://wiki.qt.io/Qt_for_Python_Missing_Bindings 218.. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/ 219