Libsailfishapp DocsAPI 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:
BuildRequires: pkgconfig(sailfishapp)to your .spec file
TARGET = harbour-yourappnamein your .pro file
CONFIG += sailfishappto your .pro file
sailfishapp.hin your .cpp file
- Use the
SailfishApp::methods in your
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.
In case you provide application icon in multiple sizes:
SAILFISHAPP_ICONS = size1 size2...to your .pro file, enumerating all available icon sizes in form
- Ensure all icons are present as
icons/WIDTHxHEIGHT/$$TARGET.pngin the source tree
How to use i18n support in your project
To use the internationalization convenience features of libsailfishapp:
- In your main .pro file, add:
CONFIG += sailfishapp_i18n
If you use id based translations also add:
CONFIG += sailfishapp_i18n_idbased
make(this will create or update the file
translations/$APPNAME.tsand all files in TRANSLATIONS)
- In your RPM packaging .yaml file, add the following entry to the files section:
To add a new language to your project:
- 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...)
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
- How to create a new
- How to use
SailfishApp::pathTo()for file paths
- How for the most generic case one can use
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
Storing application data and cached files
To store application data, use the location returned by
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
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.