Application SDK Your First App

From SailfishOS Documentation

Your First App

If you don’t have the SDK installed and running yet, follow the installation guide.


Launch SailfishOS IDE

You can launch from the ‘SailfishOS IDE’ entry in the system menu (or from ~/SailfishOS/bin/qtcreator if you’re a Linux terminal person).


As an example, on Ubuntu, open the dash, type in ‘sailfish’. Click on the ‘SailfishOS IDE’ icon to launch the IDE.

Application sdk first app-ubuntu dash qtc.png


Create a Sailfish UI Project

The SDK comes with a Sailfish UI template project that makes it very easy to get started.

1. In the IDE, click on File→New File or Project.

Application sdk first app-qtc new project.png

2. Select Applications→SailfishOS Qt Quick Application and then click Choose.

Application sdk first app-qtc choose template.png

3. Give a name to your project. Ensure it is created somewhere under your home directory and click Next.

Application sdk first app-qtc template 01.png

4. Select MerSDK-SailfishOS-armv7hl (for ARM devices, e.g. the Jolla phone) and MerSDK-SailfishOS-i486 (for Intel devices, e.g. the emulator) kit and click Next.

Application sdk first app-qtc template 02.png

5. You can edit the short description of your project or just click Next.

Application sdk first app-qtc template 03.png

6. Click Finish.

Application sdk first app-qtc template 04.png

7. The project template is imported into your project and opened in the editor.

Application sdk first app-qtc open project.png


Launch the Mer Build Machine and Emulator

The Sailfish OS SDK uses a Mer build machine to compile your code and another virtual machine to run an emulator. If these are not running when you attempt to build or deploy an application you will be asked to start them.

Note: The Mer build machine needs access to your source code to compile it and by default your home directory is shared – this is why the project should be in your home.


When a Sailfish OS project is open, the SDK automatically displays two control buttons in the left toolbar for starting/stopping the Mer build machine and Emulator.

Application sdk first app-toolbar icons.png


1. Click on the Application sdk faq-mersdk icon.png icon to launch Mer Build Engine.

The Mer Build Engine is started in the background and the icon will turn gray until the machine has booted up.


2. Click on the Application sdk faq-emulator icon.png icon to launch the emulator. NOTE: This icon is only available if the MerSDK-SailfishOS-i486 kit is active. You can activate the MerSDK-SailfishOS-i486 kit from menu Build → Open Build and Run Kit Selector….

A new VirtualBox window opens and boots up the emulator.


Successful connection

When the Qt Creator can successfully connect to both the emulator and Mer build machine, the icons are updated as shown below.


Before connection:

Application sdk first app-toolbar icons start.png

Connection established:

Application sdk first app-toolbar icons stop.png


Create a Connection to Mer Hardware Device

Sailfish OS SDK can also deploy application to Mer hardware device. This feature requires a valid Mer hardware device to be set-up with USB or WLAN connection to computer and making sure that it is possible to connect to it over SSH with password. When using Mer hardware device as development device in SDK a valid kit needs to be selected (such as SailfishOS-armv7hl target).


Mer hardware device setup is done using Qt Creator’s device settings. Depending on your host environment this is found from either the menu Tools→Options→Devices or Qt Creator→Preferences→Devices. In this settings view, click Add… to start creating device settings.


Unless some custom configuration is used, these default values work just fine. If you encounter timeouts with SSH connections on your PC, you can modify the timeout setting also after the device has been created. Connect the device now, enter your SSH password and press Test Connection as described in the dialog. On successful completion, you can click Next to continue.

Application sdk first app-mer hw select.png

In the next dialog, you can review and further adjust connection related configuration. Click Next to continue.

Application sdk first app-mer hw configure.png

In next dialog just click Next unless you want to abort device creation. In that case click Cancel.


Qt Creator shall then create device configuration, deploy the SSH key to device and finally test the setup. In those dialogs user can only click Close to go to next phase.


Once tested and verified, Qt Creator shows a view which shows the created device. Notice that configuration files are not updated yet, so if you don’t press OK or Apply changes will not be saved.


That’s it. Now Qt Creator can deploy your application to device.


Set ARM Kit to Deploy to Device

By default ARM kit will create RPM binaries, it won’t even try to deploy to device. The deploy option Deploy by Building an RPM Package is selected. This can be changed from Qt Creator’s main view with deploy options, select Deploy as RPM Package or Deploy by Copying Binaries. mer-arm-kit-select-deploy

Application sdk first app-mer arm kit select deploy.png

Congratulations! Now you can build and deploy to Sailfish ARM device.


Build and Deploy the App

Press the Application sdk first app-qtc run button.png button in the toolbar to compile and run the project on the emulator.


That’s it! You just ran your first Sailfish OS application. It should be running in the emulator as shown below.

Application sdk first app-emulator screenshot 01.png


Deploy by Building an RPM Package

The default deploy option for ARM is to only build RPM packages. In this case the green Run button stays gray, because this option does not require or define a device to deploy to. To create the RPM packages, click on Build → Deploy Project “projectname”.


Next steps: exploring how to use the application.