harbour-hermes/docs/BUILD.md

Build: compilazione, test e deploy

1. Prerequisiti SDK

• Sailfish SDK (testato su 5.1.0.11) con target del dispositivo aarch64: SailfishOS-5.0.0.62-aarch64 (Jolla Phone 2026) o equivalente.

• Nel target SDK serve QtMultimedia (registrazione/riproduzione): se pkgconfig(Qt5Multimedia) non è trovato in fase di build, installa il pacchetto devel nel target:

  sfdk tools exec SailfishOS-5.0.0.62-aarch64 zypper install -y qt5-qtmultimedia-devel
  

  (oppure via Qt Creator: Tools → Sailfish OS → Manage targets → Packages, oppure sfdk target install con un RPM locale.)

2. Build e deploy dell'app

cd harbour-hermes
sfdk build          # genera RPMS/
sfdk deploy         # installa sul device collegato

Note:

• Il target è Qt 5.6: il codice del core è scritto per compilare anche lì (niente API Qt > 5.6; per il TTS si usa audio/mpeg di edge-tts).
• Il profilo SailJail è nel rpm/harbour-hermes.desktop (Internet;Audio;Microphone) e deve restare allineato a setOrganizationName("harbour") / setApplicationName("hermes") in main.cpp.
• Al primo uso del microfono Sailfish chiede il consenso al permesso Microphone.

3. Test del core in locale (senza SDK)

Il core (ApiClient, ChatModel, parser SSE, Recorder, Player) si compila anche su desktop con Qt 5.15 per i test:

# Qt desktop (qui: Qt 5.15.2 nel kit locali)
export PATH=<Qt5.15>/gcc_64/bin:$PATH
mkdir -p /tmp/hh-test && cd /tmp/hh-test
qmake /percorso/harbour-hermes/tests/core_test.pro
make -j4

• Unit (parser SSE): ./core-test
• Integrazione live: ./core-test --live richiede un'istanza di prova di hermes-webui su http://127.0.0.1:8899 con password in /tmp/hermes-probe/pw e l'audio di prova in /tmp/hermes-probe/out/prova.ogg (vedi note in tests/core_test.cpp). Il flusso coperto: login → nuova sessione → turno con streaming → TTS → trascrizione.

Nota desktop: se manca libGL.so di sviluppo, creare un symlink libGL.so -> /usr/lib/x86_64-linux-gnu/libGL.so.1 e assicurarsi che core_test.pro punti lì (GLSTUB), oppure lanciare con LD_LIBRARY_PATH puntato alla lib dir di Qt.

Nota desktop 2: Qt5Multimedia richiede libpulse-mainloop-glib.so.0 (pacchetto libpulse-mainloop-glib0, non installato su questo server). Senza sudo si estrae dal .deb:

mkdir -p /tmp/hh-libs && cd /tmp/hh-libs
apt-get download libpulse-mainloop-glib0
dpkg-deb -x libpulse-mainloop-glib0_*.deb ext
export LD_LIBRARY_PATH=/tmp/hh-libs/ext/usr/lib/x86_64-linux-gnu:<Qt>/gcc_64/lib

Esecuzione: ./core-test (unit) e ./core-test --live (integrazione, richiede il probe WebUI su :8899). Esito 12/09/2026: unit 9/9, live completo OK.

4. Tarball per la build da Qt Creator

cd ~/workspace
tar czf harbour-hermes-0.5.3.tar.gz \
    --transform 's,^harbour-hermes,harbour-hermes-0.5.3,' \
    --exclude='.git' harbour-hermes

Lo spec si aspetta la directory harbour-hermes-0.5.3/ (pattern degli altri progetti: cercato in modo robusto anche per i sorgenti live di sfdk).

Traduzioni

Stringhe UI in qsTr() (QML) e tr() (C++). Dopo modifiche alle stringhe:

lupdate -no-obsolete -recursive src qml -ts translations/harbour-hermes-it.ts \
    translations/harbour-hermes-fr.ts translations/harbour-hermes-de.ts

In build CONFIG += sailfishapp_i18n compila i .qm e li installa in /usr/share/harbour-hermes/translations (caricati all'avvio in base alla lingua di sistema).

5. Dipendenze lato server (WebUI)

• /api/transcribe richiede un provider STT attivo sul server (qui: faster-whisper locale — verificato con /api/transcribe/capability).

• /api/tts con engine edge non richiede chiavi API.

• Le voci italiane di edge sono state aggiunte all'allowlist del server (patch a hermes-webui/api/routes.py + test tests/test_italian_voices_tts_allowlist.py): per attivarle riavviare il servizio WebUI (sudo systemctl restart hermes-webui).

• Per una dettatura italiana corretta impostare in ~/.hermes/config.yaml:

  stt:
    provider: local
    local:
      model: base
      language: it
  

  (senza, whisper può tradurre/maltrascrivere l'italiano). Richiede il riavvio del WebUI.