Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

Modificando o Gaia

Esta página é destinada para os desenvolvedores do Gaia, se você está procurando como compilar e rodar o Firefox Os, você deveria consultar a página Compilando e Instalando o Firefox OS.

Gaia é uma coleção de web apps que compõem a interface do Firefox OS. Tudo que você vê na tela do Firefox OS é construido sobre tecnologias web abertas. Isto inclui a tela inicial e todas as aplicações padrões.

Pegando o código fonte

Para pegar o código fonte do Gaia, faça o fork no GitHub e depois clone seu fork utilizando o git.

$ git clone https://github.com/mozilla-b2g/gaia.git

Rodando o Gaia

Você pode rodar o Gaia no B2G Desktop, no Firefox ou em um aparelho compatível.

B2G desktop

B2G desktop é uma compilação do aplicativo runtime usado nos dispositivos Firefox OS o qual você pode executar o Gaia no seu computador desktop.

Você pode baixar a imagem nightly do B2G desktop aqui. Dependendo de qual versão você deseje, você pode querer uma versão específica do latest-mozilla-b2g18. Existems imagens para Linux (32 bit and 64 bit), Mac OS X e Windows.

Imagens Nightly vem empacotadas com a versão mais recente do Gaia. Uma vez que você baixou o arquivo, tudo que você precisa é extrair para um diretório e executar o binário b2g,

Nota: Imagens para Linux 64-bit não funciona em algumas distros, veja o bug bug 812484. Se você tiver esse tipo de problema tente a versão 32-bit.

$ cd b2g
$ ./b2g

Para executar o B2G com sua própria versão do Gaia para propósitos de desenvolvimento, primeiramente você precisa construir um perfil do seu clone:

$ cd /path/to/gaia
$ DEBUG=1 DESKTOP=0 make

Isso irá gerar um subdiretório no seu diretório gaia chamado profile. A parte DEBUG executa Gaia como aplicação hospedada no servidor web interno, ao invés do pacote padrão de aplicativos que você tem que reempacotar a cada mudança. Você pode encontrar o caminho para o diretório profile observando a última linha da saída do comando acima. Algo parecido como:

Profile Ready: please run [b2g|firefox] -profile /path/to/gaia/profile

Então você pode executar o B2G Desktop com o perfil gerado dessa forma:

$ ./b2g /path/to/gaia/profile

Se você quiser você pode compilar seu próprio B2G desktop a partir do fonte.

Nota : No Mac OS X, o bintário b2g estará dentro de B2G.app. Você precisa rodar dessa forma:

./B2G.app/Contents/MacOS/b2g /path/to/gaia/profile

Usando o Gaia no Firefox

Também é possível executar o Gaia dentro do Firefox. Isso dá a vantagem de ter um ciclo de desenvolvimento rápido, bem como a utilização de ferramentas padrões de desenvolvimento web e depuração. Veja Guia rápido para desenvolvimento Gaia para maiores detalhes.

Usando um dispositivo Gaia

Se você possui um dispositivo compatível você também pode executar o Gaia fazendo um flash do Firefox OS. Você pode fazer um flash de uma versão compatível do Gaia com sua versão atual do Firefox OS, veja a seção Carregar no dispositivo, ou você pode compilar sua própria versão do Firefox OS. Nós também temos documentação de como testar o Firefox OS.

Teste unitários

Veja o artigo Testes unitários do Gaia para saber como criar e executar testes para o Gaia.

Registrando bugs

Bugs são registrado no Bugzilla em Firefox OS > Gaia. Registre um novo bug no componente Gaia (ou em algum do seus subcomponentes).

Contribuindo com o Gaia

Mozilla depende de contribuições da comunidade open source para ajuda no desenvolvimento de aplicativos Gaia e adoraríamos que você se envolvesse.

Alguns dos locais para encontrar alguns bugs para se trabalhar:

Estilo de codificação básica

  • Background:
  • Certifique-se que os arquitos HTML possuem <!DOCTYPE html> (ou seja, são documentos HTML5). Se não fizer isso, o Internet Explorer 9 e anteriores vão carregá-lo em modo de compatibilidade.
  • Inclua o comando"use strict"; (exatamente assim, com aspas) no início do seus arquivos JavaScript para colocá-lo em modo strict.
  • Sempre use dois espaços para identação ao invés de tabs.
  • Por favor utilize quebras de linhas para separar blocos lógicos do código!
  • Utilize underscore "_" para separar as palavras em nomes de arquivos e diretórios, por exemplo: like_this.js.
  • Utilize apóstrofo no lugar de aspas para strings.

Regras adicionais

Ruim:

if (expression) doSomething();

Correto:

if (expression) {
  doSomething();
}

Se você está trabalhando um aplicativo de sistema, verifique o guia listado aqui.

Antes de submeter uma correção nós recomendamos você executar gjslint para verificar algum erro no estilo:

gjslint --nojsdoc my_file.js

Submetendo uma correção (patch)

Primeiramente assinale o bug para você no Bugzilla, você precisará de uma conta no Bugzilla.

Então crie um branch no seu fork do Gaia:

$ git branch branchname
$ git checkout branchname

Faça um commit das suas alterações:

$ git add /file/to/add
$ git commit -m "Bug XXXXX - Fix the broken Gaia and save the world"

Carregue seu branch:

$ git push origin branchname

Envie um pull request navegando no branch do seu fork no GitHub e encontre o botão "Pull Request".

Nota: Exceto em circunstâncias não usuais, correções devem ser carregadas primeiro no master branch, não em um release branch como v1-train, v1.3, etc. Se você precisa carregar em um release branch, deve-se seguir um processo de aprovacão descrito em B2G Landing wiki page.

Para requerer uma revisão de sua correção, inclua o pull request ao bug no Bugzilla, referenciando a URL do pull request  e configurar a flag review ("r") para "?" e informar o ID Bugzilla de um dos donos dos modulos ou um de seus pares (isso é muito importante - caso contrário, seu erro provavelmente não será visto por ninguém). O Github pode ser configurar para extensão do bugzilla o que pode ajudar a automtizar o processo automaticamente criando um anexo e adicionando-o ao bug, mas você ainda precisará configurar o flag de revisão no Bugzilla.

O revisor pode pedir a você para fazer algumas alterações, você pode necessitar corrigir o commit original e forçar uma carga para o branch/pull request original. Uma vez que eles estiverem satisfeitos com sua correção, eles podem fazer um merge ao master branch para você. Antes de fazer isso eles podem preferir registrar todas as suas alterações em um único commit e assim sua contribuição fica facilmente rastreável.

Quem for fazer o merge do commit (normalmente um revisor) adicionará um flag  r= nos comentários do commit.

Opções do Make

Você usa o comando make dentro do repositório Gaia para criar o perfil Gaia que pode ser carregado no seu dispositivo ou na imagem de um B2G Desktop. Essa seção mostra em detalhes as diferentes opções disponíveis do make.

Existem muitas variáveis de ambiente presentes no Makefile. Independente delas poderem ser removidas no futuro.

Os perfis criados são armazenados em /gaia/profile, e contém os seguintes itens:

  • defaults: Diretório que contem configurações padrão para ser recarregado depois que você fizer um reset no telefone.
  • extensions: Diretório contendo as extensões.extensions.
  • settings.json: Arquivo de configurações.
  • user.js: Outro arquivo contendo mais configurações e preferências.
  • webapps: Diretório contendo todos os aplicativos web que serão instalados no seu telefone.

Nota: Quando você já criou um perfil e gostaria de fazer um novo, você deve apagar o diretório de perfil existente antes de tentar gerar um novo.

Padrão

make

Isso simplesmente gera uma imagem sem rótulo e sem possibilidade de depuração. Para uma imagem com ródulo você precisa usar make com o rótulo oficial Mozilla; para uma imagem com depuração use make com depuração.

Carregar no dispositivo

make install-gaia

make reset-gaia

make profile

Com a configuração do ADB (Android Debug Bridge), esses makes copiarão o Gaia para o dispositivo. install-gaia irá copiar as atualizações do Gaia do seu diretório de trabalho para o dispositivo. reset-gaia limpará toda configuração existente, perfis, aplicativos e banco de dados (um novo conjunto de banco de dados será inicializado) antes de copiar o Gaia.

Compilando aplicativos específicos

APP=system make

APP=system make install-gaia

Quando um perfil existe, APP permite você especificar quais aplicativos serão empacatodas ao invés de empacotar todos os aplicativos Gaia.

Diretório de perfil personalizado

Você pode especificar um diretório personalizado para compilar seu perfil, usando PROFILE_FOLDER, por exemplo:

PROFILE_FOLDER=profile-b2g-desktop make

Compilações para diferentes dispositivos

Há algumas opções do make para criar compilações para diferentes dispositivos com diversos propósitos.

Criando uma compilação Gaia para Telefone

GAIA_DEVICE_TYPE=phone make

Essa compilação pega os aplicativos do diretório /gaia/build/config/phone/apps-engineering.list.

Criando uma compilação Gaia para Tablet

GAIA_DEVICE_TYPE=tablet make

Essa compilação pega os aplicativos do diretório /gaia/build/config/phone/apps-engineering.list.

Tipos diferentes de compilação

Há algumas opções de make que criam diferentes tipos de compilação, com finalidades diferentes.

make production

PRODUCTION=1 make

Isso cria uma imagem de produção do Gaia:

  • Gaia é executado como um pacote de aplicativos, que são difíceis de depurar, mas é o melhor estado disponível para as aplicações em termos de permissões disponíveis para API, etc.
  • Teste de aplicativos não estão incluídos na imagem
  • Depuração remota é desabilitada por padrão
  • Tela de bloqueio foi ativada (que por sua vez vai cortar ligações USB)
  • Marionette é desligado
  • Experiência de primeiro uso é ligada
  • Cache offline é usado

Nota: Você também pode usar o alias make production.

make com depuração

DEBUG=1 make

A variável DEBUG executa o Gaia como um aplicativo hospedado no servidor interno numa GAIA_PORT específica, ao invés de aplicativos empacotados, como é no padrão, que é necessário reempacotar depois de cada alteração. Isso torna as coisas mais fáceis para testar. Lançamento do perfil com o mais recente Firefox Nightly também lhe dará bons painéis específicos B2G sobre as Ferramentas de Desenvolvedor Firefox.

E mais:

  • Teste de aplicativos incluído na imagem.
  • Depuração remota habilitada por padrão.
  • Bloqueio de tela desabilitada (Conexões USB não são interrompidas).
  • Marionette habilitado, o que é necessário para executar testes unitários do Gaia.
  • Experiência de primeiro uso é desabilitadada.
  • Cache Offline não é usado, nem memsmo é gerado.

make com depuração do dispositivo

DEVICE_DEBUG=1 make

Isso desabilita a tela de bloqueio no dispositivo, e habilita a depuração com a ferramenta ADB, isso é muito útil para a depuração do dispositivo.

No Firefox OS versão 1.2 e superiores, utilize esse parâmertro quando você quer depurar aplicativos web com o App Manager.

make com depuração desktop

DEBUG=1 DESKTOP=0 make

Essa opção cria a versão de depuração do desktop para rodar no B2G desktop.

make com o rótulo oficial Mozilla

MOZILLA_OFFICIAL=1 make

Use para criar uma imagem com o rótulo oficial Mozilla.

make Dogfood

DOGFOOD=1 make

Opções Dogfooding e utilitários são habilitados, por exemplo, aplicativo Feedback, que for example the Feedback app, que permite "Dog fooders" facilmente enviar feedbacks do sistema operacional.

make System apps

B2G_SYSTEM_APPS=1 make

Essa variável de ambiente permite você enviar um aplicativo para /system/b2g ao invés de /data/local. Você deve usar isso  quando trabalha com uma imagem do usuário. Essa variável é automaticamente selecionada quando executar make production. Isso pode ser usado para install-gaia ou reset-gaia.

Compilação para Distribuição e personalização de mercado

GAIA_DISTRIBUTION_DIR=./dir

Note: Read Personalização de Mercado para maiores detalhes.

Opções para desenvolvimento/depuração

Também existem opções para adicionar ou remover recursos ou modificar configurações para facilitar a depuração.

Habilitar depuração remota

REMOTE_DEBUGGER=1

Isso habilita a depuração remota no dispositivo, o mesma opção usada emThis enables remote debugging on the device, the same as using the option in the Configurações do Desenvolvedor.

make otimizção do JavaScript

GAIA_OPTIMIZE=1 make

Isso dispara a otimização no JavaScript do Gaia, concatenando/comprimindo os arquivos. Isso é automaticamente configurado quando é executado make production. Também pode ser usado para install-gaia ou reset-gaia.

Ativos de imagem de alta resolução

GAIA_DEV_PIXELS_PER_PX=1.5 make

Quando empacota o aplicativo, essa opção substitui as imagens com seus arquivos equivalentes *@1.5x.(gif|jpg|png) se existirem. Você precisar usar a opção acima como parte do comando make padrão, por exemplo:

GAIA_DEV_PIXELS_PER_PX=1.5 make reset-gaia

GAIA_DEV_PIXELS_PER_PX=1.5 make install-gaia

Atualmente o Gaia é gerado com as seguintes resoluções de tela:

  • qHD: ~540×960; device pixel ratio = 1.6875
  • WVGA: ~480×800; device pixel ratio = 1.5
  • HBGA (320x240); device pixel ratio = 1

Use GAIA_DEV_PIXELS_PER_PX para certificar-se que as imagens fiquem visíveis em dispositivos qHD and WVGA. Veja o artigo Um pixel não é um pixel para mais informações sobre pixels de dispositivos por pixels de css.

Compilação de perfil com pouca memória

GAIA_MEMORY_PROFILE=low make

Essa variável gera um perfil do Gaia com pouca memória, destinado a dispositivos com pouca memória como o Tarako.

Recursos Haida

HAIDA=1 make reset-gaia

Essa compilação habilita o conjunto de recursos Haida, que atualmente é limitado aos gestos rocketbar e edge, mas provavelmente incluirão outros recursos num futuro próximo.

Desabilitar Experiência do primeiro uso (FTU - First Time Use)

NOFTU=1

Desabilte o FTU com essa variável de ambiente.

Desabilitar a tela de bloqueio

Você pode desabilitar a tela de bloqueio usando a opção NO_LOCK_SCREEN, por exemplo:

NO_LOCK_SCREEN=1 make

Carga de trabalho de referência

Possibilita desenvolvedores e testadores instalar uma grande quantidade de dados em diversos aplicativos, tipicamente em um telefone recém formatado.

Os comandos são (a patir do diretório gaia):

make reference-workload-light
  • 200 contatos
  • 200 mensagens SMS
  • 50 ligações
  • 20 images na galeria
  • 20 músicas
  • 5 vídeos
make reference-workload-medium
  • 500 contatos
  • 500 mensagens SMS
  • 100 ligações
  • 50 images na galeria
  • 50 músicas
  • 10 vídeos
make reference-workload-heavy
  • 1000 contatos
  • 1000 mensagens SMS
  • 200 ligações
  • 100 images na galeria
  • 100 músicas
  • 20 vídeos
make reference-workload-x-heavy
  • 2000 contatos
  • 2000 mensagens SMS
  • 500 ligações
  • 250 images na galeria
  • 250 músicas
  • 50 vídeos

Essas metas aceitam a variável de ambiente APP, ou a variável APPS que deve conter os nomes das aplicações separados por espaço, ou seja:

APP=sms make reference-workload-light
APPS="sms communications/contacts" make reference-workload-heavy

Os aplicativos disponíveis são:

APPS="gallery music video communications/contacts sms communications/dialer"

Com o objetivo de insatalar músicas com cargas de trabalho de referência o utilitário mid3v2 deve ser instalado. Esse utilitário pode ser instalado com:

sudo apt-get install python-mutagen

Se você estiver executando Fedora ou RHEL, use:

sudo yum install python-mutagen

make documentação

A documentaão do Gaia pode ser gerada via jsdoc3. Para gerar isso, utilize o seguinte comando:

make docs

Habilitando layout IME e dicionários

Para habilitar o layout de teclado IME e os dicionários, use a seguinte estrutura de comando:

GAIA_KEYBOARD_LAYOUTS=en,zh-Hant-Zhuyin,el,de,fr,zh-Hans-Pinyin make

Padronizando os aplicativos em tempo de compilação

Os aplicativos que são executados no Firefox OS ficam todos na árvore de fontes do Gaia, nas seguintes posições:

  • gaia/apps: Aqui é onde os aplicativos padrão do sistem são encontrados, como: calendar, email, settings, etc.
  • gaia/external-apps: Nesse diretório fica o aplicativo Firefox Marketplace (marketplace.firefox.com), e onde são armazenados os aplicativos instalados pelo usuário.
  • gaia/showcase-apps: Ficam os aplicativos showcase, por exemplo: 3D Crystal Skull para mostrar a performance WebGL do dispositivo.
  • gaia/test-apps: Esse diretório é um repositório para testes simples, desenhado para testar recursos simples do B2G.
  • gaia/external-apps: Esse This diretório contém mais testes.
  • Existem outros também, dependendo da versão do Gaia que você clonou.

Nota: Se você está compilando o B2G ao invés do Gaia, os diretórios são precedidos pelo B2G/, por exemplo: B2G/gaia/apps e B2G/gaia/external-apps.

Se você quiser omitir alguns desse aplicativos de sua imagem do Gaia/B2G, você pode fazer isso de diferentes maneiras:

  1. O método "força bruta" no qual você simplesmente apaga os aplicativos que você não quer que estejam presentes antes de iniciar a compilação.

  2. O método mais refinado de fazer isso é editar os arquivos gaia/build/config/device-type/apps-*.list onde device-type pode ser phone, tablet ou tv, para incluir os aplicativos que você quer incluir em tempo de compilação. Por exemplo, gaia/build/config/apps-production.list vai parecer mais ou menos como isso:

    apps/*
    external-apps/*
    outoftree_apps/*

    Mas você pode também incluir aplicativos específicos ao invés de apenas pegar todos, por exemplo:

    apps/clock

    O mecanismo para escolher qual arquivo apps-*.list é usado durante a compilação está contido em gaia/Makefile:

    GAIA_APP_TARGET?=engineering
    ...
    ifeq ($(MAKECMDGOALS), demo)
    GAIA_DOMAIN=thisdomaindoesnotexist.org
    GAIA_APP_TARGET=demo
    else ifeq ($(MAKECMDGOALS), dogfood)
    DOGFOOD=1
    else ifeq ($(MAKECMDGOALS), production)
    PRODUCTION=1
    endif
    ...
    ifeq ($(PRODUCTION), 1)
    GAIA_OPTIMIZE=1
    GAIA_APP_TARGET=production
    endif
    
    ifeq ($(DOGFOOD), 1)
    GAIA_APP_TARGET=dogfood
    endif
    ...
    ifndef GAIA_APP_CONFIG
    GAIA_APP_CONFIG=$(GAIA_DIR)$(SEP)build$(SEP)config$(SEP)$(GAIA_DEVICE_TYPE)$(SEP)apps-$(GAIA_APP_TARGET).list
    endif

    Inicialmente, a variável GAIA_APP_TARGET é configurada como engineering, assim por padrão o gaia usará app-engineering.list (que inclui todos os testes, demos, etc.):

    make

    Para especificar o uso de uma diferente lista de aplicativos você deve especificar diferentes opções quando executar o comando make. Por exemplo, para compilar com apps-production.list

  3. PRODUCTION=1 make
    • Se você compilar com DEMO=1, então será usado apps-demo.list.
    • Se você compilar com DOGFOOD=1, então será usado apps-dogfood.list.
    • Você pode suplantar a decisão usando GAIA_APP_CONFIG e prover seu próprio arquivo apps-*.list.

    gaia/Android.mk contém essas linhas:

    ifneq ($(filter user userdebug, $(TARGET_BUILD_VARIANT)),)
    GAIA_MAKE_FLAGS += PRODUCTION=1
    B2G_SYSTEM_APPS := 1
    endif

    Quando você compilar, se VARIANT=user ou VARIANT=userdebug forem configuradas (vão ser refletidas na variável TARGET_BUILD_VARIANT), PRODUCTION=1 será automaticamente configurada quando compilar o Gaia.

  4. O terceiro, e mais refinado método (porém mais complexo) é usar customizações. Isso permite que você especifique instruções de customização em tempo de compilação em diretórios serpardos, sem modificar o repositório Gaia principal. Você pode incluir suas próprias customizações em diretórios distintos ou usar diretórios pré-existentes que vêm no fonte.

  5. Por exemplo, a lista customizada de aplicativos básicos para Firefox OS tablet é definida em apps.list no diretório distribution_tablet (gaia/distribution_tablet). Essas customizações podem ser aplicadas durante a compilação usando opções como essa:

    GAIA_DISTRIBUTION_DIR=distribution_tablet make

    Nota: Customizações / personalizações possuem um tópico próprio. Para saber mais a respeito leia Customizações de Mercado.

    Nota: Se você quiser incluir aplicações externas customizadas como parte da sua imagem Gaia, você precisa compilá-las de uma forma específica, e colocá-las no diretório gaia/external-apps/. Leia o artigo para saber como.

Importante: Se você é um fornecedor de disposito e quer criar sua própria imagem B2G/Gaia para distribuição, você precisa satisfazer um certo critério antes de incluir o aplicativo FIrefox Marketplace nos seus telefones/tablets/etc. Contacte a Mozilla para maiores detalhes.

Contacte o time

Etiquetas do documento e colaboradores

 Colaboradores desta página: jwhitlock, rbrandao, xtv, andreanastacio, tiago_jesus, MarcPires
 Última atualização por: jwhitlock,