libsailfishapp documentation

To ease development of applications for Sailfish 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 to set up the 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 libsailfishapp in their projects can use this document 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.

How to use libsailfishapp in your project

To use libsailfishapp 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 86×86 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.

 

How to use i18n support in your project

To use the internationalization convenience features of libsailfishapp:

  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.

 

libsailfishapp C++ API

TODO: Describe the API calls libsailfishapp provides

  • How to get the QGuiApplication instance
  • How to create a new QQuickView
  • How to use SailfishApp::pathTo() for file paths
  • How for the most generic case one can use SailfishApp::main()

 

libsailfishapp QML-only launcher

TODO: Describe how to build a project without any C++ that can still access private QML imports and the Sailfish Silica API.

 

Custom context properties

TODO: Explain where and how to set up custom context properties so they are exposed in the QML view.

 

Custom QML types registered at runtime

TODO: Describe how one can use qmlRegisterType with libsailfishapp and the naming requirements for Harbour QA.

 

Installing and using private shared libraries

TODO: Describe where to install shared libraries, how to link against them and how libsailfishapp takes care of the rpath

 

Installing and using private QML imports

TODO: Describe where to install private QML imports, how to import them in QML code, how libsailfishapp sets the import path and the naming requirements for Harbour QA.

 

Storing application configuration files

To store application configuration files, you can use the standard QSettings class with the default constructor, which will use the application and organization name (set correctly by libsailfishapp to the application name, which is the binary name in case of C++ applications or the first argument in case of QML-only applications with the sailfish-qml launcher).

 

Storing application data and cached files

To store application data, use the location returned by
QStandardPaths::writableLocation(QStandardPaths::DataLocation)

To store cache files (these files can be removed at any time by the system if disk space is low, and these files are not guaranteed to be backed up), use the location returned by
QStandardPaths::writableLocation(QStandardPaths::CacheLocation)

You can also use the Qt Quick Local Storage API to store data directly from your QML-only Sailfish Application. libsailfishapp will make sure that your application uses a application-specific storage directory.