Testing in a privileged context: Shipping your own Gaia apps

  • Revision slug: Mozilla/Firefox_OS/Apps/Testing_in_a_privileged_context
  • Revision title: Testing in a privileged context: Shipping your own Gaia apps
  • Revision id: 372273
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment Moved From Mozilla/Firefox_OS/Testing_in_a_Privileged_Context to Mozilla/Firefox_OS/Apps/Testing_in_a_privileged_context

Revision Content

Testing in a Privileged Context: Shipping your own Gaia Apps

As you may have noticed, executing JavaScript does not give you full access to all the shiny WebAPIs. For an App to use a specific API, it has to request access in its manifest. To get the current running App's metadata (and the manifest in a variable (here: appself), you could run the following:

navigator.mozApps.getSelf().onsuccess = function(e) { appself = e.result }

Or, if you want to see the permissions for a different App try the test app "Permissions" which comes with your b2g-desktop testing build: It will enumerate the permissions given to all the currently installed apps.

Some of the existing WebAPIs are just not available to any kind of App. To use them anyway, we install an App with the highest privileges (i.e., certified). To do that, we will have to build our custom version of the top b2g layer, called Gaia. Doing this requires git and a working make environment.

Downloading and building Gaia

First need to download Gaia, and then build it, which builds a profile which you can load with b2g desktop. This can be achieved with the following commands:

Warning: building Gaia the first time requires downloading xulrunner, which is approx. 500MB.

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

Preparing a custom app

While the xulrunner is being downloaded, I recommend reading the Gaia source code and getting our custom app ready in the meantime:

All the apps that come with Gaia (Settings, Contacts, Browser, ...) are stored in the apps/ directory. That means our high-privileged app will also have to go there. For this documentation, an example app called allperms has been made available on github.

Change into the apps/ directory and clone it:

git clone https://github.com/freddyb/allperms.git

Once your first gaia build is done and xulrunner-sdk has been downloaded, you can re-make gaia with allperms in the apps/ folder. But don't worry, this time will be much faster:

make

Load B2G desktop using the new profile

B2G Desktop comes with two main executables: b2g and b2g-bin: we want the latter, as this allows us to specify command line arguments.

Load the b2g executable, supplying the -profile option with the path to the gaia location

Linux

    $ b2g-bin -profile /path/to/gaia/profile 

Mac

On a Mac the command to launch from the gaia directory:

    $ /Applications/B2G.app/Contents/MacOS/b2g-bin -profile /path/to/gaia/profile 

Windows

TBD

 

Assuming it all works, you should see the lock screen:

<placeholder for gaia screenshot>

  • Useful switches when running b2g:
    • Launch B2G desktop with a specific screen resolution: --screen (e.g. --screen 800x600)
    • Enable the error console: -jsconsole (note the single - )

Hint: this profile starts with default settings again. You will have to setup marionette, proxy settings and certificates once again. Sorry about that.

Done

Your allperms have should be equipped with all possible permissions.

Now you will only have to re-iterate on the Marionette steps from part 2 to have a testing environment that can access all WebAPIs.

Revision Source

<h2>Testing in a Privileged Context: Shipping your own Gaia Apps</h2>
<p>As you may have noticed, executing JavaScript does not give you full access to <a data-mce-="" href="https://developer.mozilla.org/en-US/docs/WebAPI">all the shiny WebAPIs</a>. For an App to use a specific API, it has to request access in its <a data-mce-="" href="https://developer.mozilla.org/en-US/docs/Apps/Manifest">manifest</a>. To get the current running App's metadata (and the manifest in a variable (here: appself), you could run the following:</p>
<pre>
navigator.mozApps.getSelf().onsuccess = function(e) { appself = e.result }</pre>
<p>Or, if you want to see the permissions for a different App try the test app "Permissions" which comes with your b2g-desktop testing build: It will enumerate the permissions given to all the currently installed apps.</p>
<p>Some of the existing WebAPIs are just not available to any kind of App. To use them anyway, we install an App with the highest privileges (i.e., certified). To do that, we will have to build our custom version of the top b2g layer, called Gaia. Doing this requires <em>git</em> and a working <em>make</em> environment.</p>
<h4><strong>Downloading and building Gaia</strong></h4>
<p>First need to download Gaia, and then build it, which builds a profile which you can load with b2g desktop. This can be achieved with the following commands:</p>
<p><strong>Warning: building Gaia the first time requires downloading xulrunner, which is approx. 500MB.</strong></p>
<pre>
    $ git clone <a class="external free" data-mce-="" href="https://github.com/mozilla-b2g/gaia" rel="nofollow">https://github.com/mozilla-b2g/gaia</a> 
    $ cd gaia
    $ make
</pre>
<h4><strong>Preparing a custom app</strong></h4>
<p>While the xulrunner is being downloaded, I recommend <a data-mce-="" href="https://github.com/mozilla-b2g/gaia">reading the Gaia source code</a> and getting our custom app ready in the meantime:</p>
<p>All the apps that come with Gaia (Settings, Contacts, Browser, ...) are stored in the apps/ directory. That means our high-privileged app will also have to go there. For this documentation, an example app called <a data-mce-="" href="https://github.com/freddyb/allperms"><em>allperms</em></a> has been made available on github.</p>
<p>Change into the apps/ directory and clone it:</p>
<pre>
git clone <span class="nolink">https://github.com/freddyb/allperms.git</span></pre>
<p>Once your first gaia build is done and xulrunner-sdk has been downloaded, you can re-make gaia with allperms in the apps/ folder. But don't worry, this time will be much faster:</p>
<pre>
make</pre>
<h4><span class="mw-headline">Load B2G desktop using the new profile</span></h4>
<p>B2G Desktop comes with two main executables: <em>b2g</em> and <em>b2g-bin</em>: we want the latter, as this allows us to specify command line arguments.</p>
<p>Load the b2g executable, supplying the -profile option with the path to the gaia location</p>
<h4>Linux</h4>
<pre>
    $ b2g-bin -profile /path/to/gaia/profile 
</pre>
<h4>Mac</h4>
<p>On a Mac the command to launch from the gaia directory:</p>
<pre>
    $ /Applications/B2G.app/Contents/MacOS/b2g-bin -profile /path/to/gaia/profile 
</pre>
<h4>Windows</h4>
<p>TBD</p>
<p>&nbsp;</p>
<p>Assuming it all works, you should see the lock screen:</p>
<p><span data-mce-style="color: #333333;" style="color: rgb(51,51,51);">&lt;placeholder for gaia screenshot&gt;</span></p>
<ul>
  <li>Useful switches when running b2g:
    <ul>
      <li>Launch B2G desktop with a specific screen resolution: --screen (e.g. --screen 800x600)</li>
      <li>Enable the error console: -jsconsole (note the single - )</li>
    </ul>
  </li>
</ul>
<p><strong>Hint: </strong>this profile starts with <em>default settings</em> again. You will have to setup marionette, proxy settings and certificates once again. Sorry about that.</p>
<h4>Done</h4>
<p>Your allperms have should be equipped with all possible permissions.</p>
<p>Now you will only have to re-iterate on the Marionette steps from <a data-mce-="" href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Debugging_and_Security_Testing_with_Firefox_OS">part 2</a> to have a testing environment that can access all WebAPIs.</p>
Revert to this revision