Plasma/Mobile/DevGuide: Difference between revisions

From KDE Community Wiki
< Plasma‎ | Mobile
No edit summary
(add Plasma Mobile SDK)
 
(27 intermediate revisions by 4 users not shown)
Line 5: Line 5:
# Plasma Mobile emulated environment
# Plasma Mobile emulated environment
# Mobile device running plasma mobile
# 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.  
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.  
== General Linux-based development environment ==
To cross-compile Plasma Mobile system components (such as KWin) and apps for target architecture (ARM) on your PC, you are welcome to use container environment which acts as a Plasma Mobile SDK, as described here:<br>
https://invent.kde.org/butirsky/plasma-mobile-sdk


== Plasma Mobile emulated environment ==
== Plasma Mobile emulated environment ==


=== Get the Plasma Moible precompiled image ===
=== Get the Plasma Mobile installation image ===
At first, you have to download the precompiled ISO image.  
At first, you have to download the Plasma Mobile [https://plasma-mobile.org/get/#desktop-devices installation image]. This image is using the same packages as the Neon based reference rootfs, just compiled for amd64. We will use it to set up our development virtual machine but you may use it to test Plasma Mobile in a non-android intel tablet as well.
TODO: Add link
 
=== Compile QEMU ===
To proceed to installing, QEMU should be installed. QEMU is a free and open-source hosted hypervisor that performs hardware virtualization. Nevertheless, in many distributions QEMU is not packaged with Virgil 3d support. If your distribution provides such a qemu package you may omit and proceed to just installing QEMU using you distribution's application store.
 
==== Install Virglrenderer ====
Virgil is a project that allows the guest operating system to use the capabilities of the host GPU to accelerate 3D rendering. OpenGL support on the guest system -Plasma Mobile virtual machine- is required for executing Calamares, that will enable us to install Plasma Mobile. We can compile Virgil executing the following commands:
 
{{Input|1=<nowiki>
sudo apt install meson
git clone git://git.freedesktop.org/git/virglrenderer
cd virglrenderer
meson build
cd build
ninja install
</nowiki>}}
 
==== Install build dependencies ====
Depending on your distribution, dependency package names may vary. In KDE Neon, you may install the packages required to compile QEMU executing:


=== 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:
{{Input|1=<nowiki>
{{Input|1=<nowiki>
sudo apt install qemu-utils qemu-system-x86</nowiki>}}
sudo apt install libgtk-3-dev libspice-server-dev libspice-protocol-dev libusbredirparser-dev build-essential libepoxy-dev libdrm-dev libgbm-dev libx11-dev libpulse-dev libsdl2-dev
</nowiki>}}
 
==== Install QEMU  ====
To let our system have access to /usr/local/lib we run:
{{Input|1=<nowiki>
LD_LIBRARY_PATH=/usr/local/lib/x86_64-linux-gnu
export LD_LIBRARY_PATH
</nowiki>}}
 
To compile QEMU with the set of options that fit our needs and then install it we execute:
{{Input|1=<nowiki>
git clone git://git.qemu-project.org/qemu.git
mkdir -p qemu/build
cd qemu/build
../configure --target-list=x86_64-softmmu --enable-gtk --enable-kvm --enable-spice --enable-usb-redir --enable-virglrenderer --enable-opengl
make
sudo make install
</nowiki>}}
 
==== Create Virtual Machine  ====
Now, we need to create the Plasma Mobile virtual machine, running:
{{Input|1=<nowiki>
qemu-img create -f raw plamodisk 40G
/usr/local/bin/qemu-system-x86_64 -boot menu=on -cdrom /path/to/neon-pm-devedition-gitunstable-YYYYMMDD-HHMI-amd64.iso -vga virtio -display gtk,gl=on -m 2G -enable-kvm -boot order=d -drive file=plamodisk,format=raw
</nowiki>}}
Then, we execute Konsole, select a user password and open Calamares running:
{{Input|1=<nowiki>
passwd
sudo -E calamares
</nowiki>}}
 
Follow Calamares instructions to install our system.
 
* Select your language
* Select your time zone
* Select your keyboard
* Choose the default partitioning scheme
* Create the system user
* Validate your options
 
Then, installation process will start.
 
When completed, shutdown your virtual machine.
 
Since installation has been completed, we no longer need the installation image. So, we will start our ready-to-use workstation executing:
{{Input|1=<nowiki>
/usr/local/bin/qemu-system-x86_64 -vga virtio -display gtk,gl=on -m 2G -enable-kvm -boot order=d -drive file=plamodisk,format=raw
</nowiki>}}


TODO: Add instructions to run the vm
== Mobile device running plasma mobile ==
== 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.
Currently, you may run Plasma Mobile on an actual mobile device, either by installing postmarketOS or using Halium as hardware adaption layer.
Line 35: Line 102:
User interface [weston]: plasma-mobile
User interface [weston]: plasma-mobile
</nowiki>}}
</nowiki>}}
=== Using Halium ===
=== Using Halium ===
[https://halium.org/ 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.  
[https://halium.org/ 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.  
Line 48: Line 116:
* 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
* 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.
* 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.
* 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 this 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.  
* 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.
* 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 ==
=== 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 [https://doc.qt.io/qt-5.10/qmlapplications.html QML and QtQuick] stand for and having a look at the [https://doc.qt.io/qt-5.10/qml-glossary.html QML Glossary]. [https://doc.qt.io/qt-5.10/gettingstartedqml.html  Getting Started Programming with Qt Quick guide] is a very useful resource as well. Afterwards, [https://community.kde.org/KDE_Visual_Design_Group/KirigamiHIG Kirigami Human Interface Guidelines] will introduce you to the design patterns of Plasma Mobile. Finally, you may have a quick look at CMake [https://cmake.org/documentation/ documentation].
In this section you will find a set of technical resources that will accompany you during your journey as a Plasma Mobile developer. If you are just starting out with Qt, QML and CMake, you will find here enough detail so as to feel comfortable with the technologies related to Plasma Mobile development. If you are an experienced Qt developer, you can find here valuable resources so as to comply with best practices.  
==== QtQuick and QML ====
* [https://doc.qt.io/qt-5/qmlapplications.html QML Applications]
* [https://doc.qt.io/qt-5/qmlfirststeps.html First Steps with QML]
* [https://doc.qt.io/qt-5/gettingstartedqml.html  Getting Started Programming with Qt Quick]
* [https://doc.qt.io/qt-5/qml-glossary.html QML Glossary]
* [https://doc.qt.io/qt-5/qmlreference.html QML Reference]
* [https://doc.qt.io/qt-5/qmltypes.html QML types list]


During development, [https://doc.qt.io/qt-5.10/qmlreference.html QML Reference], QML types [https://doc.qt.io/qt-5.10/qmltypes.html list] and [https://api.kde.org/frameworks/kirigami/html/index.html Kirigami API] will be your friends.
==== Kirigami ====
* [https://community.kde.org/KDE_Visual_Design_Group/KirigamiHIG Kirigami Human Interface Guidelines]  
* [https://api.kde.org/frameworks/kirigami/html/index.html Kirigami API]
==== CMake ====
* [https://cmake.org/documentation/ CMake Documentation]
* [https://community.kde.org/Guidelines_and_HOWTOs/CMake CMake Guidelines and How-tos]


=== First steps with Plasma Mobile development ===
=== 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.
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 application based on Kirigami components is quite easy.
 
To properly build a plasma mobile application, a set of development packages should be installed. When working on a KDE Neon based development environment, we suggest installing:
{{Output|1=<nowiki>git cmake make extra-cmake-modules g++ qt5-qmake qt5-default qtdeclarative5-dev libqt5svg5-dev qtquickcontrols2-5-dev libkf5config-dev kirigami2-dev qtmultimedia5-dev</nowiki>}}
 
Following the below steps we will create a simple Kirigami application in a few minutes.
* Download [https://community.kde.org/File:Hellokirigami.tar.gz hellokirigami] archive
* Download [https://community.kde.org/File:Hellokirigami.tar.gz hellokirigami] archive
* Unzip the archive
* Unzip the archive
Line 92: Line 177:
hellokirigami
hellokirigami
</nowiki>}}
</nowiki>}}
[[Image:Hellokirigami.png|250px|center]]
If you can see this image:
 
[[Image:Hellokirigami.png|250px]]
 
you have successfully created your first Plasma Mobile application!
 
To display the application like it would be displayed on the phone, use:
{{Input|1=<nowiki>
QT_QUICK_CONTROLS_MOBILE=true QT_QUICK_CONTROLS_STYLE=Plasma hellokirigami
</nowiki>}}

Latest revision as of 13:28, 5 February 2023

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.

General Linux-based development environment

To cross-compile Plasma Mobile system components (such as KWin) and apps for target architecture (ARM) on your PC, you are welcome to use container environment which acts as a Plasma Mobile SDK, as described here:
https://invent.kde.org/butirsky/plasma-mobile-sdk

Plasma Mobile emulated environment

Get the Plasma Mobile installation image

At first, you have to download the Plasma Mobile installation image. This image is using the same packages as the Neon based reference rootfs, just compiled for amd64. We will use it to set up our development virtual machine but you may use it to test Plasma Mobile in a non-android intel tablet as well.

Compile QEMU

To proceed to installing, QEMU should be installed. QEMU is a free and open-source hosted hypervisor that performs hardware virtualization. Nevertheless, in many distributions QEMU is not packaged with Virgil 3d support. If your distribution provides such a qemu package you may omit and proceed to just installing QEMU using you distribution's application store.

Install Virglrenderer

Virgil is a project that allows the guest operating system to use the capabilities of the host GPU to accelerate 3D rendering. OpenGL support on the guest system -Plasma Mobile virtual machine- is required for executing Calamares, that will enable us to install Plasma Mobile. We can compile Virgil executing the following commands:

sudo apt install meson
git clone git://git.freedesktop.org/git/virglrenderer
cd virglrenderer
meson build
cd build
ninja install

Install build dependencies

Depending on your distribution, dependency package names may vary. In KDE Neon, you may install the packages required to compile QEMU executing:

sudo apt install libgtk-3-dev libspice-server-dev libspice-protocol-dev libusbredirparser-dev build-essential libepoxy-dev libdrm-dev libgbm-dev libx11-dev libpulse-dev libsdl2-dev

Install QEMU

To let our system have access to /usr/local/lib we run:

LD_LIBRARY_PATH=/usr/local/lib/x86_64-linux-gnu
export LD_LIBRARY_PATH

To compile QEMU with the set of options that fit our needs and then install it we execute:

git clone git://git.qemu-project.org/qemu.git
mkdir -p qemu/build
cd qemu/build
../configure --target-list=x86_64-softmmu --enable-gtk --enable-kvm --enable-spice --enable-usb-redir --enable-virglrenderer --enable-opengl
make
sudo make install

Create Virtual Machine

Now, we need to create the Plasma Mobile virtual machine, running:

qemu-img create -f raw plamodisk 40G
/usr/local/bin/qemu-system-x86_64 -boot menu=on -cdrom /path/to/neon-pm-devedition-gitunstable-YYYYMMDD-HHMI-amd64.iso -vga virtio -display gtk,gl=on -m 2G -enable-kvm -boot order=d -drive file=plamodisk,format=raw

Then, we execute Konsole, select a user password and open Calamares running:

passwd
sudo -E calamares

Follow Calamares instructions to install our system.

  • Select your language
  • Select your time zone
  • Select your keyboard
  • Choose the default partitioning scheme
  • Create the system user
  • Validate your options

Then, installation process will start.

When completed, shutdown your virtual machine.

Since installation has been completed, we no longer need the installation image. So, we will start our ready-to-use workstation executing:

 /usr/local/bin/qemu-system-x86_64 -vga virtio -display gtk,gl=on -m 2G -enable-kvm -boot order=d -drive file=plamodisk,format=raw

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:

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 this 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

In this section you will find a set of technical resources that will accompany you during your journey as a Plasma Mobile developer. If you are just starting out with Qt, QML and CMake, you will find here enough detail so as to feel comfortable with the technologies related to Plasma Mobile development. If you are an experienced Qt developer, you can find here valuable resources so as to comply with best practices.

QtQuick and QML

Kirigami

CMake

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 application based on Kirigami components is quite easy.

To properly build a plasma mobile application, a set of development packages should be installed. When working on a KDE Neon based development environment, we suggest installing:

git cmake make extra-cmake-modules g++ qt5-qmake qt5-default qtdeclarative5-dev libqt5svg5-dev qtquickcontrols2-5-dev libkf5config-dev kirigami2-dev qtmultimedia5-dev

Following the below steps we will create a simple Kirigami application in a few minutes.

  • Download hellokirigami archive
  • Unzip the archive
  • Open src/contents/ui/main.qml
  • Change text:
text:  qsTr("Hello Kirigami")

to

text:  qsTr("Hello Kirigami World")
  • Using Konsole, navigate to hellokirigami folder:
cd hellokirigami
  • Create build folder:
mkdir build
  • Navigate to build folder:
cd build
  • Build and install, executing the below commands:
cmake -DKDE_INSTALL_USE_QT_SYS_PATHS=ON ..
make
sudo make install 
  • Run the application, typing:
hellokirigami

If you can see this image:

you have successfully created your first Plasma Mobile application!

To display the application like it would be displayed on the phone, use:

QT_QUICK_CONTROLS_MOBILE=true QT_QUICK_CONTROLS_STYLE=Plasma hellokirigami