|project| Getting Started
==========================

This page is focused on building |project| from source, if you just want to install |pymodname|
with ``pip`` you need to run::

    pip install pyside2

for more details, refer to our `Quick Start`_ guide. Additionally, you can
check the `FAQ`_ related to the project.

.. _Quick Start: quickstart.html
.. _FAQ: faq.html

General Requirements
--------------------

 * **Python**: 3.5+ and 2.7
 * **Qt:** 5.12+ is recommended
 * **libclang:** The libclang library, recommended: version 6 for PySide2 5.12.
   Prebuilt versions of it can be `downloaded here`_.
 * **CMake:** 3.1+ is needed.

.. _downloaded here: http://download.qt.io/development_releases/prebuilt/libclang/

Guides per platform
-------------------

You can refer to the following pages for platform specific instructions:

 * `Windows`_
 * `macOS`_
 * `Linux`_
 * Mobile platforms (iOS/Android) **(no support)**
 * Embedded platforms **(no official support)**

   .. note:: Most Linux-based embedded OS provide PySide2 with their official
             package manager (e.g. `Raspbian`_ and `ArchlinuxARM`_).

.. _Windows: gettingstarted-windows.html
.. _macOS: gettingstarted-macOS.html
.. _Linux: gettingstarted-linux.html
.. _Raspbian: https://www.raspbian.org/
.. _ArchlinuxARM: https://archlinuxarm.org/

A normal building command will look like this::

    python setup.py install --qmake=/path/to/qmake \
                            --ignore-git \
                            --debug \
                            --build-tests \
                            --parallel=8 \
                            --make-spec=ninja \
                            --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 QtCore, QtGUI
and QtWidgets.

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.

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 qmake in your path
   (``set PATH=E:\Path\to\Qt\5.14\msvc2017_64\bin;%PATH%``)

You can also run a specific test (for example ``qpainter_test``) by running::

    ctest -R qpainter_test --verbose

Building the documentation
---------------------------

The documentation is being generated using **qdoc** to get the API information, and also **sphinx**
for the local Python related notes.

The system required ``libxml2`` and ``libxslt``, also on the Python environment, ``sphinx`` and
``graphviz`` need to be installed before running the installation process::

    pip install graphviz sphinx

After installing ``graphviz``, the ``dot`` command needs to be in PATH, otherwise,
the process will fail. Installing ``graphviz`` system-wide is also an option.

Since the process rely on a Qt installation, you need to specify where the ``qtbase`` directory
you will use with your ``qmake`` is located::

    export QT_SRC_DIR=/path/to/qtbase

Once the build process finishes, you can go to the generated ``*_build/*_release/pyside2``
directory, and run::

    make apidoc

Finally, you will get a ``html`` directory containing all the generated documentation.

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 5.14.1 -v v5.14.0..5.14 -t bug-fix

* ``debug_windows.py``: This script can be used to find out why PySide2 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 ``ldd`` / ``LD_DEBUG``.

  Underneath it uses the ``cdb.exe`` command line debugger, and the ``gflags.exe`` tool, both
  installed with the latest Windows Kit.

  The aim is to ask users to run this script when they encounter PySide2 imports not working 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 PySide2 and PyQt5
  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 5.14.1 -w all

  Please keep in mind we rely on BeautifulSoup_ to parse the content, so you will be to install
  it besides PySide2 and PyQt5 (Including additional modules like DataVisualiztion, QtCharts,
  WebEngine, etc).


.. _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/
