Plasma/Mobile/DevGuide

Plasma Mobile Developer Guide

 

Under Construction
This is a new page, currently under construction!

The development environment needed depends on the specific area of Plasma Mobile you want to contribute. There are three kinds of development environment:

1. General Linux-based development environment
2. Plasma Mobile emulated environment
3. Mobile device running plasma mobile

For most tasks you will not need an actual mobile device running Plasma Mobile. Moreover, although you may contribute to Plasma Mobile using any kind of linux-based development environment , we strongly suggest to use the Plasma Mobile pre compiled image, since such an environment will make the development much easier and facilitate the testing of your work on a machine that emulates a mobile device.

Plasma Mobile emulated environment

Get the Plasma Moible precompiled image

At first, you have to download the precompiled ISO image. TODO: Add link

Run the virtual machine

To use the precompiled ISO, QEMU should be installed. QEMU is a free and open-source hosted hypervisor that performs hardware virtualization. In Ubuntu-based distributions (e.g. KDE neon), just execute:

sudo apt install qemu-utils qemu-system-x86

TODO: Add instructions to run the vm

Mobile device running plasma mobile

Currently, you may run Plasma Mobile on an actual mobile device, either by installing postmarketOS or using Halium as hardware adaption layer.

Using postmarketOS

PostmarketOS is a touch-optimized, pre-configured Alpine Linux-based distribution. Currently, postmarketOS has been ported to many devices. Ensure that your device belongs to the relative list and proceed to installation, following the installation instructions provided by postmarketOS team. When asked during installation, just select “plasma-mobile” as the user interface:

Available user interfaces (5):
* none: No graphical environment
* hildon: (X11) Lightweight GTK+2 UI (optimized for single-touch touchscreens)
* luna: (Wayland) webOS UI, ported from the LuneOS project (Not working yet)
* plasma-mobile: (Wayland) Mobile variant of KDE Plasma, optimized for touchscreen
* weston: (Wayland) Reference compositor (demo, not a phone interface)
* xfce4: (X11) Lightweight GTK+2 desktop (stylus recommended)
User interface [weston]: plasma-mobile

Using Halium

Halium provides the minimal android layer that allows a non-Android graphical environment to interact with the underlying Android kernel and access the hardware. Currently Halium has been ported to many devices. The Plasma Mobile team provides a Neon-based rootfs which can be used along with the Halium builds. This image is based on the dev-unstable branch of KDE Neon, and always ships the latest versions of KDE frameworks, kwin and Plasma Mobile.

To run Plasma Mobile using Halium as hardware adaption layer:

• Ensure that Halium has been ported to your device
• Download the Neon-based rootfs image
• Get the source manifest
• Follow the Halium documention detailed instructions to install Halium

Plasma Mobile application development

Getting involved with Plasma Mobile application environment is a perfect opportunity to familiarize with a set of important technologies:

• Qt, the cross-platform application framework for creating applications that run on various software and hardware platforms with little or no change in the underlying codebase
• QML, the UI specification and programming language that allows designers and developers to create applications with fluid transitions and effects, which are quite popular in mobile devices. QML is a declarative language offering a highly readable, declarative, JSON-like syntax with support for imperative JavaScript expressions.
• Qt Quick, the standard library of types and functionality for QML. It includes, among many others, visual types, interactive types, animations, models and views. A QML application developer can get access to all of that functionality with a single import statement.
• CMake, the cross-platform set of tools designed to build, test and package software, using a compiler-independent method.
• Kirigami, a set of QtQuick components, facilitating the easy creation of applications that look and feel great on mobile as well as on desktop devices, following the Kirigami Human Interface Guidelines.

Documentation resources

Before delving into Plasma Mobile development, you may look into the technical documentation of the technologies involved. You may get started by checking what QML and QtQuick stand for and having a look at the QML Glossary. Getting Started Programming with Qt Quick guide is a very useful resource as well. Afterwards, Kirigami Human Interface Guidelines will introduce you to the design patterns of Plasma Mobile. Finally, you may have a quick look at CMake documentation.

During development, QML Reference, QML types list and Kirigami API will be your friends.

First steps with Plasma Mobile development

Now you are familiar with the technologies related with Plasma Mobile, it's time to create our first Plasma Mobile application. Creating a Plasma Mobile applications based on Kirigami components is quite easy. Following the below steps we will create a simple Kirigami application in a few minutes.

1. Create a new folder in your filesystem:

mkdir hellokirigami

1. Navigate to this folder

project(hellokirigami)

cmake_minimum_required(VERSION 2.8.12)
set(KF5_MIN_VERSION "5.18.0")
set(QT_MIN_VERSION "5.5.0")

################# Disallow in-source build #################

if("${CMAKE_SOURCE_DIR}" STREQUAL "${CMAKE_BINARY_DIR}")
   message(FATAL_ERROR "This application requires an out of source build. Please create a separate build directory.")
endif()


# Make CPack available to easy generate binary packages
include(CPack)
include(FeatureSummary)

################# set KDE specific information #################

find_package(ECM 0.0.8 REQUIRED NO_MODULE)

# where to look first for cmake modules, before ${CMAKE_ROOT}/Modules/ is checked
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR})

include(ECMSetupVersion)
include(ECMGenerateHeaders)
include(KDEInstallDirs)
include(KDECMakeSettings)
include(ECMPoQmTools)
include(KDECompilerSettings NO_POLICY_SCOPE)

set(KF5_VERSION "5.22.0")

find_package(Qt5 ${QT_MIN_VERSION} REQUIRED NO_MODULE COMPONENTS Core Quick Test Gui Svg QuickControls2)

find_package(KF5Kirigami2 ${KF5_DEP_VERSION} "5.22.0")

################# Enable C++11 features for clang and gcc #################

if(UNIX)
   set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -std=c++0x")
endif()

################# now find all used packages #################

set (QT_MIN_VERSION "5.6.0")

find_package(PkgConfig)
#########################################################################

add_subdirectory(src)

install(PROGRAMS org.kde.hellokirigami.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

1. Create a new file named org.kde.hellokirigami.desktop
2. Open org.kde.hellokirigami.desktop
3. Add the below to org.kde.hellokirigami.desktop

[Desktop Entry]
Name=HelloKirigami
Comment=My first Plaasma Mobile App
Version=1.0
Exec=hellokirigami
MimeType=application/x-hellokirigami;
Icon=applications-development
Type=Application
Terminal=false
Categories=Qt;KDE;