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

[samuelveigarangel]

Ao executar o script para o linux, foi preciso inserir algumas linhas em bash_linux.sh:

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$ROOT_DIR"

VENV_DIR="${ROOT_DIR}/.venv"
if [[ -z "${VIRTUAL_ENV:-}" ]]; then
  if [[ ! -d "$VENV_DIR" ]]; then
    python3 -m venv "$VENV_DIR"
  fi
  # shellcheck source=/dev/null
  source "$VENV_DIR/bin/activate"
fi

python -m pip install -e ".[dev]"
python -m pip install pyinstaller
pyinstaller --noconfirm --windowed \
  --name spsvalidator \
  --icon src/spsvalidator/web/static/img/icon.png \
  --paths src \
  --collect-all packtools \
  --collect-all webview \
  --collect-data spsvalidator \
  --hidden-import pkg_resources \
  --hidden-import requests \
  --hidden-import tenacity \
  --hidden-import langdetect \
  --copy-metadata setuptools \
  src/spsvalidator/main.py
echo "Use linuxdeploy/appimagetool to convert dist/spsvalidator into AppImage."

[samuelveigarangel]

Ao executar o spsvalidator, foi preciso adicionar o argumento --browser pois para executar na interface via python, é preciso instalar algumas dependencias no linux. Como QT ou GTK.

[samuelveigarangel]

Ao executar o programa via browser, é notado que na tela principal há um texto informando que foi compilado para MacOS, mesmo sendo compilado para linux. Talvez seja interessante mudar isso para o sistema local.