Tutorial 3 - Empaquetado para distribución¶

Hasta ahora, hemos estado ejecutando nuestra aplicación en "modo desarrollador". Esto hace que sea fácil para nosotros para ejecutar nuestra aplicación a nivel local - pero lo que realmente queremos es ser capaz de dar a nuestra aplicación a los demás.

Sin embargo, no queremos tener que enseñar a nuestros usuarios cómo instalar Python, crear un entorno virtual, clonar un repositorio git y ejecutar Briefcase en modo desarrollador. Preferimos simplemente darles un instalador, y que la aplicación simplemente funcione.

Briefcase puede utilizarse para empaquetar su aplicación y distribuirla de este modo.

Creación del andamiaje de aplicaciones¶

Dado que esta es la primera vez que empaquetamos nuestra aplicación, necesitamos crear algunos archivos de configuración y otros andamios para apoyar el proceso de empaquetado. Desde el directorio helloworld, ejecuta:

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

Errores sobre las versiones de Python

Si recibe un error que dice algo como:

La versión de Python que se utiliza para ejecutar Briefcase (3.12) no es la python3 del sistema (3.10).

Necesitarás recrear tu entorno virtual usando el sistema python3. Usar el sistema Python es un requisito para empaquetar tu aplicación.

(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

Probablemente acabas de ver pasar páginas de contenido en tu terminal… ¿qué acaba de pasar? Briefcase ha hecho lo siguiente:

Se generó una plantilla de aplicación. Hay un montón de archivos y configuraciones necesarias para construir un instalador nativo, por encima y más allá del código de su aplicación real. Este andamiaje extra es casi el mismo para cada aplicación en la misma plataforma, excepto por el nombre de la aplicación real que se está construyendo - por lo que Briefcase proporciona una plantilla de aplicación para cada plataforma que soporta. Este paso despliega la plantilla, sustituyendo el nombre de tu aplicación, el ID del paquete y otras propiedades de tu archivo de configuración según sea necesario para soportar la plataforma en la que estás construyendo. Si no está satisfecho con la plantilla proporcionada por Briefcase, puede proporcionar la suya propia. Sin embargo, probablemente no quieras hacer esto hasta que tengas un poco más de experiencia usando la plantilla por defecto de Briefcase.
Descargó e instaló un paquete de soporte**. El enfoque de empaquetado adoptado por Briefcase es mejor descrito como "la cosa más simple que podría funcionar" - envía un intérprete de Python completo y aislado como parte de cada aplicación que construye (excepto para las construcciones de paquetes de sistemas nativos de Linux). Esto es ligeramente ineficiente en cuanto a espacio - si tiene 5 aplicaciones empaquetadas con Briefcase, tendrá 5 copias del intérprete de Python. Sin embargo, este enfoque garantiza que cada aplicación es completamente independiente, utilizando una versión específica de Python que se sabe que funciona con la aplicación. De nuevo, Briefcase proporciona un paquete de soporte por defecto para cada plataforma; si lo desea, puede proporcionar su propio paquete de soporte, y hacer que ese paquete se incluya como parte del proceso de compilación. Es posible que desee hacer esto si tiene opciones particulares en el intérprete de Python que necesita tener habilitadas, o si desea eliminar módulos de la biblioteca estándar que no necesita en tiempo de ejecución. Briefcase mantiene una caché local de paquetes de soporte, por lo que una vez que haya descargado un paquete de soporte específico, esa copia en caché se utilizará en futuras compilaciones. Como se ha indicado anteriormente, cuando Briefcase empaqueta una aplicación como un paquete nativo del sistema Linux (el formato de paquete predeterminado para Linux), no se incluye un paquete de soporte con la aplicación. En su lugar, la aplicación utilizará el Python proporcionado por la distribución de Linux a la que se dirija.
Se instalan los requisitos de la aplicación. Tu aplicación puede especificar cualquier módulo de terceros que se requiera en tiempo de ejecución. Estos serán instalados usando pip en el instalador de tu aplicación.
Se instala el código de tu aplicación. Tu aplicación tendrá su propio código y recursos (por ejemplo, imágenes que se necesitan en tiempo de ejecución); estos archivos se copian en el instalador.
Por último, añade cualquier recurso adicional que necesite el propio instalador. Esto incluye cosas como iconos que deben adjuntarse a la aplicación final e imágenes de pantalla de bienvenida.

Una vez completado esto, si miras en el directorio del proyecto, deberías ver un directorio correspondiente a tu plataforma (macOS, linux, o windows) que contiene archivos adicionales. Esta es la configuración de empaquetado específica de la plataforma para tu aplicación.

Construir su aplicación¶

Ahora puede compilar su aplicación. Este paso realiza cualquier compilación binaria que sea necesaria para que su aplicación sea ejecutable en su plataforma de destino.

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

En macOS, el comando build no necesita compilar nada, pero sí necesita firmar el contenido del binario para que pueda ser ejecutado. Esta firma es una firma ad hoc - sólo funcionará en tu máquina; si quieres distribuir la aplicación a otros, necesitarás proporcionar una firma completa.

(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

Una vez completado este paso, la carpeta build contendrá una carpeta helloworld-0.0.1 que contiene una réplica de un sistema de archivos Linux /usr. Esta réplica del sistema de archivos contendrá una carpeta bin con un binario helloworld, además de las carpetas lib y share necesarias para soportar el binario.

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

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

En Windows, el comando build no necesita compilar nada, pero sí escribir algunos metadatos para que la aplicación sepa su nombre, versión, etc.

Activación del antivirus

Dado que estos metadatos se escriben directamente en el binario precompilado que se despliega desde la plantilla durante el comando create, esto puede activar el software antivirus que se ejecuta en su máquina e impedir que se escriban los metadatos. En ese caso, indique al antivirus que permita la ejecución de la herramienta (llamada rcedit-x64.exe) y vuelva a ejecutar el comando anterior.

Ejecutar la aplicación¶

Ahora puede utilizar Briefcase para ejecutar su aplicación:

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
---------------------------------------------------------------------------

Esto iniciará la ejecución de su aplicación nativa, utilizando la salida del comando build.

Es posible que notes algunas pequeñas diferencias en el aspecto de tu aplicación cuando se está ejecutando. Por ejemplo, los iconos y el nombre mostrados por el sistema operativo pueden ser ligeramente diferentes a los que veías cuando se ejecutaba en modo desarrollador. Esto también se debe a que estás utilizando la aplicación empaquetada, no sólo ejecutando código Python. Desde la perspectiva del sistema operativo, ahora estás ejecutando "una aplicación", no "un programa Python", y esto se refleja en cómo aparece la aplicación.

Antes de continuar, cierra la aplicación. Al igual que con los pasos anteriores del tutorial, puedes hacerlo pulsando el botón de cierre de la ventana de la aplicación, seleccionando Salir/Exit en el menú de la aplicación, o escribiendo Ctrl+C en el terminal donde ejecutaste briefcase run.

Creación del instalador¶

Ahora puedes empaquetar tu aplicación para su distribución, utilizando el comando package. El comando package realiza cualquier compilación necesaria para convertir el proyecto en un producto final y distribuible. Dependiendo de la plataforma, esto puede implicar compilar un instalador, realizar la firma de código, o hacer otras tareas previas a la distribución.

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

La carpeta dist contendrá un archivo llamado Hello World-0.0.1.dmg. Si localizas este archivo en el Finder y haces doble clic en su icono, montarás el DMG, lo que te proporcionará una copia de la aplicación Hello World y un enlace a tu carpeta Aplicaciones para facilitar la instalación. Arrastra el archivo de la aplicación a Aplicaciones, y habrás instalado tu aplicación. Envía el archivo DMG a un amigo y podrá hacer lo mismo.

En este ejemplo, hemos utilizado la opción --adhoc-sign - es decir, estamos firmando nuestra aplicación con credenciales ad hoc - credenciales temporales que sólo funcionarán en tu máquina. Hemos hecho esto para mantener el tutorial simple. Configurar identidades de firma de código es un poco complicado, y sólo son necesarias si pretendes distribuir tu aplicación a otros. Si estuviéramos publicando una aplicación real para que otros la usaran, necesitaríamos especificar credenciales reales.

Cuando esté listo para publicar una aplicación real, consulte la guía práctica de Briefcase sobre Cómo configurar una identidad de firma de código de macOS

La salida del paso paquete será ligeramente diferente dependiendo de su distribución de Linux. Si estás en una distribución derivada de Debian, verás:

(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

La carpeta dist contendrá el archivo .deb generado.

Si estás en una distribución basada en RHEL, lo verás:

(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

La carpeta dist contendrá el archivo .rpm generado.

Si estás en una distribución basada en Arch, lo verás:

(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

La carpeta dist contendrá el archivo .pkg.tar.zst generado.

Actualmente no es posible empaquetar otras distribuciones de Linux.

Si desea crear un paquete para una distribución de Linux distinta de la que está utilizando, Briefcase también puede ayudarle, pero tendrá que instalar Docker.

Existen instaladores oficiales de Docker Engine para diversas distribuciones de Unix. Siga las instrucciones para su plataforma; sin embargo, asegúrese de no instalar Docker en modo "sin raíz".

Una vez que hayas instalado Docker, deberías ser capaz de iniciar un contenedor Linux - por ejemplo:

$ docker run --rm -it ubuntu:22.04

te mostrará un prompt Unix (algo como root@84444e31cff9:/#) dentro de un contenedor Docker Ubuntu 22.04. Escribe Ctrl-D para salir de Docker y volver a tu shell local.

Una vez que tengas Docker instalado, puedes usar Briefcase para construir un paquete para cualquier distribución de Linux que soporte Briefcase pasando una imagen Docker como argumento. Por ejemplo, para construir un paquete DEB para Ubuntu 22.04 (Jammy), independientemente del sistema operativo en el que se encuentre, puede ejecutar:

$ briefcase package --target ubuntu:jammy

Esto descargará la imagen Docker para el sistema operativo seleccionado, creará un contenedor capaz de ejecutar las compilaciones de Briefcase y compilará el paquete de la aplicación dentro de la imagen. Una vez completado, la carpeta dist contendrá el paquete para la distribución Linux de destino.

(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

En este ejemplo, hemos utilizado la opción --adhoc-sign - es decir, estamos firmando nuestra aplicación con credenciales ad hoc - credenciales temporales que sólo funcionarán en tu máquina. Hemos hecho esto para mantener el tutorial simple. Configurar identidades de firma de código es un poco complicado, y sólo son necesarias si pretendes distribuir tu aplicación a otros. Si estuviéramos publicando una aplicación real para que otros la usaran, necesitaríamos especificar credenciales reales.

Cuando esté listo para publicar una aplicación real, consulte la guía práctica de Briefcase sobre Cómo configurar una identidad de firma de código de macOS

Una vez completado este paso, la carpeta dist contendrá un archivo llamado Hello_World-0.0.1.msi. Si haces doble clic en este instalador para ejecutarlo, deberías seguir el proceso de instalación de Windows que ya conoces. Una vez finalizada la instalación, aparecerá una entrada "Hello World" en el menú de inicio.

Siguientes pasos¶

Ya tenemos nuestra aplicación empaquetada para su distribución en plataformas de escritorio. Pero, ¿qué ocurre cuando necesitamos actualizar el código de nuestra aplicación? ¿Cómo introducimos esas actualizaciones en nuestra aplicación empaquetada? Vaya al Tutorial 4 para averiguarlo…