diff options
Diffstat (limited to 'sources/pyside2')
-rw-r--r-- | sources/pyside2/doc/contents.rst | 1 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-cxfreeze.rst | 130 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-fbs.rst | 106 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment-pyinstaller.rst | 124 | ||||
-rw-r--r-- | sources/pyside2/doc/deployment.rst | 70 |
5 files changed, 431 insertions, 0 deletions
diff --git a/sources/pyside2/doc/contents.rst b/sources/pyside2/doc/contents.rst index 645f461e5..464f6e1da 100644 --- a/sources/pyside2/doc/contents.rst +++ b/sources/pyside2/doc/contents.rst @@ -8,6 +8,7 @@ faq.rst gettingstarted.rst tutorials/index.rst + deployment.rst pysideapi2.rst pysideversion.rst licenses.rst diff --git a/sources/pyside2/doc/deployment-cxfreeze.rst b/sources/pyside2/doc/deployment-cxfreeze.rst new file mode 100644 index 000000000..40b65621b --- /dev/null +++ b/sources/pyside2/doc/deployment-cxfreeze.rst @@ -0,0 +1,130 @@ +===================== +|project| & cx_Freeze +===================== + +`cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_ allows you to freeze your Python +application into executables. +The supported platforms are Linux, macOS, Windows, FreeBSD, among others. + + +You can read the `official documentation <https://cx-freeze.readthedocs.io/en/latest/index.html>`_ +to clarify any further question, and remember to contribute to +the project by `filing issues <https://sourceforge.net/projects/cx-freeze/>`_ +if you find any, or contributing to `their development <https://bitbucket.org/anthony_tuininga/cx_freeze/src>`_. + +Preparation +=========== + +Installing `cx_Freeze` can be done via **pip**:: + + pip install cx_freeze + +If you are using a virtual environment, remember to activate it before +installing `cx_Freeze` into it. + +After the installation, you will have the `cxfreeze` binary to deploy +your application. + +Freezing an application +======================= + +There are three options to work with `cx_Freeze`: + + 1. Using the `cxfreeze` script. + 2. Creating `setup.py` script to build the project. + 3. Using the module classes directly (for advanced purposes). + +We will cover the first two uses cases. + +Creating an example +------------------- + +Now, consider the following simple script, named `hello.py`:: + + import sys + import random + from PySide2.QtWidgets import (QApplication, QLabel, QPushButton, + QVBoxLayout, QWidget) + from PySide2.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_()) + + +Using `cxfreeze` executable +--------------------------- + +The command line to proceed will look like this:: + + cxfreeze hello.py + +This command will create a `dist/` directory that will contain the +executable and a `lib/` directory including all the shared libraries. + +To launch the application, you need to just go to the `dist/` directory +and execute the file:: + + cd dist/ + ./main + + +Using a setuptools script +------------------------- + +For this process, you will need an additional script called `setup.py`:: + + import sys + from cx_Freeze import setup, Executable + + setup(name = "MyApp", + version = "0.1", + description = "My GUI App", + executables = [Executable("hello.py")]) + +After that, you need to build the project using it:: + + python setup.py build + +This step will create a `build/` directory with the following structure:: + + build + └── exe.linux-x86_64-3.7 + └── lib + └── main + +The first directory inside `build/` will depend on the platform +you are using, in this case a `x86_64` Linux using Python 3.7. +The structure is the same as previously described, and you can simply +enter the directory and execute the file:: + + cd build/exe.linux-x86_64-3.7 + ./main diff --git a/sources/pyside2/doc/deployment-fbs.rst b/sources/pyside2/doc/deployment-fbs.rst new file mode 100644 index 000000000..94c52a08b --- /dev/null +++ b/sources/pyside2/doc/deployment-fbs.rst @@ -0,0 +1,106 @@ +=============== +|project| & fbs +=============== + +`fbs <https://build-system.fman.io>`_ provides a powerful environment for packaging, +creating installers, and signing your application, but also for managing the application's updates. +Since it is based on PyInstaller, it currently supports Linux, macOS, and Windows. + +You can read the `official tutorial <https://github.com/mherrmann/fbs-tutorial>`_ for more +details on how to use `fbs`, or check the +`documentation <https://build-system.fman.io/manual/>`_ for a complete set of features and +options. + +Preparation +=========== + +Installing `fbs` can be done via **pip**:: + + pip install fbs pyinstaller==3.4 + +If you are using a virtual environment, remember to activate it before +installing it. + +After the installation, you will be able to use the `fbs` executable. + +Starting a new project +====================== + +`fbs` provides nice features that allow you to create a base +project structure by executing the following command:: + + fbs startproject + +This process will prompt you to answer many questions to configure the details +of your project, like: + + * Application name + * Author name + * Qt bindings (PySide2 or PyQt5) + * Bundle indentified (for macOS) + +After the process finishes, you will have a `src/` directory that +will contain the following structure:: + + └── src + ├── build + │ └── settings + └── main + ├── icons + │ ├── base + │ ├── linux + │ └── mac + └── python + +Inside the `settings` directory you can find a couple of `json` files +that you can edit to include more information about your project. + +The main file will be under the `python` directory, and its content by default is:: + + from fbs_runtime.application_context import ApplicationContext + from PySide2.QtWidgets import QMainWindow + + import sys + + class AppContext(ApplicationContext): # 1. Subclass ApplicationContext + def run(self): # 2. Implement run() + window = QMainWindow() + version = self.build_settings['version'] + window.setWindowTitle("MyApp v" + version) + window.resize(250, 150) + window.show() + return self.app.exec_() # 3. End run() with this line + + if __name__ == '__main__': + appctxt = AppContext() # 4. Instantiate the subclass + exit_code = appctxt.run() # 5. Invoke run() + sys.exit(exit_code) + +The example will show an empty `QMainWindow`, and you can execute it by running:: + + fbs run + +Freezing the application +======================== + +Once you verify that the application is properly working, +you can continue with the freezing process:: + + fbs freeze + +After the process finishes, you will get a message stating the location +of your executable, e.g.:: + + Done. You can now run `target/MyApp/MyApp`. If that doesn't work, see + https://build-system.fman.io/troubleshooting. + + +Then executing the application will result in the same window +you saw with the `fbs run` command:: + + cd target/MyApp/ + ./MyApp + +.. note:: This is the case for Linux. For other platforms like macOS, you will need to + enter the directory: `target/MyApp.app/Contents/MacOS`, and for + Windows you will find a `MyApp.exe` executable. diff --git a/sources/pyside2/doc/deployment-pyinstaller.rst b/sources/pyside2/doc/deployment-pyinstaller.rst new file mode 100644 index 000000000..8e6a76052 --- /dev/null +++ b/sources/pyside2/doc/deployment-pyinstaller.rst @@ -0,0 +1,124 @@ +======================= +|project| & PyInstaller +======================= + +`PyInstaller <https://www.pyinstaller.org/>`_ allows you to freeze your python +application into a stand-alone executable. +The supported platforms are Linux, macOS, Windows, FreeBSD, and others. + +One of the main goals of `PyInstaller` is to be compatible with 3rd-party +Python modules, e.g.: |pymodname|. + +You can read the `official documentation <https://www.pyinstaller.org/documentation.html>`_ +to clarify any further question, and remember to contribute to +`the project <https://github.com/pyinstaller/pyinstaller>`_ +by filing issues if you find any, or contributing to their development. + +Preparation +=========== + +Installing `PyInstaller` can be done via **pip**:: + + pip install pyinstaller + +If you are using a virtual environment, remember to activate it before +installing `PyInstaller` into it. + +After the installation, the `pyinstaller` binary will be located in the `bin/` +directory of your virtual environment, or where your Python executable is located. + +If that directory is not in your `PATH`, you need to include the whole path +when executing `pyinstaller`. + +.. warning:: If you already have PySide2 or Shiboken2 installed in your system, PyInstaller will pick them + instead of your virtual environment ones. + +Freezing an application +======================= + +`PyInstaller` has many options that you can use. +To learn more about them you can just run `pyinstaller -h`. + +Two main features are the option to package the whole project +(including the shared libraries) into one executable file (`--onefile`), +and to prepare a directory that will contain +an executable next to all the used libraries. + +Additionally, for Windows you can enable opening a console during the +execution with the option `-c` (or equivalent `--console` or `--nowindowed`). +Further, you can specify to not open such console window +on macOS and Windows with the option `-w` (or equivalent `--windowed` or `--noconsole`). + +Creating an example +------------------- + +Now, consider the following simple script, named `hello.py`:: + + import sys + import random + from PySide2.QtWidgets import (QApplication, QLabel, QPushButton, + QVBoxLayout, QWidget) + from PySide2.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_()) + + +Since it has a UI, we will use the `--windowed` option. + +The command line to proceed will look like this:: + + pyinstaller --name="MyApplication" --windowed hello.py + +This process will create a `dist/` and `build/` directory. +The executable and all the shared libraries required by your application +will be placed inside `dist/MyApplication`. + +To execute the frozen application you can go inside `dist/MyApplication` and +execute the program:: + + cd dist/MyApplication/ + ./MyApplication + +.. note:: The directory inside `dist/` and the executable will have the same name. + +If you prefer to have everything bundled into one executable, i.e.: +no shared libraries next to the executable, you can use the option +`--onefile`:: + + pyinstaller --name="MyApplication" --windowed --onefile hello.py + +This process will take a bit longer, but in the end you will discover +an executable inside the `dist/` directory that you can execute:: + + cd dist/ + ./MyApplication diff --git a/sources/pyside2/doc/deployment.rst b/sources/pyside2/doc/deployment.rst new file mode 100644 index 000000000..582e38992 --- /dev/null +++ b/sources/pyside2/doc/deployment.rst @@ -0,0 +1,70 @@ +========== +Deployment +========== + +Deploying or freezing an application is a crucial part of many Python projects. +Most large projects are not based on a single Python file, so +the distribution of these applications becomes more difficult. + +The options for a project are: + 1. Sending a normal zip-file with the application's content. + 2. Building a proper `Python package (wheel) <https://packaging.python.org/>`_. + 3. Freezing the application in a single binary file, or into a directory. + +For the **third** option, there are many available tools: + * `PyInstaller <https://www.pyinstaller.org/>`_, + * `cx_Freeze <https://anthony-tuininga.github.io/cx_Freeze/>`_, + * `py2exe <http://www.py2exe.org/>`_, + * `py2app <https://py2app.readthedocs.io/en/latest/>`_, + +Since |project| is a cross-platform framework, +we would like to focus on solutions that at least work on +the three major platform supported by Qt: Linux, macOS, and Windows. + +The following table summarizes the above mentioned tools support: + +=========== ======= ===== ===== ======= +Name License Linux macOS Windows +=========== ======= ===== ===== ======= +py2exe MIT no no yes +py2app MIT no yes no +cx_Freeze MIT yes yes yes +PyInstaller GPL yes yes yes +=========== ======= ===== ===== ======= + +From the table we can see that only *cx_Freeze* and *PyInstaller* +meet our requirements. + +All tools are command-line based, and it could become +a hard task to include more resources to your application, such as +images, icons, and meta-information, because you will need to create +special hooks or separate scripts to handle them. +Additionally, since this only +allows you to freeze your current application, you don't have +any mechanism to update your application. + +To cover the update part, there is a tool built around PyInstaller +called `PyUpdater <https://www.pyupdater.org/>`_ which enables +a simple mechanism to ship applications updates. + +On top of all these features, including also a nice interface +that allows the user to install the application step by step, +or even better, provide templates to create new projects to easily +freeze-them-up is something really beneficial for both developers +and end-users. +This is where `fbs <https://build-system.fman.io>`_ enters the +game, being based on PyInstaller, but including all the nice features +we previously mentioned. + +Here you can find a set of tutorials on how to use the previously +described tools. + +.. note:: Deployment is possible only in Qt for Python 5.12.2 + +.. toctree:: + :name: mastertoc + :maxdepth: 2 + + deployment-pyinstaller.rst + deployment-cxfreeze.rst + deployment-fbs.rst |