Skip to content

uso-cli.md

Latest commit

 

History

History
314 lines (229 loc) · 8.82 KB

uso-cli.md

File metadata and controls

314 lines (229 loc) · 8.82 KB
Raw

Linha de comando

genpyexe [--version] COMANDO [OPÇÕES]
Comando Função
doctor Diagnostica o ambiente
init Cria o perfil genpyexe.toml
build Gera o executável e o instalador
icon Converte ou gera ícones
helper Gera o módulo de acesso a recursos no projeto
recipes Lista as receitas de empacotamento por biblioteca
clean Remove as venvs de build em cache
gui Abre o assistente gráfico

doctor

genpyexe doctor
genpyexe doctor --python D:\python.exe

Verifica Python, PyInstaller, Inno Setup e signtool. Quando algo falta, mostra o comando exato para instalar — mas nunca instala sozinho.

build

genpyexe build PASTA [OPÇÕES]

Identidade

Opção Padrão Efeito
--name, -n nome da pasta Nome do aplicativo
--version, -v 1.0.0 Versão X.Y.Z
--publisher, -p vazio Autor ou empresa
--description, -d nome do app Descrição curta
--copyright derivado do publisher Aviso de copyright
--url vazio Site do projeto

Ícone e entrypoint

Opção Efeito
--icon, -i Imagem do ícone
--auto-icon Gera ícone com as iniciais
--entrypoint, -e Arquivo .py inicial (detectado se omitido)

Formato

Opção Padrão
--onefile / --onedir --onefile
--windowed / --console --windowed
--isolated / --no-isolation --isolated
--base-python interpretador atual
--uac-admin desligado
--output, -o <projeto>/dist
--clean desligado
--verbose desligado

Empacotamento avançado

Todas repetíveis:

genpyexe build ./App \
    --hidden-import meu.modulo.dinamico \
    --collect-all pacote_com_dados \
    --exclude modulo_pesado_nao_usado

Para desligar as receitas automáticas (veja recipes):

genpyexe build ./App --no-recipes

--no-recipes desliga apenas a camada automática. O que você passou em --hidden-import, --collect-all e --exclude continua valendo.

Instalador

Opção Padrão
--installer / --no-installer --no-installer
--desktop-shortcut / --no-desktop-shortcut ligado
--start-menu / --no-start-menu ligado
--launch-after / --no-launch-after ligado
--per-user / --all-users --per-user
--add-to-path desligado
--run-at-startup desligado
--keep-data desligado
--associate nenhuma (repetível)
--license-file nenhum
--compression auto

--compression aceita auto, max, fast ou none. O padrão auto usa fast em --onefile (o executável do PyInstaller já vem comprimido, então o nível máximo custa o dobro do tempo para ganhar ~0,1%) e max em --onedir, onde a pasta traz binários crus e a compressão rende.

Perfil

--config (padrão) lê o genpyexe.toml do projeto; opções da linha de comando têm prioridade sobre o perfil. Use --no-config para ignorá-lo.

Exemplos

Aplicativo gráfico completo:

genpyexe build ./MinhaFerramenta \
    --name "Minha Ferramenta" --version 2.1.0 \
    --publisher "Seu Nome" --icon assets/logo.png \
    --installer --desktop-shortcut --start-menu

Ferramenta de linha de comando no PATH:

genpyexe build ./MinhaCLI \
    --name "minhacli" --console --onefile \
    --installer --add-to-path --no-desktop-shortcut

Editor que abre os próprios arquivos:

genpyexe build ./MeuEditor \
    --name "Meu Editor" --icon logo.png \
    --installer --associate .meudoc --associate .meuproj

Aplicativo corporativo para todos os usuários:

genpyexe build ./AppCorp \
    --name "App Corporativo" --publisher "Empresa Ltda" \
    --installer --all-users --start-menu --no-launch-after

Build offline (sem baixar dependências):

genpyexe build ./MeuApp --no-isolation

Aplicativo pesado, em modo pasta:

genpyexe build ./AppIA --onedir --installer --no-desktop-shortcut

init

genpyexe init ./MeuApp            # pergunta cada campo
genpyexe init ./MeuApp --yes      # não pergunta nada: gera tudo pela análise
genpyexe init ./MeuApp --force    # sobrescreve um perfil existente

Analisa o projeto, sugere os valores detectados e faz perguntas objetivas. Grava genpyexe.toml na raiz do projeto.

Com --yes (ou -y) nenhuma pergunta é feita: o perfil sai pronto a partir da análise — entrypoint, dependências, ícone detectado e o tipo de aplicativo (gráfico ou de terminal). O arquivo gerado é texto comentado, feito para ser revisado depois. É o caminho mais curto do zero ao build:

genpyexe init ./MeuApp --yes && genpyexe build ./MeuApp

Os campos podem vir por opção, com ou sem --yes:

Opção Efeito
--name / -n Nome do aplicativo (padrão: nome da pasta)
--version / -v Versão (padrão: 1.0.0)
--publisher / -p Autor ou empresa
--installer / --no-installer Gerar também o instalador (padrão: sim)

icon

genpyexe icon logo.png                       # gera logo.ico
genpyexe icon logo.png -o assets/app.ico     # destino explícito
genpyexe icon -g "Meu App"                   # ícone com as iniciais

Sempre gera as sete resoluções (16 a 256 px), preservando a proporção.

helper

Gera um resources.py dentro do projeto, com os utilitários de caminho que o aplicativo precisa para achar os próprios recursos depois de empacotado.

genpyexe helper ./MeuApp                        # cria ./MeuApp/resources.py
genpyexe helper ./MeuApp -o app/recursos.py     # outro caminho
genpyexe helper ./MeuApp --force                # substitui um arquivo existente
genpyexe helper ./MeuApp -n "Meu App" -p "Seu Nome"

Sem --name e --publisher, os valores vêm do genpyexe.toml do projeto; sem perfil, do nome da pasta.

Por que ele existe

O GenPyEXE empacota assets/ corretamente, mas isso não basta: dentro do executável o PyInstaller descompacta os dados numa pasta temporária, e o caminho relativo do código quebra.

open("assets/logo.png")                      # FileNotFoundError dentro do .exe

from resources import resource_path
open(resource_path("assets", "logo.png"))    # funciona nos dois casos

O que o arquivo traz

Função Uso
resource_path(*partes) Recurso somente leitura empacotado. Resolve em desenvolvimento, --onefile e --onedir
user_data_dir(app, publisher) Pasta gravável e persistente em %LOCALAPPDATA%, criada sob demanda
is_frozen() Diz se o código está rodando dentro do executável

As duas primeiras existem separadas de propósito: em --onefile a pasta de resource_path() é temporária e some quando o aplicativo fecha. Log, banco local e configuração vão em user_data_dir() — que é também a pasta preservada pela opção keep_data_on_uninstall do instalador.

O arquivo gerado usa apenas a biblioteca padrão. Ele não importa o genpyexeks, então não cria dependência do seu aplicativo com o GenPyEXE nem aumenta o executável. É seu: versione-o junto do projeto e edite à vontade.

Se você mover o arquivo para dentro de um subpacote, ajuste a constante _DEV_ROOT no topo dele para continuar apontando para a raiz do projeto. O comentário no próprio arquivo explica.

O genpyexe init também oferece gerá-lo.

recipes

Lista as receitas de empacotamento que o GenPyEXE aplica automaticamente quando detecta a biblioteca no projeto.

genpyexe recipes                  # lista todas
genpyexe recipes customtkinter    # detalha uma

Uma receita não inventa mecanismo nenhum: apenas liga as opções públicas e documentadas do PyInstaller — --collect-all, --collect-data, --collect-submodules e --hidden-import — para bibliotecas em que a coleta automática costuma deixar arquivos para trás.

Bibliotecas fora da tabela seguem o comportamento padrão do PyInstaller: a ausência de receita nunca quebra um build.

Para desligar a camada automática num build:

genpyexe build ./App --no-recipes

Isso não descarta o que você declarou explicitamente — --hidden-import, --collect-all e --exclude continuam valendo. No perfil, a mesma coisa:

[build]
recipes = false

clean

genpyexe clean        # pede confirmação
genpyexe clean --yes  # sem perguntar

Códigos de saída

Código Significado
0 Sucesso
1 Falha no build ou erro previsto
2 Argumentos inválidos (pasta inexistente, por exemplo)
130 Cancelado pelo usuário (Ctrl+C)

Úteis em scripts de integração contínua:

genpyexe build ./App --installer || exit 1