Using Colemak on the FirefoxOS Flame
2014-10-03

As I mentioned in my previous post, I have been using a FirefoxOS
Flame developer reference phone as my daily driver. It has now
been about two months, and I couldn't be happier with the phone
(you can read my initial review of the Flame here [0]
    
I use the Colemak layout for all of my keyboards, so I was
disappointed when the FirefoxOS 2.2 builds had the Dvorak layout
but not Colemak. As any good developer would do, I promptly cloned
the gaia repo[1]
and got ready to muck around in the system's keyboard app. Much to
my initial dismay of being able to contribute something sweet to
the community, I found that the Colemak layout was already there,
it just wasn't enabled in the default list of layouts to
build. This means that instead of hacking together some JS, all
that is required to get the Colemak layout on your device is
editing one line in a Makefile, building gaia, and flashing onto
your device.

    ** You should backup your device before mucking around in gaia **

I am not going to write about hacking on Gaia itself, that
information can be readily had from Gaia's MDN page[2].

Adding Colemak to the Keyboard Layouts
In order to get the Colemak layout on your FirefoxOS device you
must first get the gaia source. It can be cloned from Github by
doing:

        git clone https://github.com/mozilla-b2g/gaia
	    cd gaia
        
You can look in the /apps/keyboard directory to see the source of
the system's keyboard app, but we aren't going to touch anything
in there. We are going to modify gaia's toplevel Makefile.
Open 'Makefile' in you editor of choice. Search for
'GAIA_KEYBOARD_LAYOUTS'. In my gaia repo it in line 440. This
environment variable is used to determine which keyboard layouts
will be built into the system's keyboard app - exactly what we
want to modify.
Feel free to modify this line as you see fit, but in order to get
the Colemak layout you must at least add 'en-Colemak' to the comma
separated list of layouts. Make sure to save the file after you
edit it.

Now comes the slightly scary part, we are going to build a new
version of gaia and flash it onto our FirefoxOS device. Following
these instructions[3] we can see what we need to do. On that page the
is a note about only flashing a single app instead of all of the
gaia apps; There is another MDN page[4] however that cautions that
using the APP environment variable with 'reset-gaia' will put your
device in an unstable state (my experimentation also confirms
this). So, we are going to have to build gaia in its entirety,
which doesn't take more that a few minutes.
    
First make sure that you have ADB installed on your machine. There
are installation instructions on MDN[5], and that you have enabled
USB debugging on your device from within the Developer menu.
    
Next connect your device to your machine. If you are using a Flame
device, you want to issue the following command:

        make reset-gaia GAIA_DEV_PIXELS_PER_PX=1.5


The GAIA_DEV_PIXELS_PER_PX environment variable specifies that you
want to use higher resolution assets. This is mentioned in a note
in MDN [6] but after the 'make reset-gaia' command so it is easy to miss it
the first time you build gaia.

Assuming there are no build failures, your device will reboot and
after you go through the initial setup screens, you will be able
enable the Colemak layout in the Keyboards Settings
panel.

[0] https://zachwick.com/posts/using_the_firefox_os_flame.txt
[1] https://github.com/mozilla-b2g/gaia
[2] https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia
[3] https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/Different_ways_to_run_Gaia
[4] https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/Build_System_Primer
[5] https://developer.mozilla.org/en-US/Firefox_OS/Debugging/Installing_ADB
[6] https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/Different_ways_to_run_Gaia