SPSValidator — build e execução (Linux e Windows)

[robertatakenaka]

Pré-requisitos comuns

• Rodar o build dentro de um venv (os scripts executam pip install -e ".[dev]" no Python ativo).
• packtools depende de pkg_resources (por isso setuptools<82 no pyproject.toml e os --hidden-import/--copy-metadata nos scripts). Se aparecer No module named 'pkg_resources', reinstale as dependências e rebuilde.
• Ambos os builds geram um bundle one-folder em dist/spsvalidator/ (não é --onefile).
• O spsvalidator.spec versionado está configurado para macOS (BUNDLE/.app, icon.icns). Os scripts de Linux e Windows não usam esse .spec: chamam o pyinstaller direto com flags.
• Dados locais ficam em ~/.spsvalidator/spsvalidator.sqlite3 (Linux) ou %USERPROFILE%\.spsvalidator\spsvalidator.sqlite3 (Windows).

---

Linux

1. Build

cd apps/spsvalidator
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
bash packaging/build_linux.sh

Saída: dist/spsvalidator/ com o executável dist/spsvalidator/spsvalidator.

2. Rodar

./dist/spsvalidator/spsvalidator

3. Backend de WebView (essencial)

O --collect-all webview empacota apenas o pacote Python pywebview; o motor de renderização nativo é do sistema e precisa estar instalado na máquina que executa o binário. Sem ele, a janela não abre. Instale um dos backends:

• GTK/WebKit (Debian/Ubuntu):

sudo apt install gir1.2-gtk-3.0 gir1.2-webkit2-4.1 python3-gi

Em distros mais antigas pode ser gir1.2-webkit2-4.0.

• Ou Qt:

sudo apt install python3-pyqt5 python3-pyqt5.qtwebengine

4. Modo navegador (fallback / headless)

./dist/spsvalidator/spsvalidator --browser
# abrir http://127.0.0.1:5000

5. (Opcional) AppImage

Com o dist/spsvalidator/ pronto, usando linuxdeploy e appimagetool:

linuxdeploy --appdir AppDir \
  --executable dist/spsvalidator/spsvalidator \
  --desktop-file spsvalidator.desktop \
  --icon-file src/spsvalidator/web/static/img/icon.png
appimagetool AppDir spsvalidator-x86_64.AppImage

Requer criar um arquivo spsvalidator.desktop (ainda não existe em packaging/).

---

Windows

1. Build

No PowerShell, dentro de apps/spsvalidator:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
powershell -ExecutionPolicy Bypass -File packaging\build_windows.ps1

Saída: dist\spsvalidator\ com o executável dist\spsvalidator\spsvalidator.exe.

2. Rodar

.\dist\spsvalidator\spsvalidator.exe

Ou apenas dê duplo clique no spsvalidator.exe dentro de dist\spsvalidator\.

3. Backend de WebView (essencial)

No Windows, o pywebview usa por padrão o Microsoft Edge WebView2. A máquina precisa do WebView2 Runtime instalado (já presente na maioria dos Windows 10/11 atualizados). Se a janela não abrir, instale o runtime "Evergreen" da Microsoft (Microsoft Edge WebView2 Runtime).

4. Modo navegador (fallback / headless)

.\dist\spsvalidator\spsvalidator.exe --browser
# abrir http://127.0.0.1:5000

5. Distribuição

• Para distribuir, compacte a pasta dist\spsvalidator\ inteira (o .exe depende dos arquivos ao lado dele).
• Opcionalmente, gere um instalador com Inno Setup ou NSIS apontando para o conteúdo de dist\spsvalidator\.