Capire il codice di Gaia

Prima di iniziare a fare le proprie modifiche al codice di Gaia è necessario comprendere le nozioni di base sulla struttura di Gaia e quali convenzioni di programmazione utilizzare. Questo articolo descrive entrambi questi aspetti.

Branch di Gaia

Nel codice di Gaia sono presenti differenti branch, e in funzione del tuo obiettivo (o del dispositivo in tuo possesso), potresti non necessariamente scaricare o lavorare sulla branch master. Segue una guida sintetica ai repository principali:

master — l'ultima branch di sviluppo. Potrai utilizzare questa branch se vorrai sviluppare nuove funzionalità (o fissare bug), oppure se vorrai utilizzare l'ultima versione di Gaia sul tuo telefono o emulatore.
v2.1, v2.0, v1.4, ecc. — branch per le versioni di Gaia 2.1, 2.0, 1.4, ecc. Utilizzerai queste branch se vorrai fissare bug per versioni specifiche di Gaia oppure se vorrai sviluppare una App e vorrai essere certo della compatibilità rispetto a versioni specifiche (ad esempio, se utilizzerai i Building Block di Firefox OS vorrai verificare la compatibilità nelle differenti versioni di Gaia).
v1.3t — la versione di Gaia per dispositivi a bassa memoria, quali il Tarako o lo Spice Fire One. Se vorrai sviluppare una app per tali dispositivi, questo è il branch che dovrai utilizzare.

Struttura del codice di Gaia

Questa sezione descrive le parti più importanti del codice di Gaia.

apps/

Questo direttorio contiene tutte le principali applicazioni di Gaia, sia le applicazioni presenti sulla home screen - come il calendar e la camera - che le applicazioni sottostanti - quali l'app di sistema (system app), la home screen, e la tastiera.

Sebbene le app lavorino con modalità leggermente differenti fra loro, tutte hanno un certo numero di caratteristiche in comune, fra cui:

index.html: il file principale di ciascuna app
manifest.webapp: il file di manifesto, definisce la app
locales: le stringhe di localizzazione per quella app
test: test unitari e di integrazione specifici per quella app
js, style: script e stili per quella app
resources: immagini, suoni e altre risorse

Nota: Puoi trovare ulteriori informazioni sulle app di default di Gaia nella guida delle app di Gaia.

build/

Questo direttorio contiene gli script di build.

dev_apps/

Questo direttorio contiene tutte le altre app che si vogliono includere in una build customizzata.

Nota: Per maggiori informzazioni sulla customizzazione di Gaia, leggi la specifica Guida alla customizzazione commerciale.

keyboard/

Questo direttorio contiene dizionari e layout di tastiere in differenti lingue.

locales/

Questo direttorio contiene un file JSON, languages_all.json, che definisce quali lingue sono supportati in Gaia. Per maggiori informazioni sulla localizzazione delle app, leggi la guida di Avvio alla localizzazione delle app.

shared/

Questo direttorio contiene una serie di risorse condivise da più app, fra cui le più importanti sono:

gaia/shared/js: Librerie JavaScript che eseguono funzioni comuni.
l10n.js: Libreria di localizzazione che individua la lingua utilizzata dal dispositivo e sostituisce le stringhe localizzabili con quelle contenute in un file di properties presente nel direttorio locales della app. Le stringhe localizzabili da sostituire sono contenute in elementi con attributi data-l10n-id.
gaia/shared/locales: Risorse di sistema localizzabili in alcune lingue.
gaia/shared/resources: Icone, suonerie e allarmi.
gaia/shared/style: Fogli di stile e altre risorse di stile per oggetti comuni quali pulsanti, barre di avanzamento, barre degli strumenti, schede, ecc
gaia/shared/style_unstable: Risorse di stile instabili o sperimentali.
gaia/shared/test: JavaScript per definire test unitari e di integrazione.

tools/

Questo direttorio contiene strumenti per gli script di build e test.

Stile di programmazione di Gaia

Gaia segue lo stile di programmazione Javascript definito da Google.

Informazioni di base:

Stile di codifica: General practices
Stile di codifica: JavaScript practices
Stile di codifica: Naming and formatting code

Regole specifiche

Assicurati che i file HTML sono dichiarati con <!DOCTYPE html> (come nei documenti HTML5). Se non lo fai, Internet Explorer 9 e successivi caricheranno le pagine in modalità compatibile.
Includi l'istruzione "use strict"; (esattamente così, compresi gli apici) all'inizio del tuo file javaScript per abilitare la modalità strict.
Utilizza sempre due spazi per l'indentazione, piuttosto che il tab.
Per favore utilizza separatori di linea per separare blocchi logici di codice!
I file che hanno nomi con più parole dovrebbero utilizzare il carattere di "underscore" per separare le parole, like_this.js.
Utilizza gli apici singoli invece che doppi per le stringhe.

Utilizza la struttura condizionale estesa:

Bad
if (expression) doSomething();

Correct
if (expression) {
  doSomething();
}

Se stai lavorando sulla system app, leggi la convenzione qui descritta.

Controllo dello stile di programmazione su base commit

Gaia utilizza JSHint per automatizzare i controlli sullo stile di programmazione Javascript prima di ogni commit (sfruttando una funzionalità di git che consente di automatizzarne l'esecuzione).

Lo script di pre-commit gaia/tools/pre-commit verrà copiato nel direttorio .git/hooks di progetto una volta eseguito il comando make.

Nota: Inizialmente utilizzavamo gjslint per controllare lo stile di programmazione, successivamente è stato deprecato a favore di JSHint in quanto permette controlli più stringenti e produce risultati migliori. Stiamo utilizzando JSHint da Firefox OS 1.4, mentre gjslint è unicamente consigliato per quei file che non sono ancora gestiti con JSHint.

Eseguire i controlli manualmente

Prima di sottomettere una patch ti consigliamo di eseguire JSHint manualmente per controllare eventuali errori di stile.

Dovresti guardare nel direttorio gaia/build/jshint per maggiori dettagli sull'utilizzo di JSHint in Gaia; Gaia ti fornisce gli script di build. Puoi eseguire il comando:

$ make lint

per eseguire sia gjslint che jshint. Oppure puoi eseguire:

$ make hint

per eseguire solamente jshint.

Nota: Se vuoi installare JSHint da te stesso, senza utilizzare Gaia, puoi utilizzare i seguenti comandi:

npm install jshint -g
jshint myfile.js