Home

Instructions

You could use FoxBox to setup your FirefoxOS Build Environment with following 2 approaches:

• Auto-configured VM (Virtual Machine) powered by vagrant and virtualbox.
• Config by Ubuntu 12.04(LTS) install script

In Virtual Machine

If you haven't install Virtualbox or vagrant, read the following instructions.

Prerequisite

You MUST download and install Virtualbox & Vagrant before you start using foxbox.

Compile a full OS is a resource consumption task. Your machine SHOULD reserve following creteria for VM

• have hardware virtualization support such as INTEL VT-x/AMD-V(which usually means i5 or i7, atom CPU is not sufficient). Mac/Windows 8 already enable it. (Guide to enable visualization in BIOS)
• at least 4GB RAM
• about 40GB disk space (for full OS, 5~10GB for gaia or gecko)

Ref: What is virtualization

On linux or mac, run configure.sh. The script will download basic ubuntu 12.04 image to your Host OS and start vagrant to setup the VM for you.

On other platform, start the setup process

$ B2G_PATH=<local path> vagrant up

You have to enter password in Linux/Mac to proceed share the NFS folders.

It will take time to download and setup the environment. Go have a cup of coffee.

(If foxbox is stablized, we'd like to ship a preconfigured box to save your time and bandwidth)

Note: if your virtualbox did not run correctly with the following message:

The guest machine entered an invalid state while waiting for it to boot.

You may need to modify your BIOS to enable VT-x/hardware virtualization features on your motherboard.

Step 1: Use your VM

Connect to VM

$ B2G_PATH=<local path> vagrant up

In linux/mac you could use ${PWD}/B2G instead of real <local path>.

Log in with the account 'vagrant', password 'vagrant' in VM's console.

If you don't want any file sync-up with Host OS, you could just run

$ vagrant up

To disconnect VM, use following commands

$ exit
$ vagrant halt

Though the VM already popup a separate window. You can still remote access to VM via command:

$ vagrant ssh

When you reopen VM second time, it will be start with GUI environment.

To access Terminal in GUI environment, open Start Menu > System Tools > XTerm or UXTerm.

In Ubuntu 12.04

If you have a device with Ubuntu version 12.04 (Long term support) installed, you could run auto-setup script setup_ubuntu_12_04.sh within the script folder directly without VM.

You might want to disable Enable GUI part in setup_ubuntu_12_04.sh, which will install extra GUI environment.

Step 2: Build FirefoxOS

Build Gaia only

Make sure you've synced local gaia folder to VM via command

$ GAIA_PATH=<local path> vagrant up

(Run gui.sh to start the GUI environment if you want test gaia via bundled nightly browser)

Then FoxBox provide an init script to help you fetch gaia source:

$ ./gaia_init.sh

All gaia related helper scripts are prefixed by gaia_.

It will clone gaia source to gaia folder. Then go to gaia folder and type

$ cd gaia
$ make DEBUG=1

refer to https://developer.mozilla.org/en-US/Firefox_OS/Platform/Gaia/Hacking

In GUI environment you could open the Terminal Emulator and run

$ firefox-trunk -profile /home/vagrant/gaia/profile-debug

Build whole FirefoxOS (B2G)

Make sure you've synced local B2G folder to VM via command

$ GAIA_PATH=<local path> vagrant up

Then FoxBox provide an init script to help you fetch B2G source:

$ ./B2G_init.sh

It will clone B2G source to B2G folder. Refer to https://developer.mozilla.org/en-US/Firefox_OS/Preparing_for_your_first_B2G_build Go to B2G folder and type

$ cd B2G
$ ./configure.sh emulator
$ ./build.sh

The above instruction takes several hours. Once the compile process is done, go to step 3 to launch emulator in GUI.

Basically the above instruction can build all FirefoxOS for you including gecko and gaia. But you could build gaia or gecko independently to debug specific part of FirefoxOS.

All B2G related helper scripts are prefixed by B2G_.

Build Gecko only

Make sure you've synced local gecko folder to VM via command

$ GECKO_PATH=<local path> vagrant up

Then FoxBox provide an init script to help you fetch gecko source:

$ ./gecko_init.sh

It will install mercurial, clone gecko source to gecko folder, and put the b2g client build config in gecko/.mozconfig.

Then go to gecko folder and type

$ cd gecko
$ ./mach build

If you saw 'please rerun mach' message, run the command again:

$ ./mach build

All gecko related helper scripts are prefixed by gecko_.

You can refer to the full build guide

Step 3: Test in GUI

To test Firefox OS, you'll need the graphical display of VM. ssh does not support GUI. Run the command To start the GUI (powered by lxde):

$ ./gui.sh

The firefox nightly is located in the top left Applications Menu > internet > Nightly Web Browser.

To start emulator, press Application Menu > Terminal Emulator from left top and run command:

$ B2G/run-emulator.sh

Trouble Shooting

Disable bridge

From foxbox 0.6 it will add extra bridge network in settings to make sure the repository fetching works more smoothly. It require you select the network interface for outgoing network when you vagrant up the VM.

You could disable it by editing Vagrantfile and comment out

config.vm.network "public_network"

Delete the VM

You can run following command to delete the VM anytime.

$ B2G_PATH=<local path> vagrant destroy

The shared folders will be detached and the VM will be deleted. The basic vagrant box and the fetched source code will still exist so you don't have to fetch again.

Share failed

When you got message:

NFS is reporting that your exports file is invalid. Vagrant does
this check before making any changes to the file. Please correct
the issues below and execute "vagrant reload":

It usually happened if you had some previous images/boxes installed in my virtual box, so there were a few invalid entries in /etc/exports already. So I had to clean up that file and restart my vagrant box.

sudo rm /etc/exports
sudo touch /etc/exports

vagrant halt
./configure.sh

(Edit from stackoverflow)

Rerun the configure process

If there's any issue that make the setup process fail. You can re-run the configure process by following command:

$ launch.sh

It will update to latest foxbox and provide a shortcut to do the following operation for you.

$ B2G_PATH=${PWD}/B2G vagrant reload --provision

Repo sync failed

According to StackOverflow, invoking following command did the trick:

$ repo sync -f -j10

As it seems -f or --force-broken flag allows it to recover from network error and more important recover on broken/missing objects.

Goal

Short term

• enable developer jump into gaia development without pain

Mid term

• Utils
  • backup/restore tool
• ship a preconfigured box with b2g source
• l10n and keyboard layout settings
• customization

Long term

• Local test Firefox OS in VM