Generates and installs FxOS apps
Python JavaScript HTML
Switch branches/tags
Nothing to show
Pull request Compare This branch is 22 commits ahead of malini:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
fxos_appgen
MANIFEST.in
README.rst
setup.py

README.rst

FxOS App Generator

A tool to generate, and optionally install, an FxOS application with any given permissions.

You can install this package from pypi as 'fxos_appgen'.

Requirements

You must have 'adb' installed. If you need to install adb, see https://developer.mozilla.org/en-US/Firefox_OS/Debugging/Installing_ADB.

Once installed, add adb to your PATH in your ~/.bashrc or equivalent file, by adding the following line to the file (replacing $SDK_HOME with the location of the android sdk):

PATH=$SDK_HOME:$PATH

Your phone must have Marionette installed on it and running on port 2828. If your phone does not have Marionette installed, you can install it using this repository: https://github.com/mozilla-b2g/marionette-extension

To forward Marionette's port to 2828, run:

adb forward tcp:2828 tcp:2828

Setup

You should set up and run this tool inside a virtual environment. From the root directory of your source checkout, run:

virtualenv venv

Then activate the virtualenv:

source bin/activate

To install:

python setup.py install

Usage

Once installed, you will have access to 'fxos_appgen' from the command line.

You can run it like so:

fxos_appgen [options] app_name details_file

By default, it assumes 'adb' is on your path and will generate a v1.3 certified app named 'app.zip' in your current working directory. It will not install the app by default.

To modify this behaviour, use the options listed here:

fxos_appgen --help

You can also use its API as python package. For example, if you wish to generate and install a simple, all permissions app:

from fxos_appgen import generate_app
generate_app("My App", install=True, version="1.3", all_perm=True)

Please see https://github.com/mozilla-b2g/fxos-appgen/blob/master/fxos_appgen/generator.py to learn about the API available.

Details File

The details_file must contain the permissions, and may contain the optional data.

This file is required, unless you use the --all-permissions option. If you use --all-permissions, then you may pass in this file to define the other optional fields, but the 'permissions' section of the details_file will be ignored.

Permissions (required unless --all-permissions option is used)

To set permissions on your application, you need to pass in a JSON file containing the permissions you wish to include.

Under the reference/ folders, you'll find complete_permissions.json files. These files contain the full list of permissions available for their respective FxOS versions. Use these files as references for your own permissions file.

For example, if I wanted to have an app with only "read" access to "contacts" for v1.3, my permissions file will only contain this:

{
  "permissions": {
    "contacts":{ "access": "readonly" },
  }
}

The "access" options take either "readonly", "readwrite", "readcreate" and "createonly".

For more information on permissions, please see https://developer.mozilla.org/en-US/Apps/Build/App_permissions

System Messages (optional)

Certain permissions require you to direct system messages to a particular page in your app. For example, if you have "sms" as a permission, then you likely want your app to listen for "sms-delivery-success", which will tell your app that the sms was sent successfully.

By default, if you specify a permission that has related system messages, the app generated will assigned its messages to be received at the launch_path. If you would like to change where the messages get received, then you can add a "messages" section to your permissions file and direct the messages the way you like. Here's an example:

{
  "permissions": {
    "sms": {}
  },
  "messages": [
    { "sms-delivery-success": "/index.html" }
  ]
}

For v1.3 builds: https://mxr.mozilla.org/mozilla-b2g28_v1_3/source/dom/messages/SystemMessagePermissionsChecker.jsm#29 and https://github.com/mozilla-b2g/gaia/blob/v1.3/apps/settings/resources/permissions_table.json

For trunk builds: https://mxr.mozilla.org/mozilla-central/source/dom/messages/SystemMessagePermissionsChecker.jsm#29 and https://github.com/mozilla-b2g/gaia/blob/master/apps/settings/resources/permissions_table.json

Datastore Access (optional)

If your app needs access to a datastore, please add it to your permissions file as either "datastore-owned" or "datastore-access" as needed, like so:

{
  "permissions": {
    "sms": {}
  },
  "messages": [
    { "sms-delivery-success": "/index.html" }
  ],
  "datastores-owned": {
      "download_store": {
        "access": "readwrite",
        "description": "Stores successful downloads"
      }
  }
}

Description (optional)

You may customize the description of your app. Add a "description" section to your permissions file with the desired text. Example:

{
  "permissions": {
    "sms": {}
  },
  "description": "My test application"
}

By default, we provide the description for your app as "Generated app".