mozilla

Revision 522801 of Quickstart guide to Gaia development

  • 리비전 슬러그: Mozilla/Firefox_OS/Hacking_Firefox_OS/Quickstart_guide_to_Gaia_development
  • 리비전 제목: Quickstart guide to Gaia development
  • 리비전 아이디: 522801
  • 제작일시:
  • 만든이: jryans
  • 현재 리비전인가요? 아니오
  • 댓글
태그: 

리비전 내용

This guide provides a very quick easy guide to developing Gaia apps, including running Gaia inside desktop Firefox. This guide assumes that you know HTML5 technologies, have knowledge of MVC patterns and have keen interest in Firefox OS.

Note: It's important to note that this is not a particularly accurate representation of the experience of using Boot to Gecko on a real mobile device. Many hardware interface features don't work, for example, and Firefox nightly builds may be unstable. But it is still a valid way to get some high level testing done.

What do you need?

  • First of all you need to have Git installed. If you prefer working in a visual environment, you might also consider installing the Github client (Github for Mac / Github for Windows). Git is essential for updating the code, promoting your changes, and seeing what other developers are working on.
  • Next, you need to clone the Mozilla Gaia repository: https://github.com/mozilla-b2g/gaia. After this is done, you should use a terminal to enter the repository (cd gaia) and then run the DEBUG=1 make command to configure Gaia correctly for debugging.
  • After you are done with setting up your workspace, you need to install the Nightly build of Firefox.
  • In that Nightly build, you could also choose to have the Firefox Simulator Extension and App Manager Extension, depending on your preferred workflow (both are covered below). The App Manager extension should be pre-installed in the nightly build, but you'll need to install the Firefox OS simulator if desired.
  • You will need to install the ADB helper for debugging on the remote device, AKA your phone.
  • You might want to get a Firefox OS phone. It will show you various use information related to the start time of apps, frame rates, etc. Also, once you have the actual OS running on a device, you will be able to easily test all the supported device APIs.

Now that you have the basic workspace setup, lets get to the apps!

Firefox OS's default apps

The default HTML5 apps provided in the Gaia source code are as follows:

  • Bluetooth
  • Browser
  • Calendar
  • Camera
  • Clock
  • Cost Control
  • Dialer
  • FL
  • FM
  • Gallery
  • Homescreen
  • Keyboard
  • Music
  • PDF.js
  • Ringtones
  • Search
  • Setringtone
  • Settings
  • SMS
  • System
  • Video
  • Wallpaper
  • WAPPush

The first app that gets launched when the phone starts is the System app. This app is responsible for opening and managing the Homescreen app. From the Homescreen app,  you can launch the other apps to perform various functions.  For example, the Dialer app gets launched from the Homescreen app when a user taps on the phone icon. This Dialer app can then launch the Contacts app when the user wants to see the list of contacts to dial.

Let’s explore some apps

The default apps are all contained in folders inside the gaia/apps/ folder. Each Gaia app folder contains the following components:

  • manifest.webapp file: To store metadata about the app.
  • style folder: To store CSS files.
  • js folder: To store JavaScript files.
  • locales folder:  To store translated strings for different languages.
  • An HTML file: usually (but not limited to) index.html.

Some apps may also have:

  • elements folder: To store other views in HTML files.
  • test folder: To run the tests related to the application.
  • resources folder: Contains other resources such as movies, sounds, etc.
  • build folder.

There might also be some additional files like LazyLoaders and Customized Templating Engines and other utilities at work in a Firefox OS app. Just find the path to those files from the main HTML file, and try to figure out how they work. You may notice different JavaScript patterns in different apps or .js files. Remember, it is an open source app/OS, so it is coded by many different people.

Note: This is the general layout for Gaia apps. Your own web apps only actually require a manifest.webapp file; everything else is optional.

If you are experienced in web development, you will already have all you need to make some modifications to these apps. Get improving.

Let's fire up some apps

After you have made modifications to those applications, you will want to see the changes in action. You can either seem them in the Firefox OS simulator, running inside Firefox Nightly, or on a physical Firefox OS device.

Running in the Firefox OS simulator

To run the modified Gaia apps in the Firefox Simulator, open the simulator via Tools > Web Developer > Firefox OS Simulator. This should open up the simulator UI, then from here you can use the Add Directory/Add URL tools to add your modified Gaia apps into the simulator and run them. This is ok for a quick test, but the simulator doesn't have a lot of the features of Firefox OS available. The below options are better.

Running in Firefox Nightly

To run Gaia and view the apps in Firefox Nightly, you have to run a command with the following structure:

/path/to/firefoxnightly -profile /path/to/B2G/gaia/profile-debug -no-remote

For example, on Mac OS X, we ran the following command:

/Applications/FirefoxNightly.app/Contents/MacOS/firefox -profile /path/to/B2G/gaia/profile-debug -no-remote

Note: -no-remote is needed to prevent reusing a running Firefox instance instead of creating a new one running the custom Gaia profile.

Running on a physical device

To push your modified Gaia to a physical Firefox OS device:

  1. Make sure you have adb installed, or install ADB helper as described above.
  2. Check that your phone is successfully connected to your computer over adb by entering the adb devices command into your terminal.
  3. Enter the command make reset-gaia from inside your Gaia directory to push it to your device over adb.

There is an even easier way — as long as your device is running Firefox 1.2+, you can just run the modified app in the App Manager, as covered in the next section.

Debugging with the App Manager

After you are done building your app, you might want to debug it.

To do so, first of all get the App Manager and your physical device talking to one another, as shown in Using the App Manager.

Select the Contacts app (for example), then click on that debug button in your app section in the App Manager.

A card showing details of the Gaia contacts app: a simple contacts application.

This will not only run the app on a device, but it opens up the debug window as well. Test it out by adding console or debug logs.

A screenshot of the Mozilla App Manager

FAQ

The following subsections answer some common questions about debugging apps using Gaia on the desktop.

Note: Refer to Hacking gaia for more make options that can be set that are useful for Gaia debugging.

Can I emulate high resolution devices inside the Firefox desktop browser?

Yes.

  1. First of all, you can use the command
    GAIA_DEV_PIXELS_PER_PX=1.5 DEBUG=1 make
    to make sure the images look sharp on qHD and WVGA devices.
  2. Next, you can change browser density by opening the about:config page in Firefox and setting the layout.css.devPixelsPerPx flag to 1.5 .
  3. Last, you can use the Responsive Design View to 320 x 533 px (which is the equivalent CSS pixel dimensions to 480 x 800 device pixels.)

리비전 소스

<div class="summary">
 <p><span class="seoSummary">This guide provides a very quick easy guide to developing Gaia apps, including running Gaia inside desktop Firefox.</span> This guide assumes that you know HTML5 technologies, have knowledge of MVC patterns and have keen interest in Firefox OS.</p>
</div>
<div class="note">
 <p><strong>Note</strong>: It's important to note that this is not a particularly accurate representation of the experience of using Boot to Gecko on a real mobile device. Many hardware interface features don't work, for example, and Firefox nightly builds may be unstable. But it is still a valid way to get some high level testing done.</p>
</div>
<h2 id="What_do_you_need.3F">What do you need?</h2>
<ul>
 <li>First of all you need to have <a href="http://git-scm.com/book/en/Getting-Started-Installing-Git">Git installed</a>. If you prefer working in a visual environment, you might also consider 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, promoting your changes, and seeing what other developers are working on.</li>
 <li>Next, you need to clone the Mozilla Gaia repository: <a href="https://github.com/mozilla-b2g/gaia">https://github.com/mozilla-b2g/gaia</a>. After this is done, you should use a terminal to enter the repository (<code>cd gaia</code>) and then run the <code>DEBUG=1 make</code> command to configure Gaia correctly for debugging.</li>
 <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>.</li>
 <li>In that Nightly build, you could also choose to have the Firefox Simulator Extension and App Manager Extension, depending on your preferred workflow (both are covered below). The App Manager extension should be pre-installed in the nightly build, but you'll need to install the <a href="https://ftp.mozilla.org/pub/mozilla.org/labs/fxos-simulator/">Firefox OS simulator</a> if desired.</li>
 <li>You will need to install the <a href="https://ftp.mozilla.org/pub/mozilla.org/labs/fxos-simulator/">ADB helper</a> for debugging on the remote device, AKA your phone.</li>
 <li>You might want to get a Firefox OS phone. It will show you various use information related to the start time of apps, frame rates, etc. Also, once you have the actual OS running on a device, you will be able to easily test all the supported device APIs.</li>
</ul>
<p>Now that you have the basic workspace setup, lets get to the apps!</p>
<h3 id="Firefox_OS's_default_apps">Firefox OS's default apps</h3>
<p>The default HTML5 apps provided in the Gaia source code are as follows:</p>
<ul>
 <li>Bluetooth</li>
 <li>Browser</li>
 <li>Calendar</li>
 <li>Camera</li>
 <li>Clock</li>
 <li>Cost Control</li>
 <li>Dialer</li>
 <li>FL</li>
 <li>FM</li>
 <li>Gallery</li>
 <li>Homescreen</li>
 <li>Keyboard</li>
 <li>Music</li>
 <li>PDF.js</li>
 <li>Ringtones</li>
 <li>Search</li>
 <li>Setringtone</li>
 <li>Settings</li>
 <li>SMS</li>
 <li>System</li>
 <li>Video</li>
 <li>Wallpaper</li>
 <li>WAPPush</li>
</ul>
<p>The first app that gets launched when the phone starts is the System app. This app is responsible for opening and managing the Homescreen app. From the Homescreen app,&nbsp; you can launch the other apps to perform various functions.&nbsp; For example, the Dialer app gets launched from the Homescreen app when a user taps on the phone icon. This Dialer app can then launch the Contacts app when the user wants to see the list of contacts to dial.</p>
<h2 id="Let.E2.80.99s_explore_some_apps">Let’s explore some apps</h2>
<p>The default apps are all contained in folders inside the <code>gaia/apps/</code> folder. Each Gaia app folder contains the following components:</p>
<ul>
 <li><code>manifest.webapp</code> file: To store metadata about the app.</li>
 <li><code>style</code> folder: To store CSS files.</li>
 <li><code>js</code> folder: To store JavaScript files.</li>
 <li><code>locales</code> folder:&nbsp; To store translated strings for different languages.</li>
 <li>An HTML file: usually (but not limited to) <code>index.html</code>.</li>
</ul>
<p>Some apps may also have:</p>
<ul>
 <li><code>elements</code> folder: To store other views in HTML files.</li>
 <li><code>test</code> folder: To run the tests related to the application.</li>
 <li><code>resources</code> folder: Contains other resources such as movies, sounds, etc.</li>
 <li><code>build</code> folder.</li>
</ul>
<p>There might also be some additional files like LazyLoaders and Customized Templating Engines and other utilities at work in a Firefox OS app. Just find the path to those files from the main HTML file, and try to figure out how they work. You may notice different 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.</p>
<div class="note">
 <p><strong>Note</strong>: This is the general layout for Gaia apps. Your own web apps only actually require a <code>manifest.webapp</code> file; everything else is optional.</p>
</div>
<p>If you are experienced in web development, you will already have all you need to make some modifications to these apps. Get improving.</p>
<h2 id="Let's_fire_up_some_apps">Let's fire up some apps</h2>
<p>After you have made modifications to those applications, you will want to see the changes in action. You can either seem them in the Firefox OS simulator, running inside Firefox Nightly, or on a physical Firefox OS device.</p>
<h3 id="Running_in_the_Firefox_OS_simulator">Running in the Firefox OS simulator</h3>
<p>To run the modified Gaia apps in the Firefox Simulator, open the simulator via <em>Tools &gt; Web Developer &gt; Firefox OS Simulator</em>. This should open up the simulator UI, then from here you can use the <em>Add Directory</em>/<em>Add URL</em> tools to add your modified Gaia apps into the simulator and run them. This is ok for a quick test, but the simulator doesn't have a lot of the features of Firefox OS available. The below options are better.</p>
<h3 id="Running_in_Firefox_Nightly">Running in Firefox Nightly</h3>
<p>To run Gaia and view the apps in Firefox Nightly, you have to run a command with the following structure:</p>
<pre class="brush: bash">
/path/to/firefoxnightly -profile /path/to/B2G/gaia/profile-debug -no-remote</pre>
<p>For example, on Mac OS X, we ran the following command:</p>
<pre class="brush: bash">
/Applications/FirefoxNightly.app/Contents/MacOS/firefox -profile /path/to/B2G/gaia/profile-debug -no-remote</pre>
<div class="note">
 <p><strong>Note:</strong> <code><em>-no-remote</em></code> is needed to prevent reusing a running Firefox instance instead of creating a new one running the custom Gaia profile.</p>
</div>
<h3 id="Running_on_a_physical_device">Running on a physical device</h3>
<p>To push your modified Gaia to a physical Firefox OS device:</p>
<ol>
 <li>Make sure you have <a href="/en-US/Firefox_OS/Debugging/Installing_ADB"><code>adb</code></a> installed, or install <a href="https://ftp.mozilla.org/pub/mozilla.org/labs/fxos-simulator/">ADB helper</a> as described above.</li>
 <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.</li>
 <li>Enter the command <code>make reset-gaia</code> from inside your Gaia directory to push it to your device over <code>adb</code>.</li>
</ol>
<p>There is an even easier way — as long as your device is running Firefox 1.2+, you can just run the modified app in the App Manager, as covered in the next section.</p>
<h2 id="Debugging_with_the_app_manager">Debugging with the App Manager</h2>
<p>After you are done building your app, you might want to debug it.</p>
<p>To do so, first of all get the App Manager and your physical device talking to one another, as shown in <a href="/en-US/Firefox_OS/Using_the_App_Manager">Using the App Manager</a>.</p>
<p>Select the Contacts app (for example), then click on that debug button in your app section in the App Manager.</p>
<p><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; height: 358px; display: block; margin: 0px auto;" /></p>
<p>This will not only run the app on a device, but it opens up the debug window as well. Test it out by adding console or debug logs.</p>
<p><img alt="A screenshot of the Mozilla App Manager" src="https://mdn.mozillademos.org/files/7137/debugger.png" style="width: 700px; height: 357px; display: block; margin: 0px auto;" /></p>
<h2 id="FAQ">FAQ</h2>
<p>The following subsections answer some common questions about debugging apps using Gaia on the desktop.</p>
<div class="note">
 <p><strong>Note</strong>: Refer to <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Hacking#High_resolution_image_assets" title="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Hacking#High_resolution_image_assets">Hacking gaia</a> for more make options that can be set that are useful for Gaia debugging.</p>
</div>
<h3 id="Can_I_emulate_high_resolution_devices_inside_the_Firefox_desktop_browser.3F">Can I emulate high resolution devices inside the Firefox desktop browser?</h3>
<p>Yes.</p>
<ol>
 <li>First of all, you can use the command
  <pre class="language-html">
GAIA_DEV_PIXELS_PER_PX=1.5 DEBUG=1 make</pre>
  to make sure the images look sharp on qHD and WVGA devices.</li>
 <li>Next, you can change browser density by opening the <a href="https://developer.mozilla.org/about:config" title="/about:config">about:config</a> page in Firefox and setting the <code>layout.css.devPixelsPerPx</code> flag to <code>1.5</code> .</li>
 <li>Last, you can use the <a href="/en-US/docs/Tools/Responsive_Design_View">Responsive Design View</a> to 320 x 533 px (which is the equivalent CSS pixel dimensions to 480 x 800 device pixels.)</li>
</ol>
현재 리비전 복원