Introduction to the Firefox OS Command Line Interface

Firefox OS (we’ll be referring to as FFOS) is a new Mobile Operating System full of potential and increasing in popularity with users and developers.

After developing a couple of FFOS applications, I think the process could be more automated and less repetitive. There has to be a faster way to create a project than manually creating the whole directory tree and necessary files for every FFOS application.

Inspired by Git, I decided to create a Command-Line Interface to automate the process and help other developers who like developing FFOS apps.

What is ffos-cli?

ffos-cli is a simple tool, developed in the C programming language. It helps you generate the entire directory tree needed for a FFOS app and more.

It helps the developer:

• Create a new project folder with the name of the application
• Edit the manifest file from the command-line
• Add source files to the project

Getting started

ffos-cli uses a C library, called jansson, for dealing with JSON files like the manifest.webapp file in any Firefox OS application project. In order to get ffos-cli and use it properly, you should download jansson. If using Ubuntu, do this by executing:

sudo apt-get install libjansson-dev

If using a Mac, you can use Homebrew and type:

brew install jansson

This installs jansson on your machine. Now you are ready to get the ffos-cli source code and compile it yourself. You can clone the source code from GitHub.

To clone it to your machine, execute:

git clone https://github.com/aziflaj/ffos-cli.git

And to install, execute:

cd ffos-cli
make
sudo make install

If you execute ffos you will see the default help page:

ffos-cli 0.1 to help developing Firefox OS applications easier

commands:
    create - Creates a new Firefox OS application folder with necessary files
    add - Adds new source files to the working project
    set - Changes data stored in manifest file

For more help check the README or type ffos help [command].

If you see this help page (I’m sure you will), you have successfully installed ffos-cli on your machine. You are now ready to create Firefox OS applications using it.

ffos-cli in action

Now let’s use this tool to create and then manage a Firefox OS application.

To create an application, execute:

ffos create MagnApp

This command will create the following directory tree:

[MagnApp]
    |------ css/
    |------ img/
    |------ js/
    |------ index.html
    |------ manifest.webapp

Move into the MagnApp directory and set up the manifest.webapp file.

By default, the manifest.webapp file is:

{
    "name" : "MagnApp",
    "launch_path" : "index.html",
    "description" : "App description here",
    "version" : "1.0",
    "developer" : {
        "name" : "Your name here",
        "url" : "Your url here"
    }
}

If you want to set your name or your company’s name as the developer’s name, or your URL as the developer’s URL, you can by executing:

ffos set dev.name John Doe                  # or your company name
ffos set dev.url https://www.johndoe.com    # or your company url

Now let’s change the description of the application under development. This can be done by executing:

ffos set descr "This application does magnificient things"

Maybe you are not releasing this application as version 1.0. To change the version number, execute this:

ffos set version 0.3    # or whatever version this is

After executing all these ffos commands, the manifest.webapp becomes:

{
    "name" : "MagnApp",
    "launch_path" : "index.html",
    "description" : "This application does magnificient things",
    "version" : "0.3",
    "developer" : {
        "name" : "John Doe",
        "url" : "https://www.johndoe.com"
    }
}

If you need to add CSS and JavaScript files to your project. You can manually create them, or execute:

ffos add css main   # this creates main.css
ffos add js app     # this creates app.js

After executing these, the directory tree becomes:

[MagnApp]
    |------ css/
    |          |------ main.css
    |
    |------ img/
    |
    |------ js/
    |          |------ app.js
    |
    |------ index.html
    |------ manifest.webapp

You can add more html files by executing (You’ve probably figured this out by now!):

ffos add html anotherfile   # this creates anotherfile.html

If you want to set anotherfile.html as the launch path, execute:

ffos set launch_path anotherfile.html

During the development of your application, you may need to add permissions. Permissions are fields in the manifest which hold information about specific APIs that are used by the application. This is a list of all permissions accepted by Mozilla in the manifest.webapp file. To add a permission using ffos-cli, execute:

ffos set permission alarms "This application will use alarms"

This command adds a permission called "alarms" with the description "This application will use alarms". If a permission called "alarms" already exists in the manifest.webapp, it changes the description of the permission.

So, assuming you have executed all the commands above, you will have this directory tree:

[MagnApp]
    |------ css/
    |          |------ main.css
    |
    |------ img/
    |
    |------ js/
    |          |------ app.js
    |
    |------ anotherfile.html
    |------ index.html
    |------ manifest.webapp

and the manifest.webapp file:

{
    "name" : "MagnApp",
    "launch_path" : "anotherfile.html",
    "description" : "This application does magnificient things",
    "version" : "0.3",
    "developer" : {
        "name" : "John Doe",
        "url" : "https://www.johndoe.com"
    },
    "permissions" : {
        "alarms" : {
            "description" : "This magnificient application will use alarms"
        }
    }
}

Simplicity was the first thing in my mind when I designed and developed the ffos-cli and I hope you find it useful. Feel free to fork it on GitHub. At the moment I think permission filtering and app packaging features would be helpful and would love your help adding these or any other features you feel are needed.