From 589f97d26dedb4d3da7debb2c238291df941315b Mon Sep 17 00:00:00 2001
From: Christian Tismer <tismer@stackless.com>
Date: Thu, 23 Sep 2021 16:28:41 +0200
Subject: Document the usage of Nuitka

This documentation is adapted from the document
deployment-pyinstaller.rst .

Task-number: PYSIDE-1523
Change-Id: I2f42d596ea1073158ff8c198ed01a5816c745d58
Reviewed-by: Christian Tismer <tismer@stackless.com>
---
 sources/pyside6/doc/deployment-nuitka.rst | 132 ++++++++++++++++++++++++++++++
 sources/pyside6/doc/deployment.rst        |  10 +++
 2 files changed, 142 insertions(+)
 create mode 100644 sources/pyside6/doc/deployment-nuitka.rst

diff --git a/sources/pyside6/doc/deployment-nuitka.rst b/sources/pyside6/doc/deployment-nuitka.rst
new file mode 100644
index 000000000..dff9aec97
--- /dev/null
+++ b/sources/pyside6/doc/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::
+
+    pip3 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::
+
+    pip3 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.
diff --git a/sources/pyside6/doc/deployment.rst b/sources/pyside6/doc/deployment.rst
index a294905a0..f8b22ae44 100644
--- a/sources/pyside6/doc/deployment.rst
+++ b/sources/pyside6/doc/deployment.rst
@@ -104,6 +104,15 @@ The following table summarizes the platform support for those packaging tools:
           <td><p style="color: green;">yes</p></td>
           <td><p style="color: green;">yes</p></td>
         </tr>
+        <tr>
+          <td><p>Nuitka</p></td>
+          <td><p>MIT</p></td>
+          <td><p style="color: green;">yes</p></td>
+          <td><p style="color: green;">yes</p></td>
+          <td><p style="color: green;">yes</p></td>
+          <td><p style="color: green;">yes</p></td>
+          <td><p style="color: green;">yes</p></td>
+        </tr>
       </tbody>
     </table>
 
@@ -134,3 +143,4 @@ Here's a set of tutorials on how to use these tools:
     deployment-cxfreeze.rst
     deployment-briefcase.rst
     deployment-py2exe.rst
+    deployment-nuitka.rst
-- 
cgit v1.2.3