Tutoriel 3 - Emballage pour la distribution¶

Jusqu'à présent, nous avons exécuté notre application en "mode développeur". Cela nous permet d'exécuter facilement notre application localement - mais ce que nous voulons vraiment, c'est pouvoir donner notre application à d'autres personnes.

Cependant, nous ne voulons pas avoir à apprendre à nos utilisateurs comment installer Python, créer un environnement virtuel, cloner un dépôt git, et lancer Briefcase en mode développeur. Nous préférons leur donner un programme d'installation et faire en sorte que l'application fonctionne tout simplement.

Briefcase peut être utilisé pour empaqueter votre application afin de la distribuer de cette manière.

Création de l'échafaudage de l'application¶

Puisque c'est la première fois que nous empaquetons notre application, nous devons créer quelques fichiers de configuration et autres échafaudages pour supporter le processus d'empaquetage. Depuis le répertoire helloworld, exécutez :

macOSLinuxWindows

(beeware-venv) $ briefcase create

[helloworld] Generating application template...
Using app template: https://github.com/beeware/briefcase-macOS-app-template.git, branch v0.3.18
...

[helloworld] Installing support package...
...

[helloworld] Installing application code...
Installing src/helloworld... done

[helloworld] Installing requirements...
...

[helloworld] Installing application resources...
...

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Created build/helloworld/macos/app

(beeware-venv) $ briefcase create

[helloworld] Finalizing application configuration...
Targeting ubuntu:jammy (Vendor base debian)
Determining glibc version... done
Targeting glibc 2.35
Targeting Python3.10

[helloworld] Generating application template...
Using app template: https://github.com/beeware/briefcase-linux-AppImage-template.git, branch v0.3.18
...

[helloworld] Installing support package...
No support package required.

[helloworld] Installing application code...
Installing src/helloworld... done

[helloworld] Installing requirements...
...

[helloworld] Installing application resources...
...

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Created build/helloworld/linux/ubuntu/jammy

Erreurs concernant les versions de Python

Si vous recevez un message d'erreur qui ressemble à quelque chose comme :

La version de Python utilisée pour faire fonctionner Briefcase (3.12) n'est pas la version système python3 (3.10).

Vous devrez recréer votre environnement virtuel en utilisant le système python3. L'utilisation du système Python est une condition nécessaire à l'empaquetage de votre application.

(beeware-venv) C:\...>briefcase create

[helloworld] Generating application template...
Using app template: https://github.com/beeware/briefcase-windows-app-template.git, branch v0.3.18
...

[helloworld] Installing support package...
...

[helloworld] Installing application code...
Installing src/helloworld... done

[helloworld] Installing requirements...
...

[helloworld] Installing application resources...
...

[helloworld] Created build\helloworld\windows\app

Vous venez probablement de voir défiler des pages de contenu dans votre terminal… que s'est-il passé ? Briefcase a fait ce qui suit :

Il génère un modèle d'application. Il y a beaucoup de fichiers et de configurations nécessaires pour construire un installateur natif, en plus du code de votre application réelle. Cet échafaudage supplémentaire est presque le même pour chaque application sur la même plateforme, à l'exception du nom de l'application réelle en cours de construction - Briefcase fournit donc un modèle d'application pour chaque plateforme qu'il supporte. Cette étape déploie le modèle, en substituant le nom de votre application, l'ID du bundle, et d'autres propriétés de votre fichier de configuration comme requis pour supporter la plateforme sur laquelle vous construisez. Si vous n'êtes pas satisfait du modèle fourni par Briefcase, vous pouvez fournir le vôtre. Cependant, vous ne voudrez probablement pas faire cela avant d'avoir un peu plus d'expérience dans l'utilisation du modèle par défaut de Briefcase.
Il a téléchargé et installé un paquetage de support. L'approche d'empaquetage adoptée par Briefcase est décrite comme "la chose la plus simple qui puisse fonctionner" - elle fournit un interpréteur Python complet et isolé dans le cadre de chaque application qu'elle construit (à l'exception des paquets du système natif de Linux). Cette approche est légèrement inefficace en termes d'espace - si vous avez 5 applications livrées avec Briefcase, vous aurez 5 copies de l'interpréteur Python. Cependant, cette approche garantit que chaque application est complètement indépendante, utilisant une version spécifique de Python connue pour fonctionner avec l'application. Encore une fois, Briefcase fournit un paquetage de support par défaut pour chaque plateforme ; si vous le souhaitez, vous pouvez fournir votre propre paquetage de support, et faire en sorte que ce paquetage soit inclus dans le processus de construction. Vous pouvez faire cela si vous avez des options particulières dans l'interpréteur Python que vous devez activer, ou si vous voulez retirer de la bibliothèque standard les modules dont vous n'avez pas besoin au moment de l'exécution. Briefcase maintient un cache local des paquets de support, donc une fois que vous avez téléchargé un paquet de support spécifique, cette copie en cache sera utilisée dans les futures versions. Comme indiqué ci-dessus, lorsque Briefcase compile une application en tant que paquetage système Linux natif (le format de paquetage par défaut pour Linux), un paquetage de support n'est pas inclus avec l'application. Au lieu de cela, l'application utilisera Python qui est fourni par la distribution de Linux ciblée.
Il installe les exigences de l'application. Votre application peut spécifier tous les modules tiers qui sont nécessaires à l'exécution. Ceux-ci seront installés en utilisant pip dans l'installeur de votre application.
Il installe le code de votre application. Votre application aura son propre code et ses propres ressources (par exemple, les images nécessaires à l'exécution) ; ces fichiers sont copiés dans le programme d'installation.
Il installe les ressources nécessaires à votre application. Enfin, il ajoute toutes les ressources supplémentaires nécessaires à l'installateur lui-même. Cela inclut des choses comme les icônes qui doivent être attachées à l'application finale et les images de l'écran d'accueil.

Une fois cette opération terminée, si vous regardez dans le répertoire du projet, vous devriez voir un répertoire correspondant à votre plateforme (macOS, linux, ou windows) qui contient des fichiers supplémentaires. C'est la configuration de l'empaquetage spécifique à la plate-forme pour votre application.

Construire votre application¶

Vous pouvez maintenant compiler votre application. Cette étape permet d'effectuer toute compilation binaire nécessaire pour que votre application soit exécutable sur votre plate-forme cible.

macOSLinuxWindows

(beeware-venv) $ briefcase build

[helloworld] Adhoc signing app...
...
Signing build/helloworld/macos/app/Hello World.app
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 00:07

[helloworld] Built build/helloworld/macos/app/Hello World.app

Sous macOS, la commande build n'a pas besoin de compiler quoi que ce soit, mais elle doit signer le contenu du binaire pour qu'il puisse être exécuté. Cette signature est une signature ad hoc - elle ne fonctionnera que sur votre machine ; si vous voulez distribuer l'application à d'autres, vous devrez fournir une signature complète.

(beeware-venv) $ briefcase build

[helloworld] Finalizing application configuration...
Targeting ubuntu:jammy (Vendor base debian)
Determining glibc version... done
Targeting glibc 2.35
Targeting Python3.10

[helloworld] Building application...
Build bootstrap binary...
make: Entering directory '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
...
make: Leaving directory '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
Building bootstrap binary... done
Installing license... done
Installing changelog... done
Installing man page... done
Updating file permissions... done
Stripping binary... done

[helloworld] Built build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/bin/helloworld

Une fois cette étape terminée, le dossier build contiendra un dossier helloworld-0.0.1 qui contient un miroir du système de fichiers Linux /usr. Ce miroir du système de fichiers contiendra un dossier bin avec un binaire helloworld, ainsi que les dossiers lib et share nécessaires pour supporter le binaire.

(beeware-venv) C:\...>briefcase build
Setting stub app details... done

[helloworld] Built build\helloworld\windows\app\src\Hello World.exe

Sous Windows, la commande build n'a pas besoin de compiler quoi que ce soit, mais elle doit écrire quelques métadonnées pour que l'application connaisse son nom, sa version, et ainsi de suite.

Déclenchement de l'antivirus

Puisque ces métadonnées sont écrites directement dans le binaire précompilé déployé à partir du modèle pendant la commande create, cela peut déclencher un logiciel antivirus fonctionnant sur votre machine et empêcher les métadonnées d'être écrites. Dans ce cas, demandez à l'antivirus d'autoriser l'outil (nommé rcedit-x64.exe) à s'exécuter et relancez la commande ci-dessus.

Exécution de l'application¶

Vous pouvez maintenant utiliser Briefcase pour exécuter votre application :

macOSLinuxWindows

(beeware-venv) $ briefcase run

[helloworld] Starting app...
===========================================================================
Configuring isolated Python...
Pre-initializing Python runtime...
PythonHome: /Users/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/support/python-stdlib
PYTHONPATH:
- /Users/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/support/python311.zip
- /Users/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/support/python-stdlib
- /Users/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/support/python-stdlib/lib-dynload
- /Users/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/app_packages
- /Users/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/app
Configure argc/argv...
Initializing Python runtime...
Installing Python NSLog handler...
Running app module: helloworld
---------------------------------------------------------------------------

(beeware-venv) $ briefcase run

[helloworld] Finalizing application configuration...
Targeting ubuntu:jammy (Vendor base debian)
Determining glibc version... done
Targeting glibc 2.35
Targeting Python3.10

[helloworld] Starting app...
===========================================================================
Install path: /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr
Pre-initializing Python runtime...
PYTHONPATH:
- /usr/lib/python3.10
- /usr/lib/python3.10/lib-dynload
- /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/lib/helloworld/app
- /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/lib/helloworld/app_packages
Configure argc/argv...
Initializing Python runtime...
Running app module: helloworld
---------------------------------------------------------------------------

(beeware-venv) C:\...>briefcase run

[helloworld] Starting app...

===========================================================================
Log started: 2023-04-23 04:47:45Z
PreInitializing Python runtime...
PythonHome: C:\Users\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src
PYTHONPATH:
- C:\Users\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src\python39.zip
- C:\Users\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src
- C:\Users\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src\app_packages
- C:\Users\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src\app
Configure argc/argv...
Initializing Python runtime...
Running app module: helloworld
---------------------------------------------------------------------------

Ceci lancera l'exécution de votre application native, en utilisant la sortie de la commande build.

Il se peut que vous remarquiez de petites différences dans l'apparence de votre application lorsqu'elle est en cours d'exécution. Par exemple, les icônes et le nom affichés par le système d'exploitation peuvent être légèrement différents de ceux que vous avez vus lors de l'exécution en mode développeur. Cela s'explique également par le fait que vous utilisez l'application packagée et que vous ne vous contentez pas d'exécuter du code Python. Du point de vue du système d'exploitation, vous exécutez maintenant "une application" et non "un programme Python", ce qui se reflète dans l'apparence de l'application.

Avant de continuer, fermez l'application. Comme pour les étapes précédentes du tutoriel, vous pouvez le faire en appuyant sur le bouton de fermeture de la fenêtre de l'application, en sélectionnant Quit/Exit dans le menu de l'application, ou en tapant Ctrl+C dans le terminal où vous avez exécuté briefcase run.

Construction du programme d'installation¶

Vous pouvez maintenant empaqueter votre application pour la distribuer, en utilisant la commande package. La commande package effectue toutes les compilations nécessaires pour convertir le projet d'échafaudage en un produit final distribuable. Selon la plateforme, cela peut impliquer la compilation d'un installateur, la signature du code, ou d'autres tâches de pré-distribution.

macOSLinuxWindows

(beeware-venv) $ briefcase package --adhoc-sign

[helloworld] Signing app...

*************************************************************************
** WARNING: Signing with an ad-hoc identity                            **
*************************************************************************

    This app is being signed with an ad-hoc identity. The resulting
    app will run on this computer, but will not run on anyone else's
    computer.

    To generate an app that can be distributed to others, you must
    obtain an application distribution certificate from Apple, and
    select the developer identity associated with that certificate
    when running 'briefcase package'.

*************************************************************************

Signing app with ad-hoc identity...
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 00:07

[helloworld] Building DMG...
Building dist/Hello World-0.0.1.dmg

[helloworld] Packaged dist/Hello World-0.0.1.dmg

Le dossier dist contiendra un fichier nommé Hello World-0.0.1.dmg. Si vous localisez ce fichier dans le Finder, et que vous double-cliquez sur son icône, vous monterez le DMG, ce qui vous donnera une copie de l'application Hello World, et un lien vers votre dossier Applications pour faciliter l'installation. Faites glisser le fichier de l'application dans Applications, et vous aurez installé votre application. Envoyez le fichier DMG à un ami, qui devrait pouvoir faire de même.

Dans cet exemple, nous avons utilisé l'option --adhoc-sign - c'est-à-dire que nous signons notre application avec des informations d'identification ad hoc - des informations d'identification temporaires qui ne fonctionneront que sur votre machine. Nous avons fait cela pour que le tutoriel reste simple. La mise en place d'identités de signature de code est un peu fastidieuse, et elles ne sont nécessaires que si vous avez l'intention de distribuer votre application à d'autres personnes. Si nous publiions une application réelle pour que d'autres puissent l'utiliser, nous devrions spécifier de vraies informations d'identification.

Lorsque vous êtes prêt à publier une application réelle, consultez le guide Briefcase How-To sur Setting up a macOS code signing identity.

Le résultat de l'étape du paquetage sera légèrement différent selon votre distribution Linux. Si vous êtes sur une distribution dérivée de Debian, vous verrez :

(beeware-venv) $ briefcase package

[helloworld] Finalizing application configuration...
Targeting ubuntu:jammy (Vendor base debian)
Determining glibc version... done
Targeting glibc 2.35
Targeting Python3.10

[helloworld] Building .deb package...
Write Debian package control file... done

dpkg-deb: building package 'helloworld' in 'helloworld-0.0.1.deb'.
Building Debian package... done

[helloworld] Packaged dist/helloworld_0.0.1-1~ubuntu-jammy_amd64.deb

Le dossier dist contiendra le fichier .deb qui a été généré.

Si vous utilisez une distribution basée sur RHEL, vous verrez :

(beeware-venv) $ briefcase package

[helloworld] Finalizing application configuration...
Targeting fedora:40 (Vendor base rhel)
Determining glibc version... done
Targeting glibc 2.39
Targeting Python3.12

[helloworld] Building .rpm package...
Generating rpmbuild layout... done

Write RPM spec file... done

Building source archive... done

Executing(%prep): /bin/sh -e /var/tmp/rpm-tmp.Kav9H7
+ umask 022
...
+ exit 0
Building RPM package... done

[helloworld] Packaged dist/helloworld-0.0.1-1.fc40.x86_64.rpm

Le dossier dist contiendra le fichier .rpm qui a été généré.

Si vous êtes sur une distribution basée sur Arch, vous verrez :

(beeware-venv) $ briefcase package

[helloworld] Finalizing application configuration...
Targeting arch:20240101 (Vendor base arch)
Determining glibc version... done
Targeting glibc 2.38
Targeting Python3.12

[helloworld] Building .pkg.tar.zst package...
...
Building Arch package... done

[helloworld] Packaged dist/helloworld-0.0.1-1-x86_64.pkg.tar.zst

Le dossier dist contiendra le fichier .pkg.tar.zst qui a été généré.

Les autres distributions Linux ne sont actuellement pas prises en charge pour l'empaquetage.

Si vous souhaitez créer un paquet pour une distribution Linux autre que celle que vous utilisez, Briefcase peut également vous aider - mais vous devrez installer Docker.

Des installateurs officiels pour Docker Engine sont disponibles pour une série de distributions Unix. Suivez les instructions correspondant à votre plate-forme, mais assurez-vous de ne pas installer Docker en mode "sans racine".

Une fois que vous avez installé Docker, vous devriez être en mesure de démarrer un conteneur Linux - par exemple :

$ docker run --rm -it ubuntu:22.04

vous montrera une invite Unix (quelque chose comme root@84444e31cff9:/#) à l'intérieur d'un conteneur Docker Ubuntu 22.04. Tapez Ctrl-D pour quitter Docker et revenir à votre shell local.

Une fois que vous avez installé Docker, vous pouvez utiliser Briefcase pour construire un paquet pour n'importe quelle distribution Linux que Briefcase supporte en passant une image Docker comme argument. Par exemple, pour construire un paquet DEB pour Ubuntu 22.04 (Jammy), quel que soit le système d'exploitation sur lequel vous êtes, vous pouvez exécuter :

$ briefcase package --target ubuntu:jammy

Ceci téléchargera l'image Docker pour le système d'exploitation choisi, créera un conteneur capable d'exécuter les builds de Briefcase, et construira le paquetage de l'application à l'intérieur de l'image. Une fois terminé, le dossier dist contiendra le paquet pour la distribution Linux cible.

(beeware-venv) C:\...>briefcase package

*************************************************************************
** WARNING: No signing identity provided                               **
*************************************************************************

    Briefcase will not sign the app. To provide a signing identity,
    use the `--identity` option; or, to explicitly disable signing,
    use `--adhoc-sign`.

*************************************************************************

[helloworld] Building MSI...
Compiling application manifest...
Compiling... done

Compiling application installer...
helloworld.wxs
helloworld-manifest.wxs
Compiling... done

Linking application installer...
Linking... done

[helloworld] Packaged dist\Hello_World-0.0.1.msi

Dans cet exemple, nous ne signons pas notre application. En conséquence, quand vous installez l'application, vous recevez un avertissement système signalant qu'elle provient d'un développeur inconnu. Nous avons fait cela pour que le tutoriel reste simple. La mise en place d'identités de signature de code est un peu fastidieuse, et elles ne sont nécessaires que si vous avez l'intention de distribuer votre application à d'autres personnes. Si nous publiions une application réelle pour que d'autres puissent l'utiliser, nous devrions spécifier de vraies informations d'identification ; quand une application signée est installée, le système informe l'utilisateur que l'application provient de l'entité connue associée au certificat.

Lorsque vous êtes prêt à publier une application réelle, consultez le guide Briefcase How-To sur Setting up a Windows code signing identity.

Une fois cette étape terminée, le dossier dist contiendra un fichier nommé Hello_World-0.0.1.msi. Si vous double-cliquez sur ce programme d'installation pour le lancer, vous devriez passer par un processus d'installation Windows familier. Une fois l'installation terminée, il y aura une entrée "Hello World" dans votre menu de démarrage.

Étapes suivantes¶

Notre application est désormais prête à être distribuée sur les plates-formes de bureau. Mais que se passe-t-il lorsque nous devons mettre à jour le code de notre application ? Comment intégrer ces mises à jour dans notre application packagée ? Consultez le Tutoriel 4 pour le découvrir…