From 8b9ab12aa6b4f3c5e1e02529895770d63ae10b1b Mon Sep 17 00:00:00 2001 From: Jimmy Girardet Date: Sat, 27 Jun 2020 23:08:15 +0200 Subject: Doc: add briefcase deployment doc Change-Id: Id0d896330dabee3b5b01aea70f1f15a30797d466 Reviewed-by: Cristian Maureira-Fredes --- sources/pyside2/doc/deployment-briefcase.rst | 199 +++++++++++++++++++++++++++ sources/pyside2/doc/deployment.rst | 13 +- 2 files changed, 211 insertions(+), 1 deletion(-) create mode 100644 sources/pyside2/doc/deployment-briefcase.rst (limited to 'sources/pyside2/doc') diff --git a/sources/pyside2/doc/deployment-briefcase.rst b/sources/pyside2/doc/deployment-briefcase.rst new file mode 100644 index 000000000..fec5e0d56 --- /dev/null +++ b/sources/pyside2/doc/deployment-briefcase.rst @@ -0,0 +1,199 @@ +|project| & Briefcase +####################### + +`Briefcase `_ is a packaging tool that lets you create a standalone package for a Python application. It supports the following installer formats: + + * .app application bundle for macOS + * MSI installer for Windows + * AppImage for Linux + +For more details, see the `official documentation `_. + +Preparation +=========== + +Install `Briefcase` using the following **pip** command:: + + pip install briefcase + +You also need : docker on linux, `WixToolset`_ on windows, + +If you're using a virtual environment, remember to activate it before installing `Briefcase`. + +After installation, the `briefcase` binary is located in your virtual environment's `bin/` +directory, or where your Python executable is located. + +You can either create a brand new project using the briefcase assistant or setup your own. + +.. _`WixToolset`: https://wixtoolset.org/ + +Use Briefcase Assistant +======================= + +Run the following command and answer the questions to get started:: + + briefcase new + +Ensure that `PySide2` is chosen as the `GUI toolkit choice`. +Your PySide2 application is now configured. You can jump to `Build the package`_. + + +Set up your project +=================== + +Create a pyproject.toml +----------------------- + +At the root level of your project, create a `pyproject.toml` file:: + + [tool.briefcase] + project_name = "MyPySideApp" + bundle = "com.example" + version = "0.0.1" + url = "https://somwhere/on/the/net" + license = "GNU General Public License v3 (GPLv3)" + author = 'MyName Firstname' + author_email = "cool@mailexample.com" + + [tool.briefcase.app.mypysideapp] + formal_name = "A Cool App" + description = "The coolest app ever" + icon = "src/mypysideapp/resources/appicon" # Briecase will choose the right extension depending the os (png,ico,...) + sources = ['src/mypysideapp'] + requires = ['pyside2==5.15.0', + 'pony>=0.7.11,<0.8', + 'dickens==1.0.1', + 'Pillow==7.1.2', + 'mako==1.1.2', + 'beautifulsoup4'] + + + [tool.briefcase.app.mypysideapp.macOS] + requires = [] + + [tool.briefcase.app.mypysideapp.linux] + requires = [] + system_requires = [] + + [tool.briefcase.app.mypysideapp.windows] + requires = [] + + +Write some code +---------------- + +Let's say your project tree is like this:: + + pyproject.toml + setup.cfg + pytest.ini + src/ + + mypysideapp/ + resources/ + appicon.png + appicon.ico + __init__.py + __main__.py + app.py + + +Content of `__main__.py`:: + + import sys + from PySide2.QtWidgets import QApplication + from mypysideapp.app import MyWidget + + if __name__ == "__main__": + app = QApplication(sys.argv) + + widget = MyWidget() + widget.resize(800, 600) + widget.show() + + sys.exit(app.exec_()) + + +Content of `app.py`:: + + import random + from PySide2.QtWidgets import (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)) + + +Build the package +================== + +Initialize the package +------------------------ + +Just run:: + + briefcase create + +Run the following command to initialize the building the packages for Windows, Linux, and macOS. +It creates a subdirectory each for the different platforms. +This step takes longer as it adds the packages listed in `requires` sections in the `pyproject.toml` file. + +Build the application +--------------- +:: + + briefcase build + +You'll get:: + + macOS/A Cool App/A Cool App.app + or + linux/A Cool App-x86_64-0.0.1.AppImage + or + windows\A Cool App + + +Run the application +----------- +:: + + briefcase run + +.. note:: You can run your project in `dev` mode (your source code not packaged) with `briefcase dev` + + +Build the installer (only Windows and macOS) +--------------------------------------------- + +macOS:: + + briefcase package --no-sign + +It's possible to sign, see the `documentation `_. You get `macOS/A Cool App-0.0.1.dmg` + +Windows:: + + briefcase package + +You get `windows\A_Cool_App-0.0.1.msi` diff --git a/sources/pyside2/doc/deployment.rst b/sources/pyside2/doc/deployment.rst index 78d6058da..414a468ed 100644 --- a/sources/pyside2/doc/deployment.rst +++ b/sources/pyside2/doc/deployment.rst @@ -12,6 +12,7 @@ Here are a few distribution options that you can use: 1. Send a normal ZIP file with the application's content. 2. Build a proper `Python package (wheel) `_. 3. Freeze the application into a single binary file or directory. + 4. Provide native installer (msi, dmg) If you choose Option 3, consider using one of these tools: * `fbs`_ @@ -19,12 +20,14 @@ If you choose Option 3, consider using one of these tools: * `cx_Freeze`_ * `py2exe`_ * `py2app`_ + * `briefcase`_ .. _fbs: https://build-system.fman.io/ .. _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/ +.. _briefcase: https://briefcase.readthedocs.io Since |project| is a cross-platform framework, we focus on solutions for the three major platforms that Qt supports: Windows, Linux, and macOS. @@ -79,10 +82,17 @@ The following table summarizes the platform support for those packaging tools:

yes

no

+ +

briefcase

+

BSD3

+

yes

+

yes

+

yes

+ -Notice that only *fbs*, *cx_Freeze*, and *PyInstaller* meet our cross-platform requirement. +Notice that only *fbs*, *cx_Freeze*, *briefcase*, and *PyInstaller* meet our cross-platform requirement. Since these are command-line tools, you'll need special hooks or scripts to handle resources such as images, icons, and meta-information, before adding them to your package. Additionally, @@ -107,3 +117,4 @@ Here's a set of tutorials on how to use these tools: deployment-fbs.rst deployment-pyinstaller.rst deployment-cxfreeze.rst + deployment-briefcase.rst -- cgit v1.2.3