Sailfish Community News, 8th September, New Harbour APIs

Subscribe to future posts here :bell:

Sailfish OS update from Jolla

During the most recent Community Meeting we had an update from Ville Nummela (vige) who you’ll know as one of the managers of this forum, but who is also Technical Product Manager of Jolla’s Developer Offering.

Ville revealed that there will be several new APIs that will be allowed in the Jolla Store from the next release. We caught up with Ville to dig into the details, and try to find out exactly what’s happening in the Harbour.

There’s actually quite a list of new APIs which we are going to allow.

Ville explains.

Some of the APIs are more useful to developers than others. Perhaps the most anticipated new API is Sailfish Secrets and Crypto, which provides access to secure storage and cryptographic functions. These have been already used by quite a few apps, unfortunately rending them non-harbour-compatible until now.

Then we have a bunch of Sailfish UI components, which mostly provide Sailfish-looking components for various situations. These have been designed for platform apps, so their usability in third party apps can be quite low. Nevertheless, they are there now if someone wishes to use them.

QtLocation is also one that has been requested quite often. It provides map components. Our version is quite old, and there are better and more modern components for this purpose. But this one already exists in Sailfish OS, which might make it attractive for some.

And finally, we have Pillow, which is a python library for image processing.

Here we summarise the proposed new APIs. It’s possible not all of these will make it into the next release, so you should follow the repos prior to the 4.5.0 release if you want to be certain. Where documentation isn’t yet available, we’ve listed the installed location of the relevant QML components on-device:

API PR Repository Documentation
Sailfish Secrets and Crypto PR, PR Repo Docs
QtLocation PR Repo Docs
Sailfish Media PR N/A /usr/lib64/qt5/qml/Sailfish/Media
Sailfish Contacts PR, PR Repo /usr/lib64/qt5/qml/Sailfish/Contacts
Sailfish Accounts PR N/A /usr/lib64/qt5/qml/Sailfish/Accounts
Sailfish Telephony PR N/A /usr/lib64/qt5/qml/Sailfish/Telephony
Pillow PR Repo Docs
BluezQt PR Repo Docs

There has been a lot of encouragement from the developer community to allow these APIs in the Jolla Store. Many of you will recall the API Poll held by Ville at the end of 2020, in which Sailfish Secrets and QtLocation hit the third and fifth spots respectively (QtPositioning, which was fourth, was added already back in January 2021). More recently fridlmue raised the possibility of including QtLocation during a community meeting.

Clearly this has helped shape the choices for API inclusion, while also adding some extra momentum to the process. But if these are being added now, it raises the obvious question as to why they weren’t already added in the intervening two years. Ville explains.

Of course our motivation is to have as many useful apps in Jolla Store as possible. Unfortunately quite a few apps have been disqualified because they use APIs which have not been allowed. The reasons why a certain API has not been allowed vary.

If we look at the question from the “what has changed” point of view, one thing that stands out is Sailjail. As the end user has the ability to see what the applications have access to, we feel more confident in allowing them in Harbour. So the question has really changed from “Why should we allow this?” to “Why shouldn’t we allow this?”

That’s a significant change, and one that the introduction of Sailjail always promised to unlock. To elaborate on this a little further, granting access to the Accounts API for example, has security implications that the end-user should be aware of. If any app could have access to this API it might lead the way for apps to get access without the user’s knowledge. With Sailjail, the user is always made aware and has to agree to an app accessing Accounts, before the API can be used by the app.

That’s not the only thing that’s changed though. The update to the APIs is also the result of some internal relaxation of the policies around Documentation and API stability. As Ville explained during the community meeting:

Because we lack the resources, we had to lower the bar a little bit in order to get the APIs in. While the new APIs will have their documentation in [the Developer Docs], you will find out that for most of the new APIS the documentation is quite empty, at least in the beginning.

When I spoke to Ville he elaborated on the reasoning behind this.

The reason is simple: Writing documentation is a lot of work. If we were to write the API documentation at the level you are used to, we could perhaps add one or two APIs in the upcoming release.

What this means in practice is that the level of documentation varies. Some APIs have quite a good level of documentation, while for some others the documentation is just a list of QML types and their properties and methods.

There will also be a slight relaxation around API stability. Here’s Ville again from the community meeting.

Some of the APIs are still not 100% stable, so we can’t really promise that we won’t make API breaking changes to them in the future.

The reasoning here is similar:

It takes a huge amount of work to polish the APIs. Therefore they aren’t currently perfect in many places, and we might want to polish them later on. However, many of these APIs have been in existence for a long time, and even though we know they are not perfect, the likelihood that we will change them in the near future seems low. Therefore it doesn’t make sense to forbid using the APIs just because we might change them some day.

In practice this means that in the future, the APIs might change, and when they do, it’s the responsibility of the app developers to changes their apps accordingly.

Before we wrap up, I’m interested to know whether Ville has any particular apps he’s looking forward to seeing sailing into Harbour for download from the Jolla Store. He deftly dodges my attempt to expose favouritism.

We haven’t been targeting any specific apps, but of course we would like to see as many apps as possible in the Jolla Store. I know there are a few apps which have been disqualified just because they use Sailfish Secrets and Crypto, and I would really like to see those apps make their way to Harbour.

So if you’re a developer of an app that uses one of the new APIs, we urge you to check it against the Harbour allowed QML imports, allowed libraries and allowed requires lists to see whether it will pass the updated validator and can make it into the Jolla Store. Ville has some useful advice for developers looking to do this.

If they want to take these APIs in to use, they are free to do so, and submit their apps to Harbour. One thing to note is that the allowed package dependencies for these new APIs are done using the QML API names, so in practice you need to write “Requires: qml(Sailfish.Contacts)” instead of “Requires: sailfish-components-contacts-qt5” in your spec files.

And can we expect even more new APIs to be delivered in the near future?

I would say that this is only one step on our way to make Harbour more open. A big step maybe, but it’s not the first and won’t be the last. There will always be more APIs to add.

At this time we have been looking mostly at Sailfish UI components. Of course we have been following the feedback from the developers, and that affects our decisions. The API poll which we had a while ago was a good source of insight. We might have another poll someday.

And of course, as Ville points out, “Feedback is always welcome, as are contributions”.

Repository roundup

Besides the good news about newly added APIs to Jolla harbour, one can see in this digest many updates of low-level packages to their latest upstream releases, with a large part of the work coming from mlehtima but also from community members like attah. Besides bringing the possibility to use latest capabilities, it also ensures to get all latest bug corrections from this free software world and keep the platform up to date. I’ll just quote nico from latest community meeting to conclude this introduction : “Sooooo, Sailfish 6 will have Qt6, right?”… :wink:

Homescreen

  • lipstick, the compositor and main user interface of your phone, Tomin1’s pull request about supporting an X-DBusActivatable key in desktop files, has been merged. JacekJagosz’s proposition to allow Discord notifications (from the Discord Android app) has also been merged. pvuorela mentioned that from Sailfish OS release after 4.4 and Android newer than version 4, this kind of modification per application should not be necessary anymore.

Browser stack

Audio / video stack

Document stack

OS low-levels

Documentation

OS build

SDK

Software engineering

App roundup

Thanks to Damien for another thorough and enlightening repo roundup. We’ve seen lots of activity on the app front as well, with the following being just a selection of the recent additions and changes to the Jolla Store.

AIDA64

The first in our roundup is AIDA64 developed by FinalWire Ltd. AIDA64 provides a wealth of information about the hardware, software and status of your phone.

It’s an impressive app for many reasons. It’s excessively cross platform (Sailfish OS, iOS, Android, Ubuntu Touch, Windows Phone, Tizen and Windows are all supported), and it’s been around in one form or another for over 25 years (it’s release to the Jolla Store came in June 2016).

Open the app and you’ll be presented with twelve different categories to choose from, each one allowing you to drill down into the current status of all aspects of your phone, such as the running temperature of various components, the sensor readings, the apps installed and so on. That’s great for casual viewing, but you can also save or email the data out as a report for later inspection. The amount of data available is a bit overwhelming, but fascinating, and depending on your use-case, could also be incredibly useful.

The latest release includes something which we know many people have been waiting for: a 64-bit ARM executable to allow it to run on more recent devices. It also adds some nice new features, including information about the Android Runtime installed, Sailjail support, plus improved support for specific devices including the Mi 2, PinePhone, Xperia XA2 Dual.

Version 2.0.9 is available from the Jolla Store now.

Seabass

Yet another update to Seabass from prolific coder Mikhael Milikhin (milikhin). Seabass is a “small but perfectly formed” text file editor aimed at coders that’s especially strong on syntax colouring. It harnesses a swathe of existing code editing and viewing tools, at its core the Javascript Codemirror text editing framework. But it’s wrapped up with a nicely Sailfishy design, including a nice Read Only viewing mode. It combined both top and bottom menus, but uses a neat trick to avoid them interacting badly while scrolling. It’s a nice design.

The latest version incorporates Mikhael’s own file picker component. This simplifies the user interface, but more importantly it also allows for functionality to create new files, something which hasn’t been possible until this version.

Version 0.10.0 of Seabass is highly recommended and available from both the Jolla Store and OpenRepos.

TimeLapse Tools

TimeLapse Tools from Lukáš Karas (karry) is another app that seems to be enjoying regular updates. The very first release we covered last month. TimeLapse tools is an app of two halves. The first half allows you to capture images over a long period of time. It turns your phone into a timelapse camera, capturing still images at regular intervals over a long period of time. Depending on the time period and subject you want to capture, you might set it to take a photo once every second, once every minute, something like that.

Having captured these images, the second half of the app allows you to assemble your captured images together to form a video. Typically the video will be far shorter than the time period over which the images are captured, resulting in an accelerated replay of the events. It’s great for making slow events tractable for our short human attention spans.

The latest version adds Czech translations, adds an option to stabilise the produced video, changes the video output format for improved interoperability and fixes some bugs. Unfortunately I also experienced a bug which prevented the captured images from being assembled into a video (duly reported).

While the new features are nice, I’d recommend skipping this release if you plan to assemble the videos on your phone. It’s possible to work around the bug by moving files around, but hopefully it can be fixed to avoid this in the next release.

Version 0.2 of TimeLapse tools is available from both the Jolla Store and OpenRepos.

Mah Solitaire

Mah Solitaire had a slew of updates earlier this year, with app author Mark Washeim (poetaster) even managing to get his changes to make it work better with mobile devices and Sailfish OS in particular incorporated upstream. So as an app it’s already quite refined, and the latest update adds Spanish translations to the mix.

Mah Solitaire is a single-player game build around the classic Mahjong tileset, which are initially stacked in a specific layout but in a random order onto the board. The entire set contains four of each tile type and as a player it’s your job to match them in pairs. Each pair matched is removed from the board. Your objective: remove all the tiles.

It’s a simple enough premise, complicated by the fact that tiles must be free of horizontal neighbours and must be at the top of the stack before they can be removed. Some care and strategy is therefore required to remove them in the correct order. A misstep can result in an insoluble arrangement of tiles.

Although the game scores you based on your time, there’s no explicit pressure, so it can be a surprisingly calming way to pass the time. Each play through is different and there are over fifty different board styles to choose from, providing plenty of longevity.

Mah Solitaire is one of my favourite implementations, and definitely worth a try. Version 1.6.1 is available from the Jolla Store, OpenRepos and also Chum.

Please feed us your news

We hope you enjoyed this fortnight’s community news. This is your news, and frankly we can’t always keep up with all the exciting stuff happening in the Sailfish community, so please help us out by replying to this post in the forum if you’d like to see something included.

And do also join us at our community meetings on IRC, Matrix and Telegram. It’s a great place to discuss any of the content you see here, ask questions and share your ideas. The next meeting will be on the 15th September, and will be presided over by special-guest chair abranson, so worth attending for that reason alone!

19 Likes

It would be nice if @rainemak could share his findings in the thread, especially whether or not we can/should set these values back to their defaults after the next update.

2 Likes

Thanks for the nice read and the big step with the APIs! I wonder if we can add pytz to the list as well?! (https://github.com/sailfishos/python3-pytz/pull/1, @vige)

I hope we do not need until SFOS6 as a rough extrapolation leads to (1.0 - 2013, 2.0 . 2015, 3.0 - 2018, 4.0 - 2021 → 2.67 Years between main version releases - > ) Qt6 in 2026/2027. :stuck_out_tongue_winking_eye:

1 Like

Well, I haven’t managed to get that even integrated yet, so perhaps it’s a bit premature to announce it.

3 Likes

Thanks for including my miniscule merge request, too :grin:

It feels great to see new features and changes happening! Thank you all and keep up the good work!

2 Likes

Lot’s of good news. Thanks all for the efforts!

I’ve doing: Requires: python3-imaging (I think since february). is this correct?

Please use Requires: python3dist(pillow) instead. The reason behind this is that it gives us the possibility of changing the package name without breaking things. Like in this case, I can imagine we might at some point want to change the actual package name to python3-pillow.

4 Likes

Thanks! Still just very happy it’s there!