Ir para o conteúdo

Tutorial 3 - Empacotar para distribuição

Até o momento, executamos a nossa aplicação em "modo de desenvolvedor". Isso facilita-nos executar a nossa aplicação localmente - mas o que realmente queremos é poder fornecer a nossa aplicação a outras pessoas.

Entretanto, não queremos ter que ensinar aos nossos utilizadores a como instalar Python, criar um ambiente virtual, clonar um repositório git e executar o Briefcase no modo de desenvolvedor. Preferimos dar-lhes um instalador, e ter a aplicação A Trabalhar.

O Briefcase pode ser usado para empacotar a sua aplicação para distribuir dessa maneira.

Criar o alicerce da sua aplicação

Como esta é a primeira vez que estamos a empacotar a nossa aplicação, precisamos criar alguns ficheiros de configuração e outras estruturas para suportar o processo de empacotamento. No diretório helloworld, execute:

(beeware-venv) $ briefcase create

[helloworld] A gerar modelo de aplicação...
A usar modelo de aplicação: https://github.com/beeware/briefcase-macOS-app-template.git, ramo v0.3.18
...

[helloworld] A instalar pacote de suporte...
...

[helloworld] A instalar código da aplicação...
A instalar src/helloworld... concluído

[helloworld] A instalar requisitos...
...

[helloworld] A instalar recursos da aplicação...
...

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

[helloworld] Criado build/helloworld/macos/app

(beeware-venv) $ briefcase create

[helloworld] A finalizar a configuração da aplicação...
A direcionar para ubuntu:jammy (base de fornecedor Debian)
A determinar a versão da glibc... concluído
A direcionar para glibc 2.35
A direcionar para Python 3.10

[helloworld] A gerar modelo de aplicação...
A usar modelo de aplicação: https://github.com/beeware/briefcase-linux-AppImage-template.git, ramo v0.3.18
...

[helloworld] A instalar pacote de suporte...
Nenhum pacote de suporte necessário.

[helloworld] A instalar código da aplicação...
A instalar src/helloworld... concluído

[helloworld] A instalar requisitos...
...

[helloworld] A instalar recursos da aplicação...
...

[helloworld] A remover conteúdo desnecessário da aplicação...
A remover 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 receber um erro que se parece algo como:

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

Precisa recriar seu ambiente virtual usando o python3 do sistema. O uso do Python do sistema é um requisito para empacotar a sua aplicação.

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

[helloworld] A gerar modelo de aplicação...
A usar modelo de aplicação: https://github.com/beeware/briefcase-windows-app-template.git, ramo v0.3.18
...

[helloworld] A instalar pacote de suporte...
...

[helloworld] A instalar o código da aplicação...
A instalar src/helloworld... concluído

[helloworld] A instalar os pré-requisitos...
...

[helloworld] A instalar os recursos da aplicação...
...

[helloworld] Criado build\helloworld\windows\app

É provável que você tenha observado uma grande quantidade de texto a passar no seu terminal… então o que aconteceu? O Briefcase fez o seguinte:

  1. Ele gerou um modelo de aplicação. Há muitos ficheiros e configurações necessárias para construir um instalador nativo, por cima e além do código da sua aplicação real. Esse andaime extra é quase sempre o mesmo para todas as aplicações na mesma plataforma, exceto pelo nome da aplicação real que está a ser construída - assim, o Briefcase fornece um modelo de aplicação para cada plataforma que suporta. Este passo implementa o modelo, substituindo o nome da sua aplicação, o ID do pacote e outras propriedades do seu ficheiro de configuração, conforme necessário para dar suporte à plataforma para que está a construir. Se não estiver satisfeito com o modelo fornecido pelo Briefcase, pode fornecer o seu próprio modelo. No entanto, é provável que não queira fazer isso até que tenha um pouco mais de experiência a usar o modelo predefinido do Briefcase.

  2. Ele descarregou 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 aplicação que constrói (exceto para compilações de pacotes do sistema nativo do Linux). Isso é um pouco ineficiente em termos de espaço - se tiver 5 aplicações empacotadas 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 é conhecida por funcionar com a aplicação. Novamente, o Briefcase fornece um pacote de suporte predefinido para cada plataforma; se quiser, pode fornecer seu próprio pacote de suporte e incluí-lo como parte do processo de compilação. Talvez queira fazer isso se tiver opções específicas no interpretador Python que precisam ser ativadas ou se quiser remover módulos da biblioteca predefinida 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 tenha descarregado um pacote de suporte específico, essa cópia em cache será usada em compilações futuras. Conforme observado acima, quando o Briefcase empacota uma aplicação como um pacote de sistema Linux nativo (o formato de pacote predefinido para Linux), um pacote de suporte não é incluído com a aplicação. Em vez disso, a aplicação usará o Python fornecido pela distribuição do Linux a que é destinada.

  3. Ele instalou os requisitos da aplicação. A sua aplicação 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. A sua aplicação terá o seu próprio código e recursos (ex., imagens que vão ser necessárias em tempo de execução); estes ficheiros são copiados para o instalador.

  5. Ele instalou os recursos necessários pela sua aplicação. Por fim, adiciona recursos adicionais que são necessários pelo próprio instalador. Isto inclui coisas como ícones que precisam ser anexados à aplicação final e imagens de ecrã de abertura.

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

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

Compilando a sua aplicação

Agora você pode compilar a sua aplicação. Este passo efetua qualquer compilação binária necessária para que sua aplicação seja executável na plataforma de destino.

(beeware-venv) $ briefcase build

[helloworld] Aplicação de assinatura ad hoc...
...
A assinar 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] A finalizar a configuração da aplicação...
A direcionar para ubuntu:jammy (base de fornecedor Debian)
A determinar a versão da glibc... concluído
A direcionar para glibc 2.35
A direcionar para Python 3.10

[helloworld] A compilar a aplicação...
A compilar binário bootstrap...
make: A entrar no diretório '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
...
make: A sair do diretório '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
A compilar binário bootstrap... concluído
A instalar licença... concluído
A instalar changelog... concluído
A instalar página man... concluído
A atualizar permissões de ficheiro... concluído
A remover 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 vai conter uma pasta helloworld-0.0.1 com um espelho do sistema de ficheiros /usr do Linux. Este espelho de sistema de ficheiros vai conter uma pasta bin com um binário helloworld, mais as pastas lib e share necessárias para dar suporte ao binário.

(beeware-venv) C:\...>briefcase build
A configurar detalhes de esboço de aplicação... concluído

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

No Windows, o comando build não precisa compilar nada, mas precisa registrar alguns metadados para que a aplicação reconheça seu nome, versão e outras coisas assim.

Despoletar do antivírus

Como estes metadados são 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 (chamada rcedit-x64.exe) seja executada e execute novamente o comando acima.

Correr a sua aplicação

Agora pode utilizar o Briefcase para executar sua aplicação:

(beeware-venv) $ briefcase run

[helloworld] A iniciar a aplicação...
===========================================================================
A configurar o Python isolado...
A pré-inicializar 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
A configurar argc/argv...
A inicializar o tempo de execução do Python...
A instalar o manipulador NSLog do Python...
A executar o módulo da aplicação: helloworld
---------------------------------------------------------------------------

(beeware-venv) $ briefcase run

[helloworld] A finalizar a configuração da aplicação...
A direcionar para ubuntu:jammy (base de fornecedor Debian)
A determinar a versão da glibc... concluído
A direcionar para glibc 2.35
A direcionar para Python 3.10

[helloworld] A iniciar a aplicação...
===========================================================================
Caminho de instalação: /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr
A pré-inicializar o tempo de execução 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
A configurar argc/argv...
A inicializar o tempo de execução do Python...
A executar o módulo da aplicação: helloworld
---------------------------------------------------------------------------

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

[helloworld] A iniciar a aplicação...

===========================================================================
Registro iniciado: 2023-04-23 04:47:45Z
A pré-inicializar o tempo 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
A configurar argc/argv...
A inicializar o runtime do Python...
A executar o módulo da aplicação: helloworld
---------------------------------------------------------------------------

Isso vai iniciar a execução da sua aplicação nativa, usando a aplicação criada com o comando build.

Pode notar algumas pequenas diferenças na aparência da sua aplicação quando ela está em execução. Por exemplo, os ícones e o nome exibidos pelo sistema operativo podem ser ligeiramente diferentes daqueles vistos durante a execução em modo de desenvolvedor. Isto também acontece porque está a usar a aplicação empacotada, e não apenas a executar o código Python. Do ponto de vista do sistema operativo, agora está a correr "uma aplicação", não "um programa de Python", e isso reflete-se na aparência da aplicação.

Antes de continuar, feche a aplicação. Como nas etapas anteriores do tutorial, você pode fazer isso ao pressionar o botão fechar na janela da aplicação, selecionar Sair/Terminar no menu da aplicação ou teclando Ctrl+C no terminal em que executou briefcase run.

Criar o seu instalador

Agora pode empacotar a sua aplicação para distribuição, usando o comando package. O comando package faz qualquer compilação necessária para converter o projeto de andaime num produto final e distribuível. Dependendo da plataforma, isso pode envolver a compilação dum instalador, a execução de assinatura de código ou outras tarefas de pré-distribuição.

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

[helloworld] A assinar a aplicação...

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

Esta aplicação está sendo assinada com uma identidade ad-hoc. A aplicação
    resultante será executada neste computador, mas não será executada no computador
    de mais ninguém.

Para gerar uma aplicação que possa ser distribuída a outras pessoas, deve
    obter um certificado de distribuição de aplicações da Apple e
    selecionar a identidade de desenvolvedor associada a esse certificado
    ao executar o 'briefcase package'.

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

A assinar a aplicação com identidade ad-hoc...
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100,0% • 00:07

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

[helloworld] A empacotar dist/Hello World-0.0.1.dmg

A pasta dist vai conter um ficheiro chamado Hello World-0.0.1.dmg. Se localizar esse ficheiro no Finder e clicar duas vezes em seu ícone, vai montar o DMG, fornecendo uma cópia da aplicação Hello World e um link para a pasta Applications para facilitar a instalação. Arraste o ficheiro da aplicação para Aplicações e terá instalado a aplicação. Envie o ficheiro DMG para um amigo e ele vai poder fazer o mesmo.

Neste exemplo, usamos a opção --adhoc-sign - ou seja, estamos a assinar a nossa aplicação com credenciais ad hoc, credenciais temporárias que só vão funcionar no 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 pretender distribuir a aplicação para outras pessoas. Se estivéssemos a publicar uma aplicação real para ser usada por outras pessoas, íamos precisar de especificar credenciais reais.

Quando estiver pronto para publicar uma aplicação real, consulte o guia de instruções da Briefcase sobre Configurar uma identidade de assinatura de código do macOS.

O resultado do passo de empacotamento vai ser ligeiramente diferente, dependendo de sua distribuição Linux. Se estiver numa distribuição derivada do Debian, vai ver:

(beeware-venv) $ briefcase package

[helloworld] A finalizar a configuração da aplicação...
A direcionar para ubuntu:jammy (base de fornecedor Debian)
A determinar a versão da glibc... concluído
A direcionar para glibc 2.35
A direcionar para Python 3.10

[helloworld] A compilar o pacote .deb...
A escrever ficheiro de controle do pacote Debian... concluído

dpkg-deb: a criar o pacote 'helloworld' em 'helloworld-0.0.1.deb'.
A criar pacote Debian... concluído

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

A pasta dist vai conter o ficheiro .deb que foi gerado.

Se estiver numa distribuição baseada em RHEL, vai ver:

(beeware-venv) $ briefcase package

[helloworld] A finalizar a configuração da aplicação...
A direcionar para fedora:40 (base de fornecedor rhel)
A determinar a versão do glibc... concluído
A direcionar para glibc 2.39
A direcionar para Python 3.12

[helloworld] A compilar pacote .rpm...
A gerar disposição do rpmbuild... concluído

A escrever ficheiro de especificação RPM... concluído

A compilar ficheiro de código-fonte... concluído

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

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

A pasta dist vai conter o ficheiro .rpm que foi gerado.

Se estiver numa distribuição baseada no Arch, vai ver:

(beeware-venv) $ briefcase package

[helloworld] A finalizar a configuração da aplicação...
A direcionar para arch:20240101 (base de fornecedor arch)
A determinar a versão da glibc... concluído
A direcionar para glibc 2.38
A direcionar para Python 3.12

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

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

A pasta dist vai conter o ficheiro .pkg.tar.zst que foi gerado.

No momento, não há suporte para o empacotamento em outras distribuições do Linux.

Se quiser criar um pacote para uma distribuição Linux diferente da que você está a usar, o Briefcase também pode ajudar - mas vai precisar de instalar o Docker.

Os instaladores oficiais do Motor Docker 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 direitos de root".

Depois de instalar o Docker, deve ser capaz de iniciar um contentor Linux - por exemplo:

$ docker run --rm -it ubuntu:22.04

vai mostrar um aviso de comando do Unix (algo como root@84444e31cff9:/#) dentro de um contentor de Docker do Ubuntu 22.04. Tecle Ctrl-D para sair do Docker e retornar à sua shell local.

Depois de instalar o Docker, pode usar o Briefcase para compilar um pacote para qualquer distribuição Linux que o Briefcase suporte, passando uma imagem do Docker como argumento. Por exemplo, para compilar um pacote DEB para o Ubuntu 22.04 (Jammy), independentemente do sistema operativo em que está, execute:

$ briefcase package --target ubuntu:jammy

Isto vai descarregar a imagem do Docker para o sistema operativo selecionado, vai criar um contentor capaz de executar as compilações do Briefcase, e vai compilar o pacote da aplicação dentro da imagem. Após a conclusão, a pasta dist vai 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 vai assinar a aplicação. Para fornecer uma identidade de assinatura,
    use a opção `--identity`; ou, para desativar explicitamente a assinatura,
    use `--adhoc-sign`.

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

[helloworld] A compilar MSI...
A compilar manifesto da aplicação...
A compilar... concluído

A compilar instalador da aplicação...
helloworld.wxs
helloworld-manifest.wxs
A compilar... concluído

A vincular instalador da aplicação...
A vincular... concluído

[helloworld] Empacotado em dist\Hello_World-0.0.1.msi

Neste exemplo, não estamos a assinar a sua aplicação. Como resultado, quando usa o instalador, vai obter um aviso do sistema de que a aplicação vem de um desenvolvedor desconhecido. Nós fazemos isto para manter o tutorial simples. Definir identidades de assinatura de código é um pouco complexo, e só são requeridas quando tem a intenção de distribuir a sua aplicação a outros. Se estivéssemos a publicar uma aplicação real para outros usarem, íamos precisar de especificar uma identidade de assinatura real; quando essa aplicação assinada está instalada, o sistema vai notificar o utilizador de que a aplicação é da identidade conhecida associada com o certificado.

Quando estiver pronto para publicar uma aplicação real, consulte o guia de instruções do Briefcase sobre Configurar uma identidade de assinatura de código do Windows

Quando este passo estiver concluído, a pasta dist vai conter um ficheiro chamado Hello_World-0.0.1.msi. Se 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, vai existir uma entrada "Hello World" no seu menu Iniciar.

Próximos passos

Agora temos a nossa aplicação empacotada para distribuição em plataformas de ambiente de trabalho. Mas o que acontece quando precisamos atualizar o código da nossa aplicação? Como colocamos essas atualizações na nossa aplicação empacotada? Consulte o Tutorial 4 para descobrir…