Why?

We want to make it as easy as possible for as many developers as possible to write apps for Ubuntu Touch. Many mobile app developers choose OSX as their primary development environment. Let's make it easy for them.

• These instructions were developed and tested on a relatively clean OSX 10.9 (Mavericks) installation.

• These instructions assume some familiarity with the OSX command line (Terminal app) and basic Unix-like concepts. To learn more about Linux and Unix in general, you should install Ubuntu.

Installing Ubuntu Touch onto a supported mobile device is fairly easy, especially if you have already configured your machine for Android app development. We describe two methods for doing so -- the manual method and the automated method. Each method has pros and cons.

Installing manually, with no setup

Pros:

• Minimal setup (assuming you are already familiar with Android app development on OSX)

Cons:

• Can be tedious if you want to install the OS image multiple times, or if you will install different versions in the future

The basic outline is:

• Obtain a mobile device supported by Ubuntu Touch
• Install Android Studio to obtain tools like adb and fastboot
• Download the proper Ubuntu Touch images for your device
• Manually flashing your device with adb and fastboot

Follow the Manual Download Installation instructions

Automated installation, with one-time setup

Pros:

• Will save time over the long run if you install the OS image multiple times

Cons:

• Longer one-time setup that involves installing a number of software dependencies

The basic outline is:

• Obtain a mobile device supported by Ubuntu Touch
• Install homebrew to get access to bzr and xz
• Install Android Studio to obtain tools like adb and fastboot
• Install the go language runtime and udbflash
• Flash your device with Ubuntu Touch

homebrew install bzr, xz

If you have not already installed homebrew, you should do so. It is marketed as "the missing package manager for OS X". Homebrew is required to get access to the following dependencies:

• bzr - version control system, pre-dates git, and used by Ubuntu

• xz - LZMA compression tools, superior to gzip (and stuffit )

Read the homebrew documents for the full story, but the quick summary is to issue the following at a Terminal:

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go/install)"
brew doctor
brew install bzr
brew install xz

After install bzr, you will get a message about modifying your python path. You should do so by modifying your ~/.bashrc

export PYTHONPATH=/usr/local/lib/python2.7/site-packages:$PYTHONPATH

You should also double-check to ensure that your shell is reading ~/.bashrc when you login. Check your ~/.bash_profile

source ~/.bashrc

Close your Terminal session and open a new one (or manually issue source ~/.bashrc). You may now optionally configure bzr:

bzr whoami "Billy Everyteen <me@here.com>"

This command is the equivalent of combining setting your username in git and setting your email in git.

You can always go learn more about bzr if you wish, but it's not required at this stage.

Install Android Studio

Flashing Ubuntu Touch requires the Android tools adb and fastboot. These are provided freely as part of the Android SDK.

There are two options for Android development IDEs. These instructions use Android Studio (based on IntelliJ) since Google seem to be deprecating Eclipse.

Download and install Android Studio.

Once this is done, you will need to ensure that your $PATH includes adb and fastboot. Assuming you used the default installation settings for Android Studio, add the following to your ~/.bashrc.

export PATH=$PATH:/Applications/Android\ Studio.app/sdk/platform-tools/

There is more information about setting up adb on OSX at stackoverflow.

Install go language runtime

When using Ubuntu Desktop as a development environment, you would use the phablet-tools package to push files onto your mobile device. Installing those tools in Ubuntu is easy because you can use the power of apt-get install to grab all the dependencies.

phablet-tools and its dependencies have not been ported to brew. Instead, we can use the go version of the tools which are more self-contained and thus easier to install in OSX.

First, we must install go for OSX. The easiest way to install is to use the "Mac OS X package installer".

Next, we install the golang version of phablet-flash, which is currently named udbflash.

There doesn't seem to be a convention in OSX for where to store development projects. In Ubuntu, we recommend ~/Projects so we adopt the Ubuntu convention for OSX.

Create the following directory structure:

mkdir -p ~/Projects/go

The above path will become your GOPATH. For more reference on this, see:

• http://stackoverflow.com/questions/7970390/what-should-be-the-values-of-gopath-and-goroot

• https://code.google.com/p/go-wiki/wiki/GOPATH

Edit your ~/.bashrc one final time:

export GOPATH=$HOME/Projects/go
export PATH=$PATH:$GOPATH/bin:/Applications/Android\ Studio.app/sdk/platform-tools

Close your terminal session and reopen it or source your ~/.bashrc again.

You are now finally ready to install the udbflash tools

go get launchpad.net/phablet-tools/udbflash

One-time setup to prepare phone for flashing

You are almost ready to flash your phone. There are some final one-time setup steps to prepare the phone. Similar to the above instructions to setting up your OSX machine, you only need to do these once.

Perform steps 1.5, 2, and 3 from the official installation instructions.

Do not do step 4 from that page.

• 1.5 - Optional Android Backup

• 2 - Device unlock

• 3 - Initial Device Setup

Flash Ubuntu Touch onto your device

Finally! Instead of step 4 on that page, we will use udbflash. Here is the sequence of commands verified to work.

This sequence of commands may cause you to lose any data you have on the device.

$ adb devices
List of devices attached 
008f5b00d6518b29        device

$ adb reboot-bootloader

$ fastboot devices
008f5b00d6518b29        fastboot

$ ./udbflash --bootstrap=true --channel="trusty"

This sequence of commands may take a long time to run. You will see the device reboot several times into a variety of screens. Please be patient. This is sample terminal output resulting from a successful flash. Note the final line indicating success, "Rebooting into recovery to flash"

2013/12/17 17:45:49 Device is |mako|
2013/12/17 17:45:51 Flashing version 70 from trusty channel and server https://system-image.ubuntu.com to device mako
35.39 MB / 35.39 MB [====================================] 100.00 % 183.77 KB/s 
274.87 MB / 274.87 MB [==================================] 100.00 % 362.28 KB/s 
[...]
2013/12/17 17:59:04 Start pushing /Users/achiang/.cache/ubuntuimages/gpg/image-signing.tar.xz to device
[...]
2013/12/17 17:59:46 Created ubuntu_command: /Users/achiang/.cache/ubuntuimages/ubuntu_commands786908010
2013/12/17 17:59:46 Rebooting into recovery to flash