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 Portafolio en modo desarrollador. Preferimos simplemente darles un instalador, y que la aplicación simplemente funcione.

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

Creación del andamiaje de la aplicación¶

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

macOSLinuxWindows

(beeware-venv) $ briefcase create

[helloworld] Generando plantilla de aplicación...
Usando la plantilla de aplicación: https://github.com/beeware/briefcase-macOS-app-template.git, rama v0.3.18
...

[helloworld] Instalando el paquete de soporte...
...

[helloworld] Instalando el código de la aplicación...
Instalando src/helloworld... hecho

[helloworld] Instalando requisitos...
...

[helloworld] Instalando recursos de la aplicación...
...

[helloworld] Eliminando contenido innecesario de la aplicación...
Eliminando contenido innecesario del paquete de la aplicación... hecho

[helloworld] Creado build/helloworld/macos/app

(beeware-venv) $ briefcase create

[helloworld] Finalizando la configuración de la aplicación...
Seleccionando ubuntu:jammy (base Debian del proveedor)
Determinando la versión de glibc... hecho
Seleccionando glibc 2.35
Seleccionando Python 3.10

[helloworld] Generando la plantilla de la aplicación...
Usando la plantilla de aplicación: https://github.com/beeware/briefcase-linux-AppImage-template.git, rama v0.3.18
...

[helloworld] Instalando el paquete de soporte...
No se requiere ningún paquete de soporte.

[helloworld] Instalando el código de la aplicación...
Instalando src/helloworld... hecho

[helloworld] Instalando requisitos...
...

[helloworld] Instalando recursos de la aplicación...
...

[helloworld] Eliminando contenido innecesario de la aplicación...
Eliminando contenido innecesario del paquete de la aplicación... hecho

[helloworld] Creado 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 Portafolio (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] Generando plantilla de aplicación...
Usando la plantilla de aplicación: https://github.com/beeware/briefcase-windows-app-template.git, rama v0.3.18
...

[helloworld] Instalando el paquete de soporte...
...

[helloworld] Instalando el código de la aplicación...
Instalando src/helloworld... hecho

[helloworld] Instalando los requisitos...
...

[helloworld] Instalando los recursos de la aplicación...
...

[helloworld] Creado build\helloworld\windows\app

Probablemente acabas de ver páginas de contenido devueltas 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 (p.ej. imágenes que se necesitan en tiempo de ejecución); estos archivos son copiados al instalador.
Instaló los recursos necesarios para tu aplicación.. 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 este proceso, si miras en el directorio build 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. Por ejemplo, en macOS, tu directorio de proyecto ahora incluirá:

helloworld/
└── build/
    └── helloworld/
 └── macos/

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] Aplicación de firma ad hoc...
...
Firmando build/helloworld/macos/app/Hello World.app
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100,0 % • 00:07

[helloworld] Compilado 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] Finalizando la configuración de la aplicación...
Seleccionando ubuntu:jammy (base Debian del proveedor)
Determinando la versión de glibc... hecho
Seleccionando glibc 2.35
Seleccionando Python 3.10

[helloworld] Compilando la aplicación...
Compilando el binario de arranque...
make: Entrando en el directorio '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
...
make: Saliendo del directorio '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
Compilando el binario de arranque... hecho
Instalando la licencia... hecho
Instalando el registro de cambios... hecho
Instalando la página de manual... hecho
Actualizando los permisos de los archivos... hecho
Desmontando el binario... hecho

[helloworld] Compilado 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 mantener el binario.

(beeware-venv) C:\...>briefcase build
Configurando los detalles de la aplicación de prueba... hecho

[helloworld] Se ha compilado 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 pre‐compilado 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 tu aplicación¶

Ahora puede utilizar Briefcase para ejecutar tu aplicación:

macOSLinuxWindows

(beeware-venv) $ briefcase run

[helloworld] Iniciando la aplicación...
===========================================================================
Configurando Python aislado...
Preinicializando el entorno de ejecución de Python...
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
- /Usuarios/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/support/python-stdlib/lib-dynload
- /Usuarios/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contents/Resources/app_packages
- /Usuarios/brutus/beeware-tutorial/helloworld/macOS/app/Hello World/Hello World.app/Contenido/Recursos/app
Configurando argc/argv...
Inicializando el tiempo de ejecución de Python...
Instalando el controlador NSLog de Python...
Ejecutando el módulo de la aplicación: helloworld
---------------------------------------------------------------------------

(beeware-venv) $ briefcase run

[helloworld] Finalizando la configuración de la aplicación...
Seleccionando ubuntu:jammy (base Debian del proveedor)
Determinando la versión de glibc... hecho
Seleccionando glibc 2.35
Seleccionando Python 3.10

[helloworld] Iniciando la aplicación...
===========================================================================
Ruta de instalación: /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr
Preinicializando el tiempo de ejecución de Python...
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
Configurando argc/argv...
Inicializando el tiempo de ejecución de Python...
Ejecutando el módulo de la aplicación: helloworld
---------------------------------------------------------------------------

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

[helloworld] Iniciando la aplicación...

===========================================================================
Inicio del registro: 2023-04-23 04:47:45Z
Preinicializando el entorno de ejecución de Python...
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:\Usuarios\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src\app_packages
- C:\Usuarios\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src\app
Configurando argc/argv...
Inicializando el tiempo de ejecución de Python...
Ejecutando el módulo de la aplicación: helloworld
---------------------------------------------------------------------------

Esto iniciará la ejecución de tu 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 Quitar/Salir 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 distribuíble. 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] Firmando la aplicación...

*************************************************************************
** ADVERTENCIA: Firmando con una identidad ad hoc **
*************************************************************************

 Esta aplicación se está firmando con una identidad ad hoc. La aplicación resultante
    se ejecutará en este ordenador, pero no se ejecutará en el ordenador de nadie más
    .

 Para generar una aplicación que se pueda distribuir a otros, debes
    obtener un certificado de distribución de aplicaciones de Apple y
    seleccionar la identidad de desarrollador asociada a ese certificado
    al ejecutar «briefcase package».

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

Firmando la aplicación con identidad ad hoc...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100,0 % • 00:07

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

[helloworld] Empaquetado 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 pulsas dos veces 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 del código en 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] Finalizando la configuración de la aplicación...
Seleccionando ubuntu:jammy (base Debian del proveedor)
Determinando la versión de glibc... hecho
Seleccionando glibc 2.35
Seleccionando Python 3.10

[helloworld] Compilando el paquete .deb...
Escribiendo el archivo de control del paquete Debian... hecho

dpkg-deb: creando el paquete «helloworld» en «helloworld-0.0.1.deb».
Creando el paquete Debian... hecho

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

La carpeta dist contendrá el archivo .deb que fue generado.

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

(beeware-venv) $ briefcase package

[helloworld] Finalizando la configuración de la aplicación...
Dirigido a fedora:40 (base del proveedor rhel)
Determinando la versión de glibc... hecho
Dirigido a glibc 2.39
Dirigido a Python 3.12

[helloworld] Compilando el paquete .rpm...
Generando el diseño de rpmbuild... hecho

Escribiendo el archivo de especificaciones RPM... hecho

Compilando el archivo fuente... hecho

Ejecutando(%prep): /bin/sh -e /var/tmp/rpm-tmp.Kav9H7
+ umask 022
...
+ exit 0
Compilando el paquete RPM... hecho

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

La carpeta dist contendrá el archivo .rpm que fue generado.

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

(beeware-venv) $ briefcase package

[helloworld] Finalizando la configuración de la aplicación...
Seleccionando arch:20240101 (arch de base del proveedor)
Determinando la versión de glibc... hecho
Seleccionando glibc 2.38
Seleccionando Python 3.12

[helloworld] Compilando el paquete .pkg.tar.zst...
...
Compilando el paquete Arch... hecho

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

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

Otras distribuciones de Linux actualmente no están mantenidas para empaquetado.

Si desea construir 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 intérprete Unix (algo como root@84444e31cff9:/#) dentro de un contenedor Docker Ubuntu 22.04. Teclea 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 admita 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, puedes 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

************************************************************************
** ADVERTENCIA: No se ha proporcionado ninguna identidad de firma **
************************************************************************

    Briefcase no firmará la aplicación. Para proporcionar una identidad de firma,
    utilice la opción `--identity`; o, para desactivar explícitamente la firma,
    utilice `--adhoc-sign`.

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

[helloworld] Compilando MSI...
Compilando el manifiesto de la aplicación...
Compilando... hecho

Compilando el instalador de la aplicación...
helloworld.wxs
helloworld-manifest.wxs
Compilando... hecho

Vinculando el instalador de la aplicación...
Vinculando... hecho

[helloworld] Empaquetado en dist\Hello_World-0.0.1.msi

En este ejemplo, no hemos formado nuestra app. Como un resultado, cuando utilizamos el instalador, obtendremos un aviso del sistema que la aplicación viene desde un desarrollados desconocido. 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 una identidad de firma real; cuando esta aplicación firmada esté instalada, el sistema notificará al usuario que la aplicación es desde la identidad desconocida asociada con el certificado.

Cuando esté listo para publicar una aplicación real, consulte la guía práctica de Briefcase en Configurar una identidad de firma de código de Windows.

Una vez completado este paso, la carpeta dist contendrá un archivo llamado Hello_World-0.0.1.msi. Si pulsas dos veces en este instalador para ejecutarlo, iría a través del proceso de instalación de Windows que ya conoces. Una vez finalizada esta instalación, aparecerá una apunte "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…