How to install SailfishOS SDK on OSX – the Dummy Guide

Two days ago I started to install SailfishOS SDK on my Mac Mini using the instructions from Martin Grimme published in SailfishOS mailing list. As a non-seasoned Virtualbox (or a Mac) user it took me several hours and lots of questions in the mailing list to take me where I am now. Currently I have fully functional SDK installation on my Mac Mini, and I decided to write down this guide to help others do the same. The guide will be based on the bullet point guide from Martin, but will have some additions such as tips and don’t dos from me, to avoid readers to do same mistakes I did.

Step 1: Get Linux Running on Virtual Machine

* Install VirtualBox on your host OS. Give it at least 1.5 GB of RAM. After the whole setup process, you may push this down to about 500 MB, if desired.

* Install Linux in a VirtualBox. Ubuntu 12.10 32 bit works just fine.

Give it at least 12 GB of hard drive space, otherwise it runs out when installing the SDK. Dynamically expendable should be fine. After the installation you’ll be asked to reboot Ubuntu. At least for me, the Virtual machine got stuck for ages in “The system is going down for reboot NOW!” phase, so I decided not to wait and manually powered off the VM, and started it again from the VirtualBox manager. That seemed to be ok.

* Don’t forget to install the guest additions as well, because we will have to use shared folders.

You can install them from the Devices menu, selecting Install Guest Additions.

Step 2: Get the SDK in it

* Install VirtualBox on Linux and install the Sailfish SDK afterwards.

Select 32 bit version of Sailfish SDK, if you installed 32 bit version of Ubuntu. After you’ve downloaded SailfishOS SDK run
sudo chmod +x
to make it executable and start the installation

* The suggested installation path /home/<user>/SailfishOS is fine. Do not install the SDK into a shared folder as shared folders don’t support creating symlinks.

Step 3: Get the Virtual Machines Out of It

* Open the VirtualBox configurator on Linux and export the two virtual machines ‘MerSDK’ and ‘SailfishOS Emulator’ by selecting ‘File -> Export Appliance’. This will take some time. Move the resulting .ova files to your host OS (Mac OS-X in my case).

* Create a directory ‘MerHome’ on your host OS, e.g. /Users/<user>/MerHome. Inside MerHome, create three directories:

– emulator
– mersdk
– projects

Now you have to copy stuff from your virtual machine to your host OS. I used shared folders for that. You can share folders from your host from the virtual machine shared folders settings, and then mount and unmount them in Linux
sudo mount -t vboxsf mount_name mount_point
sudo umount mount_name

* Copy the SailfishOS/emulator/ssh directory from Linux into the just created directory ‘MerHome/emulator’ on the host OS.

* Copy the SailfishOS/mersdk/ssh directory from Linux into the just created directory ‘MerHome/mersdk’ on the host OS.

* Copy the ~/.scratchbox2 directory from Linux into the just created directory ‘MerHome’ on the host OS.

* Open a terminal on Linux and pack up the targets directory:

cd SailfishOS/mersdk
tar -czf targets.tar.gz targets

* Move the file targets.tar.gz to your host OS into ‘MerHome/mersdk’ and unpack it there:

cd MerHome/mersdk
tar -xzf targets.tar.gz

Step 4: Get the Virtual Machines on Your Host

* Open the VirtualBox configurator on your host OS and import the two recently exported VirtualBox appliances by selecting ‘File -> Import Appliance’.

* Edit the shared folders settings of the ‘MerSDK’ virtual machine:

home -> <your MerHome>
ssh -> <your MerHome>/mersdk/ssh
targets -> <your MerHome>/mersdk/targets

* Make sure that you don’t change the mount names during this action.

Be careful with this one, cause I managed to change “home” to “MerHome” even without touching the target name.

* Edit the shared folder settings of the ‘SailfishOS Emulator’ virtual machine:

ssh -> /emulator/ssh

Make sure that you don’t change the mount name during this action.

* You may optionally also want to activate audio while in the ‘SailfishOS Emulator’ settings.

* Test-run the MerSDK virtual machine on the host OS. Does it come up with the message ‘mounted home and targets successfully’? Then the shared folders settings ought to be OK. Close the virtual machine (saving machine state instead of shutdown is fine).

Step 5: Prepare your workspace

* Add the directory ‘MerHome/projects’ to the shared folders of your Linux virtual machine. This may be done while the machine is running.

* In your Linux home directory create an empty directory with the same name ‘projects’.

* As root, add the following line to /etc/fstab on Linux:

projects /home/<user>/projects vboxsf rw,uid=1000,gid=1000 0 0

Replace with your username and use the GID and UID of the user. On Ubuntu, the first user normally has GID = 1000 and UID = 1000.

If you have multiple users or groups, or want to be sure, you can double check them using id tool
id -u <username>
id -g <username>

* As root, mount the projects shared folder:

mount projects

* Open the VirtualBox configurator on Linux and change the host keyboard key in the global settings to something different than on the VirtualBox on your host OS.

Step 6: Fake VBoxManage Output

* Start the two virtual machines on Linux with the VirtualBox configurator. They will be very slow (as you’re running VirtualBox inside VirtualBox), so you need to have some patience until they’re fully loaded. Fortunately this has to be done only once. You will later never have to use VirtualBox inside VirtualBox again.

* Record the output of VBoxManage that the Sailfish SDK expects:

VBoxManage showvminfo MerSDK --machinereadable
VBoxManage list runningvms
VBoxManage showvminfo “SailfishOS Emulator” --machinereadable

The names of the record files contain the md5 sum of the command, so
they must match exactly.

* Stop the two virtual machines.

* In the Linux virtual machine, locate your VBoxManage program. On my Ubuntu installation, this is ‘/usr/share/virtualbox/VBoxManage’. Become root and move the file to VBoxManage.orig

On my installation, the binary was found from ‘/usr/lib/virtualbox/VBoxManage’.
If you don’t find it from either of the locations, you can locate the binary using find:
find / -name "VBoxManage" 2>/dev/null

sudo su
cd /usr/share/virtualbox
mv VBoxManage VBoxManage.orig

* Save this script as VBoxManage. It will record the output of VBoxManage and later replay that output for the Sailfish SDK.

#! /bin/bash

VBOXMANAGE=`dirname $0`/VBoxManage.orig
COMMAND=`echo “$@” | md5sum | cut -d” ” -f1`

if [ ! -f ${RECORDFILE} ]; then
exit $?

Dont forget to give the script executable rights:
sudo chmod +x VBoxManage

Step 7: Finalize the installation

* Start the two virtual machines ‘MerSDK’ and ‘SailfishOS Emulator’ on your host OS. Their performance will be far better than inside the Linux virtual machine.

* Make sure that your host OS runs a ssh server. Find out the host IP and connect to it from Linux, tunneling the ports used by the SDK.

From Mac OSX you have to tick “Remote Login” from System Preferences -> Sharing to start the ssh server. You can then find out your ip using ifconfig, or use your mac’s local name.

ssh -l \
-L 2222:localhost:2222 \
-L 2223:localhost:2223 \
-L 8080:localhost:8080 \
-L 10000:localhost:10000 \
-L 10001:localhost:10001 \
-L 10002:localhost:10002 \
-L 10003:localhost:10003 \
-L 10004:localhost:10004 \
-L 10005:localhost:10005 \
-L 10006:localhost:10006 \
-L 10007:localhost:10007 \
-L 10008:localhost:10008 \
-L 10009:localhost:10009 \
-L 10010:localhost:10010 \
-L 10011:localhost:10011 \
-L 10012:localhost:10012 \
-L 10013:localhost:10013 \
-L 10014:localhost:10014 \
-L 10015:localhost:10015 \
-L 10016:localhost:10016 \
-L 10017:localhost:10017 \
-L 10018:localhost:10018 \
-L 10019:localhost:10019

This ssh connection needs to be established all the time while you’re using the SDK.

* Start the Sailfish SDK QtCreator on Linux. It should be able to connect and use the virtual machines on your host OS now. You cannot start the virtual machines via QtCreator, though.

* IMPORTANT: Your Sailfish projects must all reside in the projects shared folder so that the MerSDK virtual machine will be able to find them.

Now you are ready to test your connection to the emulator in QtCreator.


If you’re seeing port 65535 in the ssh setting in QtCreators devices settings, go back to step 6. Probably something has gone awry with the VBoxManage recordings, and QtCreator cannot see the running SDK VM’s.

If the previous is not a problem, and the device connection test goes well, but you still see errors like “SailfishOS Emulator is not running”, you can try to hit “yes” when QtCreator asks if it should start the simulator, even if that does really nothing. Also it might need some certain combination of build/deploy/run to get your project run on the emulator, and QtCreator stop whining about not finding the SDK, but patience is good, and I hope you will have less problems with that than I did.

And finally the image I sent to Twitter, as soon as I got it working. I was pretty exited 🙂