To ease development of applications for Sailfish OS and to make sure paths for the applications are set correctly and application startup time is accelerated, third party applications on Sailfish OS should use libsailfishapp. This library provides certain convenience functions within the SailfishApp namespace to set up your project, install all files into the right directories, and get important paths at runtime via convenience methods.

This document also serves to describe the functionality of libsailfishapp so that developers who cannot use it in their projects can use the info provided here as a guide for how to replicate the directory layout and paths. However, we generally recommend using libsailfishapp where possible, as it will allow applications to easily and automatically integrate well with Sailfish OS.

API documentation

For more specific API documentation, see the SailfishApp namespace documentation.

How to use SailfishApp in your project

To use SailfishApp in your project:

1. Add BuildRequires: pkgconfig(sailfishapp) to your .spec file
2. Set TARGET = harbour-yourappname in your .pro file
3. Add CONFIG += sailfishapp to your .pro file
4. Include sailfishapp.h in your .cpp file
5. Use the SailfishApp:: methods in your main()

In the rest of this document, we will refer to the value of the TARGET variable in your .pro file as $$TARGET (this is also how you can use the variable itself in the .pro file).

Files that get installed by libsailfishapp and have to be present in the same directory as the .pro file:

• $$TARGET.png - An 86x86 pixel application icon
• $$TARGET.desktop - The .desktop file for your app
• qml/ - A folder containing all your QML files

If you want to opt out of automatic deployment of the qml/ folder, set CONFIG += sailfishapp_no_deploy_qml before adding the SailfishApp configuration option. You might want to set this option if for some reason you intend to ship your QML files as Qt Resources (qrc). We recommend that you keep the default setup and install QML files in the filesystem instead.

Deploying app icons in multiple sizes

It's recommended that you provide application icons in multiple sizes, to support different device types and different screen DPI settings. You can do this with the following steps.

1. Add SAILFISHAPP_ICONS = size1 size2... to your .pro file, enumerating all available icon sizes in the form WIDTHxHEIGHT
2. Ensure all icons are present as icons/WIDTHxHEIGHT/$$TARGET.png in the source tree

For a list of recommended icon sizes, see the Harbour FAQ. The Sailfish App Icons Guidelines include useful and important material about how to design your apps to best suit the Sailfish OS style.

Using i18n support in your project

To use the internationalization convenience features of SailfishApp, do the following.

1. In your main .pro file, add:

    CONFIG += sailfishapp_i18n

   If you use id based translations also add:

    CONFIG += sailfishapp_i18n_idbased

2. Run qmake
3. Run make (this will create or update the file translations/$APPNAME.ts and all files in TRANSLATIONS)
4. In your RPM packaging .yaml file, add the following entry to the files section:

    - '%{_datadir}/%{name}/translations'}

To add a new language to your project:

1. In your main .pro file, add (with $LANG replaced with the language):

    TRANSLATIONS += translations/$APPNAME-$LANG.ts}

   (for example, for German, use "$APPNAME-de.ts", etc...)

2. Run qmake
3. Run make

If during development you want to skip building the translations every time, you can simply comment out the line

 CONFIG += sailfishapp_i18n

in your qmake .pro file and the translations will not be built/updated. Be sure to re-enable the line when you do the release build.

Further information

For further information about how to use libsailfishapp, refer to the Sailfish SDK User Manual.