mozilla

Compare Revisions

Quickstart guide to Gaia development

Change Revisions

Revision 600963:

Revision 600963 by leo89 on

Revision 601123:

Revision 601123 by fscholz on

Title:
Guia de desenvolvimento rápido para o Firefox OS
Quickstart guide to Gaia development
Slug:
Mozilla/Firefox_OS/Developing_Firefox_OS/Quickstart_guide_to_Gaia_development
Mozilla/Firefox_OS/Developing_Firefox_OS/Quickstart_guide_to_Gaia_development
Tags:
"Gaia", "Apps", "Firefox OS"
"Gaia", "Apps", "Firefox OS"
Content:

Revision 600963
Revision 601123
t7    <div class="twocolumns">t7    <div class="summary">
8      <h3 id="Firefox_OS_oque_.C3.A9.3F">
9        <strong><span style="color:#3399ff;">Firefox OS oque é?</
>span></strong> 
10      </h3>
11      <p>
12        &nbsp;
13      </p>8      <p>
14    </div>9        <span class="seoSummary">This guide provides a very quick
 > first step to debugging and developing Gaia apps, including runn
 >ing Gaia inside desktop Firefox and in the Firefox OS App Manager
 >.</span> This guide assumes that you know HTML5 technologies, hav
 >e knowledge of MVC patterns and have keen interest in Firefox OS.
 > By the end you will have a basic understanding of Gaia app struc
 >tres, and a basic workflow to modify Gaia apps and test your work
 >.
15    <p>10      </p>
16      <span style="color:#333333;"><strong><strong>&nbsp;Firefox 11    </div>
>OS é um sistema operacional livre desenvolvido pela Mozilla e bas 
>eado no navegador da web Firefox. Além de ter a Mozilla como prin 
>cipal responsável, o Firefox OS conta com apoio de outras empresa 
>s como a Telefônica e uma vasta comunidade de voluntários em todo 
> o mundo. Este sistema operacional tem como alvo dispositivos móv 
>eis, em especial, modelos modelos mais simples e de baixo custo,  
>já que prioriza o baixo consumo de recursos, como processamento e 
> memória RAM.</strong></strong></span><br> 
17      &nbsp;12    <h2 id="What_do_you_need.3F">
13      What do you need?
14    </h2>
18    </p>15    <p>
19    <h3 id="Arquitetura.3A">16      There are two options for setting up a Gaia/B2G development
 > environment. You can set up your own, or you can use the FoxBox 
 >virtual build environment. Let's run through both of these option
 >s.
20      <strong><span style="color:#3399ff;">Arquitetura:</span></s
>trong> 
21    </h3>
22    <p>17    </p>
18    <h3 id="Setting_up_your_own_environment">
19      Setting up your own environment
20    </h3>
21    <ol>
22      <li>First of all you need to have <a href="http://git-scm.c
 >om/book/en/Getting-Started-Installing-Git">Git installed</a>. If 
 >you prefer working in a visual environment, you might also consid
 >er installing the GitHub client (<a href="http://mac.github.com/"
 >>GitHub for Mac</a> / <a href="http://windows.github.com/">GitHub
 > for Windows</a>). Git is essential for updating the code, promot
 >ing your changes, and seeing what other developers are working on
 >.
23      <br>23      </li>
24      <strong>O Boot to Gecko é um projeto open-source e livre. É24      <li>Next, you need to get the Mozilla Gaia repository onto 
> possível obter todas as versões, incluindo anteriores, atual ou >your machine: <a href="https://github.com/mozilla-b2g/gaia">https
>em desenvolvimento, a partir do repositório da Mozilla no Git Hub>://github.com/mozilla-b2g/gaia</a>. The best way to do this is to
>. Além do acesso à implementação, a lista de funcionalidades prev> fork it and then clone your fork onto your local computer using 
>istas para implementação está aberta ao público.<br>><code>git clone https://github.com/&lt;your github name&gt;/gaia.
 >git</code>. This could take a while, as the repo is rather large:
 > about 700MB.
25      A arquitetura Boot2Gecko é composta por três módulos: Gonk,25      </li>
> Gecko e Gaia.</strong> 
26      <li>After this is done, you should use a terminal to enter 
 >the repository (<code>cd gaia</code>) and then run the <code>DEBU
 >G=1 make</code> command to build and configure Gaia correctly for
 > debugging. This downloads <a href="/en-US/docs/Mozilla/Projects/
 >XULRunner">XULRunner</a> — Mozilla's runtime package for installa
 >tion, updating and uninstalling — and uses it to perform the requ
 >ired build procedure.
27        <div class="note">
28          <strong>Note</strong>: Read more details about <a href=
 >"/en-US/Firefox_OS/Platform/Gaia/Hacking#Make_options">Gaia Make 
 >options</a> if you want to know more.
29        </div>
30      </li>
31      <li>After you are done with setting up your workspace, you 
 >need to install the <a href="http://nightly.mozilla.org/">Nightly
 > build of Firefox</a>.
32      </li>
33      <li>In that Nightly build, you could also choose to use the
 > Firefox Simulator Extension and App Manager Extension, depending
 > on your preferred workflow (both are covered below). The App Man
 >ager extension should be pre-installed in the nightly build, but 
 >you'll need to install the <a href="https://ftp.mozilla.org/pub/m
 >ozilla.org/labs/fxos-simulator/">Firefox OS simulator</a> if to u
 >se via the App Manager, if you don't have a real device to test o
 >n.
34      </li>
35      <li>You will need to install the <a href="https://ftp.mozil
 >la.org/pub/mozilla.org/labs/fxos-simulator/">ADB helper</a> for d
 >ebugging on the remote device, AKA your phone.
36      </li>
37      <li>You might want to get a Firefox OS phone. It will show 
 >you various use information related to the start time of apps, fr
 >ame rates, etc. Also, once you have the actual OS running on a de
 >vice, you will be able to easily test all the supported device AP
 >Is.
38      </li>
39    </ol>
40    <h3 id="Setting_up_the_FoxBox_virtual_environment">
41      Setting up the FoxBox virtual environment
42    </h3>
26    </p>43    <p>
27    <h3 id="Gonk.3A">44      FoxBox is a Firefox OS build environment contained in a VM 
 >(Virtual Machine), powered by Vagrant and VirtualBox. This has ma
 >ny advantages, but the main one is that it does a lot of configur
 >ation for you, leaving you to get on with development work. For f
 >ull instructions, read the <a href="https://github.com/gasolin/fo
 >xbox">FoxBox GitHub repo README</a>.
28      <strong><span style="color:#3399ff;">Gonk:</span></strong>
29    </h3>
30    <p>45    </p>
31      <strong>É o "sistema operacional" de baixo nível. Essencial
>mente é o kernel Linux e a camada de abstração de hardware. O ker 
>nel é baseado no kernel da versão open source do Android, o Andro 
>id Open Source Project (AOSP). O uso de parte do projeto AOSP per 
>mite ao Firefox OS usar ferramentas comuns às do desenvolvimento  
>para Android, como o ADB e o fastboot. Outro benefício é o uso de 
> drivers que dão suporte à ampla variedade de dispositivos Androi 
>d disponíveis no mercado.</strong> 
32    </p>46    <p>
33    <h3 id="Gecko.3A">47      Now that you have the basic workspace setup, lets get to th
 >e apps!
34      <strong><span style="color:#3399ff;">Gecko:</span></strong>
35    </h3>
36    <p>48    </p>
37      <strong>Neste estão implementados os padrões HTML, CSS, Jav49    <h2 id="Firefox_OS's_default_apps">
>aScript. Essa camada é uma versão do mesmo motor de layout utiliz 
>ado no navedor Firefox. Ela permite que as interfaces e apps func 
>ionem no próprio Firefox OS e em outros sistemas operacionais nos 
> quais o navegador é utilizado.</strong> 
50      Firefox OS's default apps
51    </h2>
38    </p>52    <p>
39    <h3 id="Gaia.3A">53      The default HTML5 apps provided in the Gaia source code are
 > as follows:
40      <strong><span style="color:#3399ff;">Gaia:</span></strong>
41    </h3>
42    <p>54    </p>
43      <strong>É a camada da interface gráfica do sistema operacio55    <ul>
>nal. Nela está implementados tudo que aparece quando o sistema op 
>eracional é carregado. Ou seja, tela de bloqueio, barra de notifi 
>cações, discador, gerenciador de mensagens de texto, câmera e dem 
>ais aplicações A interface é totalmente escrita em padrões aberto 
> da Web: HTML, CSS e JavaScript.</strong> 
56      <li>Bluetooth
57      </li>
58      <li>Browser
59      </li>
60      <li>Calendar
61      </li>
62      <li>Camera
63      </li>
64      <li>Clock
65      </li>
66      <li>Contacts
67      </li>
68      <li>Cost Control
69      </li>
70      <li>Dialer
71      </li>
72      <li>FL
73      </li>
74      <li>FM
75      </li>
76      <li>Gallery
77      </li>
78      <li>Homescreen
79      </li>
80      <li>Keyboard
81      </li>
82      <li>Music
83      </li>
84      <li>PDF.js
85      </li>
86      <li>Ringtones
87      </li>
88      <li>Search
89      </li>
90      <li>Setringtone
91      </li>
92      <li>Settings
93      </li>
94      <li>SMS
95      </li>
96      <li>System
97      </li>
98      <li>Video
99      </li>
100      <li>Wallpaper
101      </li>
102      <li>WAPPush
103      </li>
104    </ul>
44    </p>105    <p>
45    <h3 id="Desenvolvimento_de_apps.3A">106      The first app that gets launched when the phone starts is t
 >he System app. This app is responsible for opening and managing t
 >he Homescreen app. From the Homescreen app,&nbsp; you can launch 
 >the other apps to perform various functions.&nbsp; For example, t
 >he Dialer app gets launched from the Homescreen app when a user t
 >aps on the phone icon. This Dialer app can then launch the Contac
 >ts app when the user wants to see the list of contacts to dial.
46      <strong><span style="color:#3399ff;">Desenvolvimento de app
>s:</span></strong> 
47    </h3>
48    <p>107    </p>
49      <strong>O desenvolvimento de aplicativos no Firefox OS é si108    <h2 id="Let.E2.80.99s_explore_some_apps">
>mples e muito semelhante com as extensões do navegador Firefox. É 
> necessário um arquivo "manifest" (no formato JSON), sendo este r 
>esponsável por todas as informações que o aplicativo precisa para 
> poder funcionar: (nome do app, versão, informações do desenvolve 
>dor, APIs utilizados, permissões, etc.). As Apps são basicamente  
>escritas em HTML, JavaScript e CSS, já que o sistema é baseado em 
> tecnologia web.<br> 
50      Qualquer desenvolvedor pode submeter seus aplicativos no Ma109      Let’s explore some apps
>rketplace (loja de aplicativos do Firefox OS), bem como distribuí 
>-los em qualquer outros.</strong> 
110    </h2>
51    </p>111    <p>
52    <h3 id=" _O_Firefox_OS_possui_tr.C3.AAs_tipos_de_Apps.3A">112      The default apps are all contained in folders inside the <c
 >ode>gaia/apps/</code> folder. Each Gaia app folder contains the f
 >ollowing components:
53      <br>
54      <span style="color:#3399ff;">O Firefox OS possui três tipos
> de Apps:</span> 
55    </h3>
56    <p>113    </p>
114    <ul>
57      <br>115      <li>
58      <strong><span style="color:#3399ff;">Host App</span>-são “A116        <code>manifest.webapp</code> file: To store metadata abou
>plicativos Hospedados”, os tipos mais simples e comum de aplicati>t the app.
>vo. Como eles podem ser hospedados em locais variados e não passa 
>m pelo processo de análise da Política de Segurança de Conteúdo d 
>a Mozilla, eles não podem conseguir acesso a recursos mais sensív 
>eis do sistema operacional, disponível pelas Web APIs.</strong><b 
>r> 
117      </li>
59      <br>118      <li>
60      &nbsp;119        <code>style</code> folder: To store CSS files.
120      </li>
121      <li>
122        <code>js</code> folder: To store JavaScript files.
123      </li>
124      <li>
125        <code>locales</code> folder:&nbsp; To store translated st
 >rings for different languages.
126      </li>
127      <li>An HTML file: usually (but not limited to) <code>index.
 >html</code>.
128      </li>
129    </ul>
61    </p>130    <p>
131      Some apps may also have:
132    </p>
133    <ul>
134      <li>
135        <code>elements</code> folder: To store other views in HTM
 >L files.
136      </li>
137      <li>
138        <code>test</code> folder: To run the tests related to the
 > application.
139      </li>
140      <li>
141        <code>resources</code> folder: Contains other resources s
 >uch as movies, sounds, etc.
142      </li>
143      <li>
144        <code>build</code> folder.
145      </li>
146    </ul>
147    <div class="warning">
148      <p>
149        <strong>Important</strong>: There might also be some addi
 >tional files like LazyLoaders and Customized Templating Engines a
 >nd other utilities at work in a Firefox OS app. You may notice di
 >fferent JavaScript patterns in different apps or <code>.js</code>
 > files. Remember, it is an open source app/OS, so it is coded by 
 >many different people. Therefore the apps are often created accor
 >ding to different patterns and coding styles!
150      </p>
151    </div>
152    <div class="note">
153      <p>
154        <strong>Note</strong>: This is the general layout for Gai
 >a apps. Your own web apps only actually require a <code>manifest.
 >webapp</code> file; everything else is optional.
155      </p>
156    </div>
157    <p>
158      If you are experienced in web development, you will already
 > have all you need to make some modifications to these apps. Get 
 >improving.
159    </p>
160    <h2 id="Let's_fire_up_some_apps">
161      Let's fire up some apps
162    </h2>
163    <p>
164      After you have made modifications to those applications, yo
 >u will want to see the changes in action. You can either run them
 > inside Firefox Nightly, push them to your physical device, or ru
 >n them through the Firefox OS App Manager (in a simulator or on a
 > real device).
165    </p>
166    <h3 id="Running_in_Firefox_Nightly">
167      Running in Firefox Nightly
168    </h3>
169    <p>
170      To run Gaia and view the apps in Firefox Nightly, you have 
 >to run a command with the following structure:
171    </p>
172    <pre class="brush: bash">
173/path/to/firefoxnightly -profile /path/to/B2G/gaia/profile-debug 
 >-no-remote
174</pre>
175    <p>
176      For example, on Mac OS X, we ran the following command:
177    </p>
178    <pre class="brush: bash">
179/Applications/FirefoxNightly.app/Contents/MacOS/firefox -profile 
 >/Users/bob/git/gaia/profile-debug -no-remote
180</pre>
181    <div class="note">
182      <p>
183        <strong>Note:</strong> <code><em>-no-remote</em></code> i
 >s needed to prevent reusing a running Firefox instance instead of
 > creating a new one running the custom Gaia profile. <code>profil
 >e-debug</code> just means we are running the debugging profile of
 > Gaia we built earlier with the <code>DEBUG=1</code> option on th
 >e <code>make command</code> , with the environment set up for deb
 >ugging.
184      </p>
185    </div>
186    <p>
187      This takes a while to start up, but eventually you'll end u
 >p with a Gaia instance plus several controls running in a new bro
 >wser window:
188    </p>
189    <p>
190      <img alt="A UI screen showing the Gaia user interface runni
 >ng in Firefox nightly: a phone screen and number of tool bar cont
 >rols." src="https://mdn.mozillademos.org/files/7161/Screen%20Shot
 >%202014-02-13%20at%2012.48.png" style="width: 800px; height: 467p
 >x; display: block; margin: 0px auto;">
191    </p>
192    <p>
193      Alternatively if you just want to run a single app in the b
 >rowser, a much quicker approach is to simply open the app's root 
 >HTML file in the browser via a file:// URL (i.e. by opening index
 >.html in the browser). You can then use the <a href="/en-US/docs/
 >Tools/Responsive_Design_View">Responsive Design View</a> tool to 
 >see what it will look like on small screen resolutions. This is a
 > useful approach if you want to do some rapid UI development/debu
 >gging and has the advantage of almost instant reloads. The Firefo
 >x developer tools can be really useful here, for example for test
 >ing CSS tweaks.
194    </p>
195    <div class="note">
196      <p>
197        <strong>Note</strong>: That this approach will not have a
 >ccess to the device hardware so lots of functionality will not wo
 >rk, plus you won't get to see the app start up, see its icon on t
 >he home screen etc. Running on a physical device is the best appr
 >oach overall, see below.
198      </p>
199    </div>
200    <h3 id="Running_on_a_physical_device">
201      Running on a physical device
202    </h3>
203    <p>
204      To push your modified Gaia to a physical Firefox OS device:
205    </p>
206    <ol>
207      <li>Make sure you have <a href="/en-US/Firefox_OS/Debugging
 >/Installing_ADB"><code>adb</code></a> installed, or install <a hr
 >ef="https://ftp.mozilla.org/pub/mozilla.org/labs/fxos-simulator/"
 >>ADB helper</a> as described above.
208      </li>
209      <li>Check that your phone is successfully connected to your
 > computer over <code>adb</code> by entering the <code>adb devices
 ></code> command into your terminal.
210      </li>
211      <li>Enter the command <code>make reset-gaia</code> from ins
 >ide your Gaia directory to push it to your device over <code>adb<
 >/code>.
212      </li>
213    </ol>
214    <p>
215      This can take a while, but there is an easier quicker way —
 > using the App Manager.
216    </p>
217    <h3 id="Running_through_the_App_Manager">
218      Running through the App Manager
219    </h3>
220    <p>
221      As long as your device is running Firefox 1.2+, you can jus
 >t run the modified app in the App Manager, as covered in the next
 > section.
222    </p>
223    <h2 id="Debugging_with_the_App_Manager">
224      Debugging with the App Manager
225    </h2>
226    <p>
227      After you are done modifying apps (or <a href="/en-US/docs/
 >Web/API/Apps">creating some of your own</a>), you might want to d
 >ebug them.
228    </p>
229    <p>
230      To do so, first of all get the App Manager and your physica
 >l device talking to one another, or use the Firefox OS simulator 
 >if you don't have a physical device. This is all explained in <a 
 >href="/en-US/Firefox_OS/Using_the_App_Manager">Using the App Mana
 >ger</a>.
231    </p>
232    <p>
233      Now select the app you want to debug — use the <em>Add Pack
 >aged App</em> control inside the App Manager and select the direc
 >tory your app to debug. When the app first comes up you'll need t
 >o press its "Start" button to install it on the device/simulator 
 >and then start it up. From then on, you can press "Update" to pus
 >h further updates to the device/simulator, and "Debug" to use Moz
 >illa's <a href="/en-US/docs/Tools">developer tools</a> to debug t
 >he app directly on the device.
234    </p>
235    <p>
236      For example, below you can see the Contacts app running in 
 >the App Manager.
237    </p>
238    <p>
239      <img alt="A card showing details of the Gaia contacts app: 
 >a simple contacts application." src="https://mdn.mozillademos.org
 >/files/7135/contacts-app-screenshot.png" style="width: 868px; hei
 >ght: 358px; display: block; margin: 0px auto;">
240    </p>
241    <p>
242      Try out some of the debugging features, for example running
 > some console commands, or modifying some CSS properties.
243    </p>
244    <p>
245      <img alt="A screenshot of the Mozilla App Manager" src="htt
 >ps://mdn.mozillademos.org/files/7137/debugger.png" style="width: 
 >700px; height: 357px; display: block; margin: 0px auto;">
246    </p>
247    <h2 id="Contributing_code_back_to_the_project">
248      Contributing code back to the project
249    </h2>
250    <p>
251      Once you are satisfied with the changes you've made in the 
 >Gaia repo, you can submit pull requests back to the repo on GitHu
 >b. If you are not sure how to do this, read <a href="https://help
 >.github.com/articles/using-pull-requests">Using Pull Requests</a>
 > on the GitHub help pages.
252    </p>
253    <p>
254      In reality, your pull requests are unlikely to be accepted 
 >by the Gaia development team without some discussion and agreemen
 >t. Your first course of action should be to discuss the changes y
 >ou want to make with the development team. They can be found on t
 >he dev-gaia@lists.mozilla.org mailing list, or in the #gaia IRC c
 >hannel on <a href="https://wiki.mozilla.org/IRC">Mozilla IRC</a>.
255    </p>
256    <p>
257      Another course of action is to file bugs on the <a href="ht
 >tps://bugzilla.mozilla.org/">Mozilla Bugzilla</a> system, using t
 >he <a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Fi
 >refox%20OS">Firefox OS project bug form</a> (choose Gaia — or an 
 >appropriate subset — as the component). First of all you should s
 >earch Bugzilla to see if the issue has already been filed by some
 >one else. If not, consider the following two points:
258    </p>
259    <ul>
260      <li>If your bug concerns something that is obviously wrong 
 >— a bug in the real sense of the word — then you should just file
 > it.
261      </li>
262      <li>If your bug is for a feature request, then it is probab
 >ly best to discuss it on the mailing list/IRC first.
263      </li>
264    </ul>
265    <div class="note">
266      <p>
267        <strong>Note</strong>: If you are not sure what to work o
 >n and just want to find relevant bugs to contribute to, Josh Matt
 >hews' <a href="http://www.joshmatthews.net/bugsahoy/?b2g=1">Bugs 
 >Ahoy</a> app is useful.
268      </p>
269    </div>
270    <h2 id="FAQ">
271      FAQ
272    </h2>
273    <p>
274      The following subsections answer some common questions abou
 >t debugging apps using Gaia on the desktop.
275    </p>
276    <div class="note">
277      <p>
278        <strong>Note</strong>: Refer to <a href="https://develope
 >r.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Hacking
 >#High_resolution_image_assets" title="https://developer.mozilla.o
 >rg/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Hacking#High_resol
 >ution_image_assets">Hacking gaia</a> for more make options that c
 >an be set that are useful for Gaia debugging.
279      </p>
280    </div>
281    <h3 id="Can_I_emulate_high_resolution_devices_inside_the_Fire
 >fox_desktop_browser.3F">
282      Can I emulate high resolution devices inside the Firefox de
 >sktop browser?
283    </h3>
284    <p>
285      Yes.
286    </p>
287    <ol>
288      <li>First of all, you can use the command
289        <pre class="language-html">
290GAIA_DEV_PIXELS_PER_PX=1.5 DEBUG=1 make
291</pre>to make sure the images look sharp on qHD and WVGA devices.
292      </li>
293      <li>Next, you can change browser density by opening the <a 
 >href="https://developer.mozilla.org/about:config" title="/about:c
 >onfig">about:config</a> page in Firefox and setting the <code>lay
 >out.css.devPixelsPerPx</code> flag to <code>1.5</code> .
294      </li>
295      <li>Last, you can use the <a href="/en-US/docs/Tools/Respon
 >sive_Design_View">Responsive Design View</a> to 320 x 533 px (whi
 >ch is the equivalent CSS pixel dimensions to 480 x 800 device pix
 >els.)
296      </li>
297    </ol>

Back to History