diff options
Diffstat (limited to 'sources/pyside6/doc/deployment/deployment-nuitka.rst')
-rw-r--r-- | sources/pyside6/doc/deployment/deployment-nuitka.rst | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/sources/pyside6/doc/deployment/deployment-nuitka.rst b/sources/pyside6/doc/deployment/deployment-nuitka.rst new file mode 100644 index 000000000..8b0afa56c --- /dev/null +++ b/sources/pyside6/doc/deployment/deployment-nuitka.rst @@ -0,0 +1,132 @@ +|project| & Nuitka +################## + +`Nuitka <https://nuitka.net/>`_ lets you compile your python application into a +stand-alone executable. Besides being a Python compiler which provides a fair +acceleration, it has the side-effect of acting as an installer as well. +Nuitka supports Linux, macOS and Windows. + +For more details, see the `official documentation <https://nuitka.net/pages/overview.html>`_. + +Preparation +=========== + +Install ``Nuitka`` via **pip** with the following command:: + + pip install nuitka + +After installation, the ``nuitka3`` binary is located in your virtual environment's ``bin/`` +directory, or where your Python executable is located. +Alternatively, you can also run:: + + python3 -m nuitka + +to achieve the same effect. + +Freeze an application +===================== + +``Nuitka`` has many options that you can use. To list them all, run ``nuitka3 -h``. + +To simply compile a project, you can run:: + + nuitka3 <programname> + +There are two main features: + +* the option to place it in a directory containing the libraries + (``--standalone``) +* the option to package the whole project (including shared libraries) into one executable file + (``--onefile``) + +If you use these options, you need to specify ``--plugin-enable=pyside6``. + +Run an example +-------------- + +Now, consider the following script, named ``hello.py``:: + + import sys + import random + from PySide6.QtWidgets import (QApplication, QLabel, QPushButton, + QVBoxLayout, QWidget) + from PySide6.QtCore import Slot, Qt + + class MyWidget(QWidget): + def __init__(self): + QWidget.__init__(self) + + self.hello = ["Hallo Welt", "你好,世界", "Hei maailma", + "Hola Mundo", "Привет мир"] + + self.button = QPushButton("Click me!") + self.text = QLabel("Hello World") + self.text.setAlignment(Qt.AlignCenter) + + self.layout = QVBoxLayout() + self.layout.addWidget(self.text) + self.layout.addWidget(self.button) + self.setLayout(self.layout) + + # Connecting the signal + self.button.clicked.connect(self.magic) + + @Slot() + def magic(self): + self.text.setText(random.choice(self.hello)) + + if __name__ == "__main__": + app = QApplication(sys.argv) + + widget = MyWidget() + widget.resize(800, 600) + widget.show() + + sys.exit(app.exec()) + +You don't have to copy this script. You find it as ``examples/installer_test/hello.py``. + +The command line to proceed looks like this:: + + nuitka3 examples/installer_test/hello.py + +This process creates an executable ``hello.bin`` and a directory hello.build that you +don't need. You can execute the binary directly. + +In order to create a bundle which can be copied onto a machine without any pre-existing +installation, run:: + + nuitka3 --standalone --plugin-enable=pyside6 examples/installer_test/hello.py + +This creates an application ``hello.dist/hello`` that contains everything needed to run. + +To run the application, go to ``hello.dist/`` and run the program:: + + cd hello.dist + ./hello + +Use the ``--onefile`` option if you prefer to have everything bundled into one executable, without +the shared libraries next to it. First you need to install:: + + pip install zstandard + +for data compression. Then you can run:: + + nuitka3 --onefile --plugin-enable=pyside6 examples/installer_test/hello.py + +This process takes a bit longer, but in the end you have one executable ``hello.bin``:: + + ./hello.bin + + +Some Caveats +============ + + +Nuitka issue on macOS +--------------------- + +Nuitka currently has a problem with the macOS bundle files on current macOS versions. +That has the effect that ``--standalone`` and ``--onefile`` create a crashing application. +Older versions which don't have the recent macOS API changes from 2020 will work. +We are currently trying to fix that problem. |