Sunday, 19 May 2013

Deploying Import Packages to Sailfish and Harmattan Devices the Hard Way


Note: This post will be updated for the Qt5 Alpha shortly!

In one of my recent posts I described how to create an import library / package that abstracted out imports of Harmattan and Sailfish Silica components from our core projects.

Towards the end I wrote something like "now deploy to your device" but did not say how as the article was already lengthy in danger of being long winded. Instead I snuck off and did some thing more satisfying like pouring a glass of ale.

So here is a separate article detailing how to install my abstract import package to a variety of Sailfish and Harmattan "devices".

a) The SailfishOS SDK
b) The SailfishOS Emulator
c) The Harmatttan Simulator
d) A real Harmattan Device (e.g. N9)
e) The Harmattan QEMU Emulator (will be added later)

To each of these we will add the library org.flyingsheep.abstracui, including all the .qml and library files  to the respective  "imports" directory.

Note: this article describes how to install packages manually: i.e the hard way.  While it should be possible to do this more elegantly for instance by using the "Deploy to Device" option in QtCreator, there are 2 reasons for doing it manually:
1) general nosiness and a desire to understand what is happening under the hood,
2) The "deploy to device" seems to not be properly working yet for Sailfish, as discussed in this Sailfish Developers' Mailing list thread.
I am using an OSX host for this article, so if you are using Windows or Linux, just change the host paths accordingly.

For some of the devices we will create symbolic links (symlinks): I have found this article showing how the equivalent can be achieved on Windows hosts: 

How to deploy an import package to the Sailfish SDK

Here the easy answer is don't!: Instead we will cheat!

My working copy of the qmls and plugins (i.e. where Qt Creator accesses them) is:
/Users/<your home dir>/SailfishProjects/abstractui/org/flyingsheep/abstractui

A proper installation on the SDK would result in:
/Users/<your home dir>/SailfishOS/mersdk/targets/SailfishOS-i486-x86/usr/lib/qt4/imports/org/flyingsheep/abstractui

But we don't want the hassle of replicating the files to the SDK every time we make a change. So let's cheat with a symlink pointing from the imports directory to the working copy. We will actually only have one copy of the files (in the working copy dir), but the operating system will "see" two directories.

We create the symlink as follows:

cd /Users/<your home dir>/SailfishOS/mersdk/targets/SailfishOS-i486-x86/usr/lib/qt4/imports

ln -s /Users/<your home dir>//SailfishProjects/abstractui/org org

Now every time we change a file in the working copy, this change will be available to the SDK without me having to do anything!

How to deploy an import package to the SailfishOS Emulator

Before we start copying, first let's connect to the device, and check what's in the imports directory /usr/lib/qt4/imports:

ssh -p 2223  -i ~/.ssh/mer-qt-creator-rsa  root@localhost

cd /usr/lib/qt4/imports

ls -l

Sailfish Emulator already has an org directory in the imports directory, so we will copy from level flying sheep (and not org)
As we can connect with the user root, we can copy direct to the right place in one step (whereas in Harmattan we have to take a multistep process)

cd /Users/<your home dir>/SailfishProjects/abstractui/org

scp -r -P 2223  -i ~/.ssh/mer-qt-creator-rsa flyingsheep root@localhost:/usr/lib/qt4/imports/org/

You should next check the file permissions: My QtCreator is hosted on OSX, and the files created have permissions that are too restrictive

So we connect to the Emulator

ssh -p 2223  -i ~/.ssh/mer-qt-creator-rsa  root@localhost

Change to the directory containing our qml and library files

Run the following 3 chmod commands:

chmod 755 *.so
chmod 644 *.qml
chmod 644 qmldir

If your host is OSX, then it will almost certainly have polluted our library with a hidden .DS_Store file in each subdirectory.
You can see these with ls -l -a
To remove these files, navigate through each subdirectory and do a rm .DS_Store

The unix command rsync has an exclude option, and can be used to deploy files as covered in this post

How to deploy an Import Package to Harmattan Simulator

One difference between the Harmattan Simulator and other devices is that the library files are binary compatible with the host rather than with a real Harmattan device. In my case this is OSX, which means that the correct library is called libabstractui.dylib instead of This can be found in /Users/<your home dir>/QTProjects/abstractui/abstractui-build-Qt_Simulator_N9-Release/

Once we have a copy of this in the working directory, we can take the same sneaky approach we took with the Sailfish SDK above: We will create an equivalent symlink:

First have a quick peak to see what is lurking in /Users/<your home dir>/QtSDK/Simulator/Qt/gcc/imports/

If all is well we can create the symlink as follows:

cd /Users/<your home dir>/QtSDK/Simulator/Qt/gcc/imports

ln -s /Users/<your home dir>QTProjects/abstractui/org org

This should result in Users/<your home dir>/QtSDK/Simulator/Qt/gcc/imports/org/flyingsheep/abstractui/

How to deploy an import package to a N9 Harmattan device

Before we start copying, first let's connect to the device, and check what's in the imports directory /usr/lib/qt4/imports:

ssh developer@

enter the developer password. You will this in the "SDK Connectivity" app.

cd /usr/lib/qt4/imports

ls -l

In my case there was no "org" sub directory, so I can copy the package at the "org" level.

Unfortunately we need to take a multi-step approach as root level access is not allowed for ssh/scp (unless you do some hacking). So we will copy our package as developer to the root directory, then login and move to the right place.

Back on your host, navigate to the folder containing the N9 Harmatttan version of the org.flyingsheep.abstractui package.

cd /Users/<your home dir>//QTProjects/abstractui
Secure copy the directory abstract including contents with user developer:

scp -r org developer@

Connect as developer in order to create directories, and move files to proper place
ssh developer@

This should connect you n the directory /home/developer. Here you should now find a subdirectory "org"

Now we need to set the unix file permissions properly

cd /home/developer/org/flyingsheep/abstractui/

chmod 644 *.qml

chmod 644 qmldir

ls -l

gives me:

total 612
-rw-r--r--    1 user     develope        58 May 19 10:38 AUIButton.qml
-rw-r--r--    1 user     develope        64 May 19 10:38 AUIButtonColumn.qml
-rw-r--r--    1 user     develope        61 May 19 10:38 AUIButtonRow.qml
…more .qml files ….
-rwxr-xr-x    1 user     develope    433033 May 19 10:38
-rw----r--    1 user     develope       696 May 19 10:38 qmldir
Now we need root level access
password rootme

cd /usr/lib/qt4/imports

3) copy the abstractui directory to the imports directory

cp -r /home/developer/org/ /usr/lib/qt4/imports/org/

How to deploy an import package to a N9 QEMU Emulator

Coming soon ...


By now you should have deployed your package manually to a variety of Sailfish and Harmattan "devices".

Your next step will be to install and test apps depending on your package.  Have fun doing this!

No comments:

Post a Comment