Tutorial 3 - Empacotando para Distribuição¶
Até o momento, executamos nossa aplicação no «modo de desenvolvedor». Isso facilita a execução da nossa aplicação localmente - mas o que realmente queremos é poder fornecer nossa aplicação para outras pessoas.
Entretanto, não queremos ter que ensinar aos nossos usuários como instalar o Python, criar um ambiente virtual, clonar um repositório git e executar o Briefcase no modo de desenvolvedor. Queremos é fornecer um instalador, garantindo a execução imediata da aplicação.
O Briefcase pode ser usado para empacotar sua aplicação para distribuição dessa maneira.
Criando a estrutura da sua aplicação¶
Como esta é a primeira vez que estamos empacotando nossa aplicação, precisamos criar alguns arquivos de configuração e outras estruturas de suporte ao processo de empacotamento. No diretório helloworld
, execute:
(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
(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
É provável que você tenha observado uma grande quantidade de texto passando pelo seu terminal… mas o que exatamente aconteceu? O Briefcase fez o seguinte:
Ele gerou um modelo de aplicação (template). Existem muitos arquivos e configurações necessárias para construir um instalador nativo, além do código da sua aplicação. Essa estrutura extra é quase igual para todas as aplicações na mesma plataforma, exceto pelo nome da aplicação que está sendo construída - um modelo de aplicação (template) é fornecido pelo Briefcase para cada plataforma que ele suporta. Esta etapa implementa o modelo, substituindo o nome da sua aplicação, ID do pacote e outras propriedades do seu arquivo de configuração conforme necessário para suportar a plataforma na qual você está construindo.
Caso o modelo fornecido pelo Briefcase não seja satisfatório, é possível você fornecer um modelo próprio. Entretanto, é recomendável que isso não seja feito antes de se obter maior familiaridade com o modelo padrão do Briefcase.
Ele baixou e instalou um pacote de suporte. A abordagem de empacotamento adotada pelo Briefcase é melhor descrita como «a coisa mais simples que poderia funcionar» - ele inclui um interpretador Python completo e isolado como parte de cada aplicativo criado. Isso apresenta uma ligeira ineficiência em termos de espaço - se você tiver 5 aplicativos empacotados com o Briefcase, terá 5 cópias do interpretador Python. No entanto, essa abordagem garante que cada aplicação seja completamente independente, usando uma versão específica do Python que comprovadamente funciona com tal aplicação.
Novamente, o Briefcase fornece um pacote de suporte padrão para cada plataforma; entretanto, caso deseje, você pode fornecer seu próprio pacote de suporte e incluí-lo como parte do processo de construção. Isso pode ser útil se você necessita de opções específicas habilitadas no interpretador Python, ou se deseja remover módulos da biblioteca padrão que não são necessários em tempo de execução.
O Briefcase mantém um cache local de pacotes de suporte. Portanto, uma vez que você tenha baixado um pacote de suporte específico, essa cópia armazenada será utilizada em compilações futuras.
As noted above, when Briefcase packages an app as a native Linux system package (the default package format for Linux), a support package is not included with the app. Instead, the app will use the Python that is provided by the distribution of Linux being targeted.
Ele instalou os requisitos da aplicação. Seu aplicativo pode especificar quaisquer módulos de terceiros necessários em tempo de execução. Estes serão instalados utilizando o
pip
no instalador da sua aplicação.Ele instalou o código da sua aplicação. Sua aplicação terá seu próprio código e recursos (por exemplo, imagens necessárias em tempo de execução); estes arquivos são copiados para o instalador.
Ele instalou os recursos requeridos pela sua aplicação. Por fim, são adicionados recursos adicionais requeridos pelo próprio instalador. Isso inclui elementos como ícones que serão anexados à aplicação final e imagens de tela de abertura.
Assim que concluído, ao verificar o diretório do projeto, você deverá encontrar um diretório correspondente à sua plataforma (macOS
, linux
ou windows
) contendo arquivos adicionais. Esta é a configuração de empacotamento específica para a plataforma da sua aplicação.
Compilando sua aplicação¶
Agora você pode compilar sua aplicação. Este passo executa qualquer compilação binária necessária para que sua aplicação seja executável na plataforma de destino.
(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
No macOS, o comando build
não necessita compilar nada, mas precisa assinar o conteúdo do binário para que ele possa ser executado. Essa assinatura é do tipo ad hoc - só funcionará no seu computador. Se você deseja distribuir a aplicação para outras pessoas, será necessário fornecer uma assinatura 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
Após a conclusão dessa etapa, a pasta build
conterá uma pasta helloworld-0.0.1
com uma estrutura semelhante ao sistema de arquivos /usr
do Linux. Ela conterá uma pasta bin
com um binário helloworld
, além das pastas lib
e share
necessárias para dar suporte ao binário.
(beeware-venv) C:\...>briefcase build
Setting stub app details... done
[helloworld] Built build\helloworld\windows\app\src\Hello World.exe
No Windows, o comando build
não precisa compilar nada, mas é preciso registrar alguns metadados para que a aplicação reconheça seu nome, versão e outras coisas assim.
Notificação de antivírus
Como esses metadados estão sendo gravados diretamente no binário pré-compilado que sai do modelo durante o comando create
, isso pode acionar o software antivírus em execução no computador e impedir que os metadados sejam gravados. Nesse caso, instrua o antivírus a permitir que a ferramenta (denominada rcedit-x64.exe
) seja executada e execute novamente o comando acima.
Rodando sua aplicação¶
Agora você pode utilizar o Briefcase para executar sua aplicação:
(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
---------------------------------------------------------------------------
Isso iniciará a execução de seu aplicativo nativo, usando a saída do comando build
.
Você pode notar algumas pequenas diferenças na aparência do seu aplicativo quando ele estiver em execução. Por exemplo, os ícones e o nome exibidos pelo sistema operacional podem ser ligeiramente diferentes daqueles vistos durante a execução no modo de desenvolvedor. Isso também ocorre porque você está usando o aplicativo empacotado, e não apenas executando o código Python. Do ponto de vista do sistema operacional, agora você está executando «um aplicativo», não «um programa Python», e isso se reflete na aparência do aplicativo.
Criando o seu instalador¶
Agora você pode empacotar seu aplicativo para distribuição, usando o comando package
. O comando package faz qualquer compilação necessária para converter o projeto de andaime em um produto final e distribuível. Dependendo da plataforma, isso pode envolver a compilação de um instalador, a execução de assinatura de código ou outras tarefas de pré-distribuição.
(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
A pasta dist
conterá um arquivo chamado Hello World-0.0.1.dmg
. Se você localizar esse arquivo no Finder e clicar duas vezes em seu ícone, montará o DMG, fornecendo uma cópia do aplicativo Hello World e um link para a pasta Applications para facilitar a instalação. Arraste o arquivo do aplicativo para Applications e você terá instalado o aplicativo. Envie o arquivo DMG para um amigo e ele poderá fazer o mesmo.
Neste exemplo, usamos a opção --adhoc-sign
, ou seja, estamos assinando nosso aplicativo com credenciais ad hoc, credenciais temporárias que só funcionarão em seu computador. Fizemos isso para manter a simplicidade do tutorial. A configuração de identidades de assinatura de código é um pouco complicada, e elas só são necessárias se você pretende distribuir o aplicativo para outras pessoas. Se estivéssemos publicando um aplicativo real para ser usado por outras pessoas, precisaríamos especificar credenciais reais.
Quando estiver pronto para publicar um aplicativo real, consulte o guia de instruções da Briefcase sobre Configuração de uma identidade de assinatura de código do macOS
A saída da etapa do pacote será ligeiramente diferente, dependendo de sua distribuição Linux. Se estiver em uma distribuição derivada do Debian, você verá:
(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
A pasta dist
conterá o arquivo .deb
que foi gerado.
Se estiver em uma distribuição baseada em RHEL, você verá:
(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
A pasta dist
conterá o arquivo .rpm
que foi gerado.
Se estiver em uma distribuição baseada no Arch, você verá:
(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
A pasta dist
conterá o arquivo .pkg.tar.zst
que foi gerado.
No momento, não há suporte para o empacotamento de outras distribuições do Linux.
Se quiser criar um pacote para uma distribuição Linux diferente da que você está usando, o Briefcase também pode ajudar, mas você precisará instalar o Docker.
Os instaladores oficiais do Docker Engine estão disponíveis para uma série de distribuições Unix. Siga as instruções para sua plataforma; no entanto, certifique-se de não instalar o Docker no modo «sem raiz».
Depois de instalar o Docker, você deve ser capaz de iniciar um contêiner Linux - por exemplo:
$ docker run --rm -it ubuntu:22.04
mostrará um prompt do Unix (algo como root@84444e31cff9:/#
) dentro de um contêiner do Docker do Ubuntu 22.04. Digite Ctrl-D para sair do Docker e retornar ao seu shell local.
Depois de instalar o Docker, você pode usar o Briefcase para criar um pacote para qualquer distribuição Linux compatível com o Briefcase, passando uma imagem do Docker como argumento. Por exemplo, para criar um pacote DEB para o Ubuntu 22.04 (Jammy), independentemente do sistema operacional em que você estiver, execute:
$ briefcase package --target ubuntu:jammy
Isso fará o download da imagem do Docker para o sistema operacional selecionado, criará um contêiner capaz de executar as compilações do Briefcase e compilará o pacote do aplicativo dentro da imagem. Após a conclusão, a pasta dist
conterá o pacote para a distribuição 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
Neste exemplo, usamos a opção --adhoc-sign
, ou seja, estamos assinando nosso aplicativo com credenciais ad hoc, credenciais temporárias que só funcionarão em seu computador. Fizemos isso para manter a simplicidade do tutorial. A configuração de identidades de assinatura de código é um pouco complicada, e elas só são necessárias se você pretende distribuir o aplicativo para outras pessoas. Se estivéssemos publicando um aplicativo real para ser usado por outras pessoas, precisaríamos especificar credenciais reais.
Quando estiver pronto para publicar um aplicativo real, consulte o guia de instruções da Briefcase sobre Configuração de uma identidade de assinatura de código do macOS
Quando essa etapa for concluída, a pasta dist
conterá um arquivo chamado Hello_World-0.0.1.msi
. Se você clicar duas vezes nesse instalador para executá-lo, deverá passar por um processo familiar de instalação do Windows. Após a conclusão da instalação, haverá uma entrada «Hello World» em seu menu Iniciar.
Próximos passos¶
Agora temos nosso aplicativo empacotado para distribuição em plataformas de desktop. Mas o que acontece quando precisamos atualizar o código em nosso aplicativo? Como podemos colocar essas atualizações em nosso aplicativo empacotado? Consulte o Tutorial 4 para descobrir…