Platform SDK Installation

From SailfishOS Documentation

Attention: These instructions are only valid for Platform SDK versions newer than or equal to 2.1.3. If you have an older Platform SDK, please upgrade it or use the old instructions. If you are doing a fresh installation, please ignore this note.

The SailfishOS platform SDK contains Development Tools like Scratchbox2, MIC (Image Creation), Spectacle, osc, qemu, etc, to make it easier for a developer to work with SailfishOS.

Quick start

If you're in a hurry then this should get you going (if it doesn't work then read the full instructions carefully!) :

export PLATFORM_SDK_ROOT=/srv/mer
curl -k -O ;
sudo mkdir -p $PLATFORM_SDK_ROOT/sdks/sfossdk ;
sudo tar --numeric-owner -p -xjf Jolla-latest-SailfishOS_Platform_SDK_Chroot-i486.tar.bz2 -C $PLATFORM_SDK_ROOT/sdks/sfossdk  ;
echo "export PLATFORM_SDK_ROOT=$PLATFORM_SDK_ROOT" >> ~/.bashrc
echo 'alias sfossdk=$PLATFORM_SDK_ROOT/sdks/sfossdk/mer-sdk-chroot' >> ~/.bashrc ; exec bash ;
echo 'PS1="PlatformSDK $PS1"' > ~/.mersdk.profile ;
echo '[ -d /etc/bash_completion.d ] && for i in /etc/bash_completion.d/*;do . $i;done'  >> ~/.mersdk.profile ;

Once you've installed the Platform SDK you'll need to installation a Platform SDK Target.

It's recommended that you read sections below for pre-requisites, options and details on installing extra architecture toolchains, tools etc.

Platform SDK

The default download contains:

  • Development tools
  • Image creation tools
  • OBS development tools

You can also install :

  • Debugging tools
  • Testing tools
  • Python development
  • Ruby development


Sailfish OS Platform SDK builds on the Scratchbox 2 cross-compilation toolkit. Scratchbox 2 solves the problem of cross-compilation by creating a virtual development environment that looks like a target system while allowing execution of both target-compatible and host-compatible binaries transparently (where "host" means the machine where software is built).

Scratchbox2 achieves this by employing target CPU emulation and by composing a single virtual file system view from four physical locations:

  • Host filesystem
    • Contains Scratchbox 2 itself
    • Contains generic (as opposite to target-specific) tools (e.g SCM tools, build automation tools, editors)
    • Host-compatible binaries
  • Tools distribution
    • Contains target-specific tools (e.g. cross-compiler toolchain)
    • Host-compatible binaries
  • Target device filesystem image
    • Target-compatible binaries
  • User's working directory
    • Contains source code and build artefacts
    • Target-compatible binaries

The existence of the Tools distribution concept enables development for different target systems within single SDK installation. Without this only targets compatible with the exact version of tools available directly from the Host filesystem could be supported within a single SDK installation.

Here is how the terms native to Scratchbox2 map to the terms used in Sailfish OS Platform SDK:

Scratchbox2 Sailfish OS SDK
Host filesystem Platform SDK Chroot
Tools distribution Sailfish SDK Tooling (*)
Target device filesystem image Sailfish SDK Target

(*) The word "tooling" is used instead of "tools" simply for the possibility to distinguish single from multiple.

Installing the Platform SDK

SDK Requirements

The Platform SDK will run on most modern Linux machines. It needs:

  • Linux distribution (one in a virtual machine works well), running 2.6.37 or newer kernel
  • about 400Mb free space to install
  • The SDK must be installed on a standard filesystem and "nosuid" must not be set. (Note: recent ecryptfs will automatically use and enforce nosuid. Automounted usb drives typically have "nosuid" set too.)
  • hundreds of Mb for rpm caches for osc and mic as well as for SB2 targets
  • Generic x86 CPU
  • user must have sudo rights

Installation / setup

The Platform SDK is provided as a rootfs tarball that contains essential tools for Sailfish OS platform development along with a helper script to enter the rootfs.

Filesystem requirements:

  • The Platform SDK can be installed to any location with enough space - we'll use /srv/ as per the Linux FHS (feel free to adapt the commands to use any other location).
  • The installation path must contain an intermediate directory called 'sdks' which only has Platform SDKs inside. eg /srv/mer/sdks/sfossdk/...

To setup the Platform SDK:

  • Download the latest stable Platform SDK rootfs tarball with the common armv7hl toolchain preinstalled:
curl -k -O 
  • Optionally, you can check the release notes from the Application SDK Release Notes. The SDK Build Engine section also contains the latest changes to the Platform SDK.
  • Create a directory for the Platform SDK rootfs and extract the tarball as root or with sudo:
sudo mkdir -p /srv/mer/sdks/sfossdk
sudo tar --numeric-owner -p -xjf Jolla-latest-SailfishOS_Platform_SDK_Chroot-i486.tar.bz2 -C /srv/mer/sdks/sfossdk

Platform SDK control script

The Platform SDK rootfs contains a helper script to enter the chroot named 'mer-sdk-chroot'. The helper script is located in the root directory (/) of the rootfs. It requires you to have sudo ability.

As mentioned, the Platform SDK is location independent so it uses the location of the helper script to determine which Platform SDK to enter.

Entering Platform SDK

Before entering the Platform SDK you may want to make an Platform SDK equivalent of ".profile" to give you a nice prompt to remind you that you are in the Platform SDK. This also reads the bash autocompletion scripts from inside the chroot.

cat << EOF >> ~/.mersdk.profile
PS1="PlatformSDK \$PS1"
if [ -d /etc/bash_completion.d ]; then
   for i in /etc/bash_completion.d/*;
      . \$i

If you use multiple Platform SDK instances, you can utilise the MERSDK shell variable to determine the absolute path to the Platform SDK chroot in use (since Sailfish OS release 2.1.3).

To enter the Platform SDK rootfs with the helper script run


You should find that you are operating under your normal username and that your home directory is available as /home/<username> and any other mountpoints are mounted under /parentroot/*

You have sudo rights automatically. If sudo fails within the sdk, make sure that the filesystem the sdk is on is not mounted with the "nosuid" parameter. "mount" on the host system gives you this information, add "suid" as parameter in fstab, if necessary.

Useful Alias

If you tend to use a single instance of the Platform SDK then this alias is useful

 echo alias sfossdk=/srv/mer/sdks/sfossdk/mer-sdk-chroot >> ~/.bashrc ; exec bash

Next Steps

The next step is to look at setting up the Platform SDK Targets and installing and using more Development Tools

Updating the Platform SDK

Attention: Sailfish OS Platform SDK before Sailfish OS release version 2.1.3 did not support simultaneous installation of SDK Targets for multiple Sailfish OS versions. If you are using such an older SDK you should ensure that the Platform SDK release version matches the SDK Target release versions and you should only update your Platform SDK after all SDK Targets are updated.

You can check your current release version by executing ssu re in the SDK. For a newer SDK release version check out the Application SDK Release Notes. In this example we will use Jolla release

 sudo ssu re
 sudo zypper ref
 sudo zypper dup

Removing the Platform SDK

Remove all SDK Targets and Toolings, then simply exit all chroot instances and, using sudo, remove /srv/mers/sdks/sfossdk.


Multiple Platform SDKs

You should be able to install and connect to multiple Platform SDKs at the same time.

Known Issues

work around bug #554 : mic failure

To work around a bug #554 add the following to ~/.mersdk.profile (e.g. Fedora >= 17 needs that):

export PATH=$PATH:/sbin

"not enough disk space left" or similar

If you do actually have enough disk then the problem is possible that the kernel on your host is too old. To run Platform SDK you should be running kernel 2.6.37 or newer on your host.