Quickstart: Python + Ubuntu Touch apps

A guide by a noob for noobs RSS

Disclaimer

This Quickstart guide is written by a noob for noobs. It describes my personal way of starting with development which might not be perfect. Consider contacting me if you find big mistakes.

What you need:

Stucture:

  1. Preparation
    1. Installing Qt/Qml
    2. Installing Atom
    3. Installing Clickable
    4. Setting up a project
  2. Resources
  3. Creating our app
    1. Helloworld Python
    2. Helloworld Qml
    3. Turn it into an app
    4. More examples
  4. Publishing our app
  5. What now?

Preparation:

I will quickly show you how to setup your system properly to start development. I will use Ubuntu 20.04 anything based on this should work with the same commands. The procedure should be similar on other distros.

Installing Qt/Qml:

Follow the steps below to install qt/qml and dependencies.

Clean up and update:


sudo apt-get autoremove && sudo apt update && sudo apt upgrade

Install Qt5:


sudo apt-get install qt5-default

Installing modules and dependencies:


sudo apt-get install qtchooser
sudo apt-get install qmlscene
sudo apt-get install qml-module-io-thp-pyotherside
sudo apt-get install qml-module-qtquick-controls
sudo apt-get install qml-module-qt-labs-settings

You can now run qmlscene yourfile.qml to test if the installation was succesful

        
  import QtQuick 2.0

  Rectangle {
      id: page
      width: 320; height: 480
      color: "lightgray"

      Text {
          id: helloText
          text: "Hello world!"
          y: 30
          anchors.horizontalCenter: page.horizontalCenter
          font.pointSize: 24; font.bold: true
      }
  }
        
      

If that throws an error you can try to specify the Qt version you want to use by running the following commands.


qtchooser -list-versions

This will return a list of the Qt versions you have installed. Copy the correct one and run the next command.


qmlscene -qt=TheQtVersion yourfile.qml

Installing Atom

In this guide we will use Atom as Code Editor in combination with a few plugins to simplify development. Alternativly you can use the Ubuntu sdk, which is no longer maintained. For further Information you should take a look at the docs here.


We will start with Installing Atom through Apt. You can also use snap but I do not reccomend this.

Update and Install dependencies:


sudo apt update
sudo apt install software-properties-common apt-transport-https wget

Import the repo GPG key and enable the Apt repository:


wget -q https://packagecloud.io/AtomEditor/atom/gpgkey -O- | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://packagecloud.io/AtomEditor/atom/any/ any main"

Install the latest version of Atom


sudo apt install atom

Now that Atom is installed we can still dowload plugins to make development more convenieant. The first plugin you should install is the atom-clickable-plugin. You might also want to install QML language support in Atom. There are many other great plugins for Atom you can install depending on your needs.

Installing Clickable

UBPorts apps are delivered as clickables/Click packages. We will need Clickable to create our projects and compile them. The tool is fairly easy to use and very usefull.

Add the PPA:


sudo add-apt-repository ppa:bhdouglass/clickable

Update:


sudo apt-get update

Install:


sudo apt-get install clickable

Setup:


clickable setup

It may ask you for your sudo Password.

Setting up a project

Setting up a project is very easy with clickable.First cd into the directory of your choice and run clickable create. This will guide you through the process of creating a project and will also create the folder structure needed.

Resources

Here are some resources that might help you if you have any problems. These are not neccesaraly essential to start development but will be a usefull information source further into development.

  • Resources
    1. UBPorts docs here
    2. UT api here
    3. UBPorts forum here
    4. Qt docs here
  • Creating our app

    Helloworld Python

    I created a very basic python function that returns Hello and the given Name.

            
              def speak(name):
                  return "Hello " + str.format(name)
            
          

    Make sure there is nothing outside the functions other than import statements, as this may cause Errors.

    Helloworld Qml

    Now we finally get to the exciting part. We use PyOtherSide to load our python module. Afterwards we call our function in the moment the MouseArea is released. Please make sure to read the comments (//this is a comment) next to the code and try to understand it.

            
      import io.thp.pyotherside 1.3
      import QtQuick 2.9
      import QtQuick.Layouts 1.3
      import Qt.labs.settings 1.0
      import QtQuick.Controls 1.0
    
      Rectangle {
        Python {
          id: py //The Id you will use to call a function.
          Component.onCompleted: {
            // Print version of plugin and Python interpreter
            console.log('PyOtherSide version: ' + pluginVersion());
            console.log('Python version: ' + pythonVersion());
    
            addImportPath(Qt.resolvedUrl('//PathToFolder')); //The path to your python files
            importModule('example', function() {}); //Importing example.py
            console.log('after importModule');
          }
        }
        height: 200
        width: 200
        Text{
          id: helloText
          anchors.centerIn: parent
        }
        Rectangle{
          anchors.horizontalCenter: parent.horizontalCenter
          anchors.bottom: parent.bottom
          anchors.bottomMargin: 20
    
          width: 100
          height: 30
          color: "red"
          radius: 10
    
          Text{
            anchors.centerIn: parent
            text: "click me!"
          }
    
          MouseArea {
            anchors.fill: parent
    
            onReleased: {
              py.call('example.speak', ["Aaron"], function(result) { //Calling the function function "speak" with argument -->                                                      //"Aaron" and returning "results"
                  helloText.text = result //Hello.text is no longer a property.
                  console.log("after call of speak")
              })
            }
          }
        }
      }
    
            
          

    Notice that I included Python inside of our root Rectangle and did not seperate it, because that would cause a syntax error. You should tinker arround with the code and try what is possible. Try calling your own functions before continuing. You can run this code using qmlscene.

    Turn it into an app

    Before Installing our app on the phone we should try it one more time with clickable desktop. If everything works you can connect your phone via adb or ssh and run clickable or clickable --ssh yourIp.This will install the app on your phone and store a click pakage in the build directory of your project. If you run into an error you can try clickable logs to view the logs. You will need to add the --ssh argument if you use ssh or you can use the CLICKABLE_SSH env var.

    More examples

    The best way to learn more about development for UBPorts is to take a look at real code. You can for example take a look at the openstore. You will find a link to the sourcecode of many apps there.

    The user pavelprosto also created some python specific examples worth taking a look at here.

    Publishing our app

    Config files

    Do you remember the configuration you had to enter when you created your project? You might want to change it later or specify your app version.

    The three config files:

    The last file is the most important one for us. It looks like this:

            
      {
          "name": "examplename.aarontheissueguy",
          "description": "This is a description",
          "architecture": "@CLICK_ARCH@",
          "title": "ExampleTitle",
          "hooks": {
              "examplename": {
                  "apparmor": "examplename.apparmor",
                  "desktop":  "examplename.desktop"
              }
          },
          "version": "1.0.0",
          "maintainer": "Firstname Lastname ",
          "framework" : "@CLICK_FRAMEWORK@"
      }
            
          

    The file is pretty much self explanatory but you can find further information on those config files here.

    Openstore

    "The OpenStore is the official app store for Ubuntu Touch. It is an open source project run by a team of volunteers with help from the community. You can discover and install new apps on your Ubuntu Touch device. You can also upload and manage your own apps for publication. The OpenStore encourages the apps published within to be open source, but also accepts proprietary apps." about

    I hope this helped

    Thanks for reading this guide. If you liked it consider subscribing to my RSS-feed or Mastadon account.

    If you find any faults please contact me.

    Pls feel free to copy parts of this article or the entire text. Atribution is welcome but not required.