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:

macOSLinuxWindows

(beeware-venv) $ briefcase create

[helloworld] Gerando modelo de aplicativo...
Usando modelo de aplicativo: https://github.com/beeware/briefcase-macOS-app-template.git, ramificação v0.3.18
...

[helloworld] Instalando pacote de suporte...
...

[helloworld] Instalando código do aplicativo...
Instalando src/helloworld... concluído

[helloworld] Instalando requisitos...
...

[helloworld] Instalando recursos da aplicação...
...

[helloworld] Removendo conteúdo desnecessário da aplicação...
Removendo conteúdo desnecessário do pacote da aplicação... concluído

[helloworld] Criado build/helloworld/macos/app

(beeware-venv) $ briefcase create

[helloworld] Finalizando a configuração do aplicativo...
Direcionando para ubuntu:jammy (base Debian do fornecedor)
Determinando a versão da glibc... concluído
Direcionando para glibc 2.35
Direcionando para Python 3.10

[helloworld] Gerando modelo de aplicativo...
Usando modelo de aplicativo: https://github.com/beeware/briefcase-linux-AppImage-template.git, ramificação v0.3.18
...

[helloworld] Instalando pacote de suporte...
Nenhum pacote de suporte necessário.

[helloworld] Instalando código do aplicativo...
Instalando src/helloworld... concluído

[helloworld] Instalando requisitos...
...

[helloworld] Instalando recursos da aplicação...
...

[helloworld] Removendo conteúdo desnecessário da aplicação...
Removendo conteúdo desnecessário do pacote da aplicação... concluído

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

Erros sobre versões do Python

Se você receber um erro do tipo:

A versão do Python que está sendo usada para executar o Briefcase (3.12) não é o python3 do sistema (3.10).

Você precisará recriar seu ambiente virtual usando o sistema python3. O uso do sistema Python é um requisito para empacotar seu aplicativo.

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

[helloworld] Gerando modelo de aplicativo...
Usando modelo de aplicativo: https://github.com/beeware/briefcase-windows-app-template.git, ramificação v0.3.18
...

[helloworld] Instalando pacote de suporte...
...

[helloworld] Instalando o código do aplicativo...
Instalando src/helloworld... concluído

[helloworld] Instalando os pré-requisitos...
...

[helloworld] Instalando os recursos do aplicativo...
...

[helloworld] Criado 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:

1. Ele gerou um modelo de aplicativo. Há muitos arquivos e configurações necessários para construir um instalador nativo, acima e além do código do seu aplicativo real. Esse andaime extra é quase o mesmo para todos os aplicativos na mesma plataforma, exceto pelo nome do aplicativo real que está sendo construído - portanto, o Briefcase fornece um modelo de aplicativo para cada plataforma que ele suporta. Esta etapa implementa o modelo, substituindo o nome do seu aplicativo, o ID do pacote e outras propriedades do seu arquivo de configuração, conforme necessário para dar suporte à plataforma em que você está construindo. Se não estiver satisfeito com o modelo fornecido pelo Briefcase, você pode criar o seu próprio modelo. No entanto, é provável que você não queira fazer isso até que tenha um pouco mais de experiência no uso do modelo padrão do Briefcase.

2. 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 envia um interpretador Python completo e isolado como parte de cada aplicativo que constrói (exceto para compilações de pacotes do sistema nativo do Linux). Isso é um pouco ineficiente 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 aplicativo seja completamente independente, usando uma versão específica do Python que é conhecida por funcionar com o aplicativo. Novamente, o Briefcase fornece um pacote de suporte padrão para cada plataforma; se quiser, você pode fornecer seu próprio pacote de suporte e incluí-lo como parte do processo de compilação. Talvez você queira fazer isso se tiver opções específicas no interpretador Python que precisam ser ativadas ou se quiser 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 em cache será usada em compilações futuras. Conforme observado acima, quando o Briefcase empacota um aplicativo como um pacote de sistema Linux nativo (o formato de pacote padrão para Linux), um pacote de suporte não é incluído com o aplicativo. Em vez disso, o aplicativo usará o Python que é fornecido pela distribuição do Linux que está sendo visada.

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

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

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

Quando isso for concluído, se você olhar no diretório build do projeto, deverá ver um diretório correspondente à sua plataforma (macOS, linux ou windows) que contém arquivos adicionais. Essa é a configuração de empacotamento específica da plataforma para o seu aplicativo. Por exemplo, no macOS, o diretório do seu projeto agora incluirá:

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

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.

macOSLinuxWindows

(beeware-venv) $ briefcase build

[helloworld] Aplicativo de assinatura ad hoc...
...
Assinando build/helloworld/macos/app/Hello World.app
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100,0% • 00:07

[helloworld] Compilado 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] Finalizando a configuração da aplicação...
Direcionando para ubuntu:jammy (base Debian do fornecedor)
Determinando a versão da glibc... concluído
Direcionando para glibc 2.35
Direcionando para Python 3.10

[helloworld] Compilando a aplicação...
Compilando binário bootstrap...
make: Entrando no diretório '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
...
make: Saindo do diretório '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
Compilando binário bootstrap... concluído
Instalando licença... concluído
Instalando changelog... concluído
Instalando página man... concluído
Atualizando permissões de arquivo... concluído
Removendo informações de binário... concluído

[helloworld] Compilado 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
Configurando detalhes do aplicativo de teste... concluído

[helloworld] Gerado 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.

Acionamento do 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:

macOSLinuxWindows

(beeware-venv) $ briefcase run

[helloworld] Iniciando o aplicativo...
===========================================================================
Configurando o Python isolado...
Pré-inicializando o ambiente de execução do 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
- /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
Configurando argc/argv...
Inicializando o tempo de execução do Python...
Instalando o manipulador NSLog do Python...
Executando o módulo do aplicativo: helloworld
---------------------------------------------------------------------------

(beeware-venv) $ briefcase run

[helloworld] Finalizando a configuração do aplicativo...
Direcionando para ubuntu:jammy (base Debian do fornecedor)
Determinando a versão da glibc... concluído
Direcionando para glibc 2.35
Direcionando para Python 3.10

[helloworld] Iniciando o aplicativo...
===========================================================================
Caminho de instalação: /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr
Pré-inicializando o runtime do 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 o tempo de execução do Python...
Executando o módulo do aplicativo: helloworld
---------------------------------------------------------------------------

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

[helloworld] Iniciando o aplicativo...

===========================================================================
Registro iniciado: 2023-04-23 04:47:45Z
Pré-inicializando o ambiente de execução do 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:\Users\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src\app_packages
- C:\Users\brutus\beeware-tutorial\helloworld\windows\app\Hello World\src\app
Configurando argc/argv...
Inicializando o runtime do Python...
Executando o módulo da aplicação: 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.

Antes de continuar, feche o aplicativo. Como nas etapas anteriores do tutorial, você pode fazer isso pressionando o botão Fechar na janela do aplicativo, selecionando Quit/Exit no menu do aplicativo ou digitando Ctrl+C no terminal em que executou briefcase run.

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.

macOSLinuxWindows

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

[helloworld] Assinando o aplicativo...

*************************************************************************
** AVISO: Assinatura com uma identidade ad-hoc **
*************************************************************************

Este aplicativo está sendo assinado com uma identidade ad-hoc. O aplicativo
    resultante será executado neste computador, mas não será executado no computador
    de ninguém mais.

Para gerar um aplicativo que possa ser distribuído a outras pessoas, você deve
    obter um certificado de distribuição de aplicativos da Apple e
    selecionar a identidade de desenvolvedor associada a esse certificado
    ao executar o 'briefcase package'.

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

Assinando o aplicativo com identidade ad-hoc...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100,0% • 00:07

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

[helloworld] Empacotado 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] Finalizando a configuração do aplicativo...
Direcionando para ubuntu:jammy (base Debian do fornecedor)
Determinando a versão da glibc... concluído
Direcionando para glibc 2.35
Direcionando para Python 3.10

[helloworld] Compilando o pacote .deb...
Escrevendo arquivo de controle do pacote Debian... concluído

dpkg-deb: criando o pacote 'helloworld' em 'helloworld-0.0.1.deb'.
Criando pacote Debian... concluído

[helloworld] Empacotado 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] Finalizando a configuração do aplicativo...
Direcionando para fedora:40 (base do fornecedor rhel)
Determinando a versão do glibc... concluído
Direcionando para glibc 2.39
Direcionando para Python 3.12

[helloworld] Compilando pacote .rpm...
Gerando layout do rpmbuild... concluído

Escrevendo arquivo de especificação RPM... concluído

Compilando arquivo de código-fonte... concluído

Executando(%prep): /bin/sh -e /var/tmp/rpm-tmp.Kav9H7
+ umask 022
...
+ exit 0
Compilando pacote RPM... concluído

[helloworld] Empacotado 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] Finalizando a configuração do aplicativo...
Direcionando para arch:20240101 (arquitetura base do fornecedor)
Determinando a versão da glibc... concluído
Direcionando para glibc 2.38
Direcionando para Python 3.12

[helloworld] Compilando o pacote .pkg.tar.zst...
...
Compilando o pacote Arch... concluído

[helloworld] Empacotado 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:

$ pacote briefcase --destino 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

*************************************************************************
** AVISO: Nenhuma identidade de assinatura fornecida **
*************************************************************************

    O Briefcase não assinará o aplicativo. Para fornecer uma identidade de assinatura,
    use a opção `--identity`; ou, para desativar explicitamente a assinatura,
    use `--adhoc-sign`.

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

[helloworld] Compilando MSI...
Compilando manifesto do aplicativo...
Compilando... concluído

Compilando instalador do aplicativo...
helloworld.wxs
helloworld-manifest.wxs
Compilando... concluído

Vinculando instalador do aplicativo...
Vinculando... concluído

[helloworld] Empacotado em 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…