Tutorial - Building packages manually

From SailfishOS Documentation
Revision as of 09:13, 7 July 2017 by Martyone (Talk | contribs) (Installing dependencies: Update link to cmakesample)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Sailfish OS provides a streamlined developer experience through the Sailfish IDE. At the moment it only provides for projects that are built with qmake. This might cause problems especially when porting over existing applications that use a different build system. Some developers might also prefer to use a different editor environment. This document aims to describe the steps to build an application manually using the Sailfish OS build machine that comes with the SDK. We use CMake in this document but the steps to take are roughly the same for any build setup.

Installing dependencies

The first thing you need to do is to install the Sailfish OS SDK. It can be downloaded from the Application SDK page. Next you should check out the sample application inside your home directory from this git repo. Now you can run Virtualbox and it should show both the build machine and the emulator. Start the MerSDK virtual machine.

You are now ready to install all the build dependencies that your software requires. We recommend declaring them in the spec file so they get installed automatically when you build your package with the mb2 command described below. For this example it only consists of CMake. Note that you should not log in to the machine from the terminal but instead always connect to it via SSH. You can minimize the VirtualBox window as you won’t need it for the actual work. Log in to the machine using SSH:

ssh -p 2222 -i ~/SailfishOS/vmshare/ssh/private_keys/engine/mersdk mersdk@localhost

Before going further let’s verify that everything is properly installed and that we are logged in the correct machine. Issue the following command:

sdk-assistant list

This should provide the following output:


This means that the build machine can build packages for both ARM and i486 platforms. The former is used for the device whereas the latter is for the emulator. We want to use both so we need to install CMake for both of these target types. This is achieved with the following two commands:

sb2 -t SailfishOS-armv7hl -m sdk-install -R zypper in cmake
sb2 -t SailfishOS-i486 -m sdk-install -R zypper in cmake

Building the packages

The SDK has set up VirtualBox shared folders so that your home directory is visible inside the build machine. You can find it in the directory /home/src1. The first step in starting the build is to go inside your project checkout. That can be accomplished with the following command:

cd /home/src1/cmakesample

Now you are ready to build the emulator and device packages. If you have set up a spec file the commands are simple.

mb2 -t SailfishOS-i486 build
mb2 -t SailfishOS-armv7hl build

Once the build finishes, you can find the RPM packages in the RPMS directory. If you wish to build your project manually, just wrap your own build commands with sb2 like this:

sb2 -t SailfishOS-i486 -m sdk-build cmake [cmake options]
sb2 -t SailfishOS-i486 -m sdk-build make

Now you can log out of the build machine.

Running the package in the emulator

It is very strongly recommended that you only deploy your application to the emulator and device as an RPM package. The following instructions only cover this case. Start the SailfishOS Emulator virtual machine now.

Deploying the package directly from the build machine

Deploying the package this way is very easy. The only thing you need to do is to run the following command:

mb2 --device "SailfishOS Emulator" deploy --sdk

This will move and install the package to the SailfishOS Emulator virtual machine.

Moving and installing the package manually

You can also move and install the package manually, but it's a little more work and could quickly become a bottleneck in the development process.

To transfer the RPM to the emulator, issue the following command.

scp -P 2223 -i ~/SailfishOS/vmshare/ssh/private_keys/SailfishOS_Emulator/root \ 
    cmakesample-1.0-1.i486.rpm root@localhost:

Then log in the machine.

ssh -p 2223 -i ~/SailfishOS/vmshare/ssh/private_keys/SailfishOS_Emulator/root \ 

Install the RPM with the following command:

rpm -i cmakesample-1.0-1.i486.rpm

This causes the application icon to appear in the menu. Tapping on the icon launches the application.

Congratulations, you have successfully built a Sailfish OS application with a custom build system.

Deploying and running the app on the device

Deploying the app directly from the build machine

Deploying on the device is straightforward. First open up the Sailfish OS IDE and add a new Mer hardware device in the preferences. Then issue the following command in the build machine:

mb2 --device "Example device" deploy --sdk
# "Example device" is the name of the device in the IDE (e.g. "Jolla C")

Now your application has appeared in the list of installed applications and is ready to be run.

Deploying the app manually

First you need to set the device to developer mode and transfer the RPM file to the device.

scp cmakesample-1.0-1.armv7hl.rpm nemo@

Then you can to log in to the device and become root.

ssh -lnemo

The last step is to install the package:

pkcon install-local cmakesample-1.0-1.armv7hl.rpm

Now your application has appeared in the list of installed applications and is ready to be run.