Client desktop

Installazione

Il client desktop è un'applicazione nativa disponibile per Windows, macOS (Apple Silicon) e Linux. Gli installer per Windows, macOS e Linux includono anche la CLI uversion e la rendono accessibile. Scaricalo da /downloads.

Windows

Scarica uVersion_x.y.z_x64-setup.exe (installer NSIS firmato, ~25 MB). All'avvio, l'installer:

• Installa il client in %LOCALAPPDATA%\uVersion (per utente, senza bisogno di admin)
• Aggiunge la cartella di installazione al PATH utente (la CLI uversion.exe è inclusa lì)
• Crea un collegamento nel menu Start
• Attiva l'auto-update tramite l'updater di Tauri

Windows in parco macchine: l'MSI

Per distribuire su molte postazioni con uno strumento di gestione del parco (Intune, SCCM, criteri di gruppo...), usa l'MSI anziché l'installer NSIS: uVersion_latest_x64_en-US.msi (URL stabile, sempre l'ultima versione, ~10 MB). Installazione silenziosa, per macchina:

msiexec /i uVersion_latest_x64_en-US.msi /qn /norestart

• Installa in C:\Program Files\uVersion (richiede diritti di amministratore). La CLI uversion.exe è inclusa, ma la cartella non viene aggiunta al PATH: se i tuoi utenti la vogliono nel terminale, falla aggiungere dallo strumento di distribuzione.
• Nessun auto-update su un'installazione MSI: il client resta alla versione distribuita e gli aggiornamenti del parco avvengono ridistribuendo l'MSI successivo. È voluto: l'updater integrato installerebbe una seconda copia, per utente, accanto a quella gestita.
• Disinstallazione silenziosa: msiexec /x uVersion_latest_x64_en-US.msi /qn

Alla prima apertura, ogni utente inserisce l'indirizzo del server e convalida l'impronta del certificato, una volta per utente e per postazione (vedi Impronta TLS).

macOS (Apple Silicon)

Scarica uVersion_x.y.z_macos-arm64.app.zip (~32 MB, firmato con Developer ID e notarizzato da Apple). Doppio clic per decomprimere, poi trascina uVersion.app in /Applications. Al primo avvio, Gatekeeper convalida automaticamente la notarizzazione, senza alcun avviso.

La CLI uversion è inclusa nell'app. Al primo avvio, il client crea automaticamente un collegamento simbolico verso ~/.local/bin/uversion e aggiunge ~/.local/bin al tuo PATH tramite ~/.zprofile: nessuna azione manuale richiesta. Apri un nuovo terminale e uversion è disponibile.

Nota: è supportato solo Apple Silicon (M1/M2/M3/M4). Nessun binario Intel.

Linux

Un solo formato per x86_64: l'AppImage (uVersion_x.y.z_amd64.AppImage, ~85 MB). Portatile, include le sue dipendenze (libwebkit2gtk, libgtk, libsoup, ecc.) e funziona su qualunque distribuzione recente senza installazione di sistema. Prerequisiti: Ubuntu 24.04 o superiore, Debian 13 o superiore, oppure una distribuzione di una generazione equivalente. Il binario richiede una libreria C di sistema recente, e l'AppImage non abbassa questa soglia: include l'ambiente grafico, non la libreria C.

La via consigliata è lo script di installazione. Senza sudo:

curl -fSL https://uversion.io/downloads/client/install.sh | sh

Non fa nulla di magico, e soprattutto nulla che richieda diritti:

• si rifiuta di girare come root, su un'architettura diversa da x86_64, o su un sistema troppo vecchio per eseguire il binario, indicando quale dei tre è il problema;
• scarica l'AppImage in ~/Applications/uVersion.AppImage, verifica che ciò che è arrivato sia davvero un eseguibile Linux (altrimenti un captive portal o una pagina di errore verrebbero salvati e resi eseguibili, per poi fallire più tardi in modo incomprensibile), quindi la mette in posizione in un solo gesto, cosa che resta sicura anche se una copia è già in esecuzione;
• avvia l'applicazione. È questo avvio a creare la voce nel menu delle applicazioni, quindi è meglio lasciarlo fare. In una sessione remota senza interfaccia grafica, mostra invece il comando esatto da digitare dal tuo desktop.

Puoi anche scaricare l'AppImage a mano dalla pagina di download, renderla eseguibile e avviarla:

chmod +x uVersion_x.y.z_amd64.AppImage
./uVersion_x.y.z_amd64.AppImage

Non esiste un pacchetto .deb per il client, e non ce ne sarà: un pacchetto installato da dpkg può aggiornarsi solo ripassando da dpkg, quindi con un'elevazione di privilegi a ogni versione, cosa impossibile per una postazione senza diritti di amministratore. L'AppImage si sostituisce da sola, senza password. Il server, invece, mantiene il suo pacchetto .deb.

Nota: la CLI uversion è inclusa nell'AppImage. Al primo avvio, il client copia il binario in ~/.local/bin/uversion e aggiunge ~/.local/bin al tuo PATH tramite ~/.profile (nessuna azione manuale richiesta). La voce nel menu delle applicazioni viene creata al primo avvio, per la stessa ragione: un AppImage è un file, non un'installazione.

Primo avvio

1. Indicare l'indirizzo del server e le tue credenziali

Al primo avvio, il client mostra la pagina di login, intitolata Welcome to uVersion. Il campo Server address non si aspetta un URL completo: è suddiviso in tre blocchi, un prefisso https:// non modificabile, la macchina e la porta (8443 per impostazione predefinita). Lo schema è imposto, il client non può produrre un http://. Incollare un indirizzo completo o un host:port nella casella della macchina lo distribuisce automaticamente tra i due campi. Poi inserisci Username e Password, quindi Sign in.

2. Verificare l'impronta del server, una sola volta

Poiché un server uVersion è autofirmato per impostazione predefinita, la primissima connessione a una data macchina mostra Verify server identity: confronta l'impronta SHA-256 con quella che ti ha dato il tuo amministratore, poi clicca su Trust this server. La domanda viene posta una sola volta per server, e se ritorna sotto il titolo rosso Server identity changed, l'impronta è cambiata: non accettare senza verificare. Vedi Impronta TLS.

Una volta connesso, il client memorizza la tua sessione in modo sicuro. La CLI uversion e i plugin editor (Unreal, Rider) riutilizzano automaticamente le stesse credenziali: non reinserisci la password da nessun'altra parte.

Aprire o clonare un repository

Connettersi non apre alcun progetto: l'elenco dei repository si richiede esplicitamente. È la stessa finestra che serve a clonare un progetto per la prima volta e a riaprire un workspace già presente sul disco.

1. Aprire la finestra Open Repository

Finché nessuna tab è aperta, il Workspace mostra No repository selected e un pulsante Open Repository. Una volta che hai almeno una tab, la stessa schermata si ottiene con il + della barra delle tab. La finestra elenca, una scheda per progetto, i repository a cui hai accesso, con un pulsante Refresh per richiedere di nuovo l'elenco al server.

2. Clonare, o riaprire un workspace esistente

Ogni scheda propone l'azione corrispondente al suo stato:

• Clone: crea un workspace nuovo. Il campo Workspace name della scheda dà il nome alla cartella creata, e riprende il nome del progetto se lasciato vuoto. Il selettore di cartella che segue chiede la cartella genitore: la sottocartella la crea uVersion stesso.
• Clone New: lo stesso pulsante, rinominato quando esiste già un workspace per questo progetto. Clonare una seconda volta è legittimo, per esempio per tenere due stati del progetto affiancati.
• Open: riapre un workspace già clonato su questa macchina, il cui percorso è richiamato sotto la scheda. Switch to Open Tab appare al suo posto quando la tab è già aperta.
• Open Local Repository..., in basso nella finestra: punta a una cartella che contiene già un .uversion/, per esempio dopo aver spostato un workspace.

La casella Download files after clone, in basso, è spuntata per impostazione predefinita e avvia il download subito dopo il clone. Deselezionala per creare il workspace ora e recuperare i file più tardi.

3. Seguire il download

La finestra si chiude non appena il clone parte, ed è voluto: il trasferimento può durare ore e non deve bloccarti. L'avanzamento continua nell'intestazione del client, la tab del workspace si apre da sola alla fine, e un'interruzione di rete non perde nulla poiché il trasferimento riprende da solo.

Workspace

Un workspace è una cartella locale collegata a un repository del server. Il client può gestire più workspace contemporaneamente, mostrati nella barra delle tab in alto. Ogni workspace archivia i suoi metadati in .uversion/ alla radice della cartella locale:

• .uversion/config.toml: l'unico file davvero importante. La sua sezione [workspace] porta il proprietario del workspace (owner), il suo identificatore, il suo nome, e last_synced_revision, la revisione a cui sei sincronizzato (non c'è nessun file .last_sync). È anche lì che viene memorizzato il percorso del motore Unreal.
• .uversion/checkouts_<workspace_id>.json: i lock che TU detieni in questo workspace
• .uversion/changelists_<workspace_id>.json: le tue changelist, cioè pacchetti di file riservati che raggruppi per inviarli separatamente. Puramente locale, mai trasmesso al server.
• .uversion/pending_deletes_<workspace_id>.json: le eliminazioni in attesa di invio
• .uversion/snapshots.json: lo stato noto dei file, che serve a individuare ciò che hai modificato localmente

Tab Files

Vista ad albero dei file del workspace con il loro stato. Due modi per ridurre l'elenco:

• Il campo di ricerca, intitolato Search files...: filtra su una porzione del percorso, senza distinguere maiuscole e minuscole.
• I chip di stato, proprio sotto. Sono contatori cliccabili, e un chip appare solo se il suo contatore supera zero: su un workspace appena sincronizzato, vedrai quindi solo {n} synced, e l'assenza degli altri è normale. I sei chip possibili sono {n} synced, {n} modified, {n} local only, {n} server only, {n} locked e {n} deleted.

Ricerca e chip si combinano: la ricerca restringe prima, i chip filtrano poi. La vista resta fluida anche su progetti da diverse decine di migliaia di file.

Selezione multipla + azioni

La barra delle azioni esiste solo se qualcosa è selezionato. Finché la selezione è vuota, non c'è alcun pulsante: è normale, non è un caricamento in corso. Seleziona dei file (clic + shift, o le caselle) e la barra appare, preceduta dal numero selezionato ({n} file(s) selected). I pulsanti compaiono a seconda di ciò che la selezione consente:

Tab Pending

File attualmente in checked-out, locked da te O da un altro utente. Due sezioni:

• Your locks: puoi fare checkin, revert, o release singolarmente
• Other users' locks: vedi chi possiede il lock + un pulsante Request release che crea una scheda di richiesta nel board Production (un badge request)

Gli admin vedono anche un pulsante Force unlock sui lock altrui, che fa release del lock senza il consenso del detentore. Ogni force unlock viene registrato nell'audit.

Tab History

Elenco paginato dei commit del repository, con autore, data, messaggio e file modificati. Cliccare su un commit apre il dettaglio: la lista completa dei file del commit con le loro revisioni.

Pulsante Get all su ogni commit per scaricare una copia locale di tutti i file a quella revisione (utile per recuperare uno stato stabile).

Production

La zona Production (una voce dedicata nella barra laterale) raggruppa il monitoraggio del progetto, per repository. Il Workspace, dal canto suo, si concentra sui file (Files, Pending, History).

My tasks

L'elenco delle schede assegnate a te, aggregato su tutti i repository a cui hai accesso.

Board

Board kanban per repository, con colonne configurabili (per impostazione predefinita To Do, In Progress, Review, Done). Ogni scheda porta una priorità (low / normal / high / urgent), label, assegnatari, una scadenza, commenti, link ad asset o commit, e un'immagine di copertina.

Dashboard

La cabina di regia del producer: una fascia di salute del progetto (bloccanti aperti, report di playtest in attesa), le zone che concentrano i problemi, i commit della settimana, il peso del progetto e l'ultima build pubblicata, con ogni blocco che rimanda al board o a Games.

Sotto, la timeline a calendario: milestone, playtest (una tantum o ricorrenti), release e scadenze di schede. Un playtest ricorrente genera automaticamente la sua scheda di board a ogni occorrenza.

Watchlist

Sorveglia dei percorsi (pattern glob) per essere avvisato dei check-in che li toccano. Ogni voce precisa il percorso sorvegliato e gli eventi seguiti.

Games

La zona Games elenca le build di playtest interne pubblicate per il progetto. Ogni build indica la sua versione, la sua configurazione (DebugGame / Development / Shipping), la sua piattaforma (Win64 / Mac / Linux), la sua dimensione e le sue note di versione, con un pulsante di download adatto alla piattaforma.

È il punto di accesso dei playtester: un account con il ruolo playtester vede solo questa pagina (né Workspace né Production), e accede solo alle build dei progetti che gli sono aperti.

Changelist locali

Raggruppa i tuoi checked-out file in più commit indipendenti. Le changelist sono locali al tuo workspace (mai inviate al server). Utile per:

• Separare un fix critico da un lavoro in corso
• Preparare più invii in parallelo senza mescolare tutto
• Tenere una changelist "default" per i WIP e una "review" per ciò che va in checkin

Settings

Preferenze globali del client (salvate in %APPDATA%/uversion/uVersion/config/config.toml):

Pannello Unreal

Quando il client rileva un progetto Unreal nel workspace, una barra di azioni dedicata appare in alto a destra del Workspace. Pilota il motore direttamente dal client: aprire l'editor, compilare, pacchettizzare, senza passare per un IDE. La maggior parte delle azioni riguarda solo i progetti C++ (un progetto Blueprint puro non ha bisogno di compilare).

La pastiglia di stato del plugin

All'estrema sinistra della barra, una pastiglia indica a che punto è il plugin Unreal per questo progetto. È cliccabile:

Percorso del motore

Il percorso di installazione di Unreal viene risolto automaticamente a partire dall'EngineAssociation del .uproject (registro di Windows, LauncherInstalled.dat, o build da sorgenti). Questo percorso è richiesto per tutte le azioni qui sotto, e la risoluzione automatica fallisce in particolare su un motore compilato dai sorgenti. Ecco dove impostarlo a mano.

1. Aprire il menu delle azioni secondarie

Non c'è né campo di inserimento, né pulsante Browse, né pulsante Auto-detect visibile nella barra. L'unico punto di ingresso è il pulsante a forma di ingranaggio, all'estrema destra della barra Unreal, accompagnato da un piccolo chevron e il cui tooltip dice More actions. Nulla nel suo aspetto parla del motore, ed è per questo che non lo si trova.

2. Scegliere Set Engine Path...

La voce Set Engine Path... è l'ultima del menu. Il suo sottotitolo mostra il percorso corrente, o Not configured se non ce n'è nessuno: è il modo più rapido per sapere se il problema viene da lì. Si apre un selettore di cartella, e il percorso scelto viene salvato nel .uversion/config.toml del workspace.

Open Editor

Avvia l'editor Unreal (UnrealEditor) sul progetto del workspace. Il pulsante è idempotente: l'editor può metterci diverse decine di secondi a mostrare la sua finestra (soprattutto su macOS / Linux), quindi un secondo clic durante quel tempo non apre una seconda istanza. Il pulsante mostra «Opening…» finché l'editor si avvia. Per un progetto C++ mai compilato localmente, aprire l'editor innesca prima una generazione dei file di progetto e poi una compilazione (vedi Azioni automatiche).

Compile

Compila il progetto (Unreal Build Tool). L'output viene mostrato in tempo reale in una console integrata. Un progetto C++ deve essere compilato perché l'editor possa aprirlo e per riflettere le modifiche al codice.

Sync e Status

Questi due pulsanti vivono nella stessa barra, e non nella tab Files:

• Sync: aggiorna tutto il workspace dal server. Il suo tooltip indica il numero di file in attesa quando ce ne sono. È il vero «sync» del client, da non confondere con il pulsante Download della tab Files, che riporta solo la selezione.
• Status: aggiorna lo stato lato server, lock degli altri utenti compresi, e riaggiorna il contatore del pulsante Sync.

Il menu More actions

Le azioni più rare sono raggruppate dietro il pulsante a forma di ingranaggio, a destra della barra (schermata qui sopra):

• Generate Project Files: rigenera i file di progetto dell'IDE (Visual Studio, Rider). Utile dopo aver aggiunto o rimosso file sorgente, o dopo un clone.
• Publish Editor Binaries: compila, poi pubblica i binari dell'editor corrispondenti all'ultimo commit di codice. I tuoi colleghi li recuperano al sync invece di ricompilare ciascuno per conto proprio. Assente su Linux.
• Force Sync: riscarica sovrascrivendo i tuoi file locali. Segnalato in rosso nel menu, con la dicitura overwrites local, e preceduto da una conferma. Da riservare ai workspace che si accetta di perdere.
• Set Engine Path...: l'impostazione del percorso del motore, descritta sopra.

Package

Il pulsante si chiama Package; «Package Game» è solo il suo tooltip, sostituito da Set Engine Path first quando il percorso del motore manca, con il pulsante allora disattivato. Pacchettizza il gioco tramite RunUAT BuildCookRun e archivia il risultato in Packages/{config}/ alla radice del workspace. Tre configurazioni a scelta:

La cartella Packages/ è ignorata per impostazione predefinita (.uversionignore): i pacchettizzati non sono versionati, si distribuiscono tramite Publish Build.

Publish Build

Pubblica una build pacchettizzata come versione di playtest interna. Diventa scaricabile dal tuo team dalla pagina Games del client (ruolo playtester o accesso alla build concesso). Il client scansiona Packages/{config}/, invia i file (deduplicati lato server) poi registra il manifesto.

Open project folder

Apre la cartella del workspace nell'esplora file del sistema (Esplora file di Windows, Finder, o xdg-open su Linux).

Stop

Interrompe in modo pulito tutte le build in corso: compilazione e pacchettizzazione. Il pulsante indica quante build sono state fermate (una compilazione automatica avviata in background può esservi conteggiata).

Azioni automatiche

Oltre ai pulsanti, il client innesca certe azioni Unreal da solo, affinché un progetto C++ resti sempre aggiornato e compilabile:

• Prima di un check-in: se dei file di codice sono cambiati, il progetto viene compilato prima. Se la compilazione fallisce, il check-in è bloccato (non si sottomette codice che non compila).
• Dopo un sync: se il sync ha scaricato del codice, il client rigenera i file di progetto poi ricompila.
• Al primo avvio dopo un clone (progetto C++): generazione dei file di progetto poi compilazione, prima di poter aprire l'editor.

Queste build automatiche si serializzano sul lock del motore (Unreal Build Tool -WaitMutex): non si rifiutano a vicenda, si incatenano. Il pulsante Stop interrompe anche queste.