KDEConnect: Difference between revisions

From KDE Community Wiki
No edit summary
Line 29: Line 29:
Please see the '''KDE Connect''' [https://userbase.kde.org/KDEConnect Userbase page] for detailed information on the different ways '''KDE Connect''' can be installed and used.
Please see the '''KDE Connect''' [https://userbase.kde.org/KDEConnect Userbase page] for detailed information on the different ways '''KDE Connect''' can be installed and used.


== Building KDE Connect ==
== Building KDE Connect from source ==
 
KDE Connect is a free/ libre open source software, being developed for over 8 years now.
If you want to build KDE Connect yourself, you'll first need to grab the code from git.
<syntaxhighlight lang="bash">
git clone https://invent.kde.org/network/kdeconnect-kde.git
</syntaxhighlight>
 
Note: if you plan to contribute code to '''KDE Connect''', please follow the steps in [[KDEConnect#Setting_up_KDE_Connect_Repository_for_Development]]


=== Linux Desktop ===
=== Linux Desktop ===


'''KDE Connect''' can be built using kdesrc-build to provide a pain-free way to set up the dev environment. See [https://community.kde.org/KDEConnect/Build_Linux here] for instructions. Alternatively, follow the guide below to manually build KDE Connect.
'''KDE Connect''' can be built directly from source using CMake and system-installed dependencies.  


KDE Connect uses cmake as a build system, which will tell you if you are missing any dependencies. On some distros you will need to install some development packages. Sometimes you will need to get the dependencies by yourself because the development branch of KDE Connect often uses new libraries not included in distro repositories, in which case you can build those yourself or use kdesrc-build. Helpfully, some package managers have a command which will automatically fetch the dependencies for you:
Alternatively, you may use a meta-build system like [https://kdesrc-build.kde.org/ kdesrc-build] or [https://community.kde.org/Craft/ Craft],  
both of which have the added benefit of leaving your linux installation unaffected and containing the dev files to a single directory.


<b> For Ubuntu </b>
==== Using a meta-build system ====


you can go in to <code>/etc/apt/source.list</code> and
# Craft is a cross-platform meta-build system that works well on Windows and Linux for KDE Connect devel.
enable the source repositories to install all build-dependencies.
See [https://community.kde.org/KDEConnect/Build_Craft here] for build instructions.
# kdesrc-build is a meta-build system that is used by many long-term KDE developers as their daily driver for KDE devel on Linux.
See [https://community.kde.org/KDEConnect/Build_kdesrc-build here] for build instructions.


<syntaxhighlight lang="bash">
==== Without a meta-build system ====
# apt update
# apt-get build-dep kdeconnect
</syntaxhighlight>


<b> For openSUSE </b>
KDE Connect uses CMake as its build system, which will tell you if you are missing any dependencies.
See [https://community.kde.org/KDEConnect/Build_Linux here] for build instructions.


you can use
=== Windows ===
 
<syntaxhighlight lang="bash">
# zypper si -d kdeconnect-kde
</syntaxhighlight>
 
<b> For Arch Linux </b>
 
Run the following command
 
<syntaxhighlight lang="bash">
# pacman -S kdeconnect
</syntaxhighlight>
 
<b> For Gentoo </b>
 
Run the following command


<syntaxhighlight lang="bash">
KDE Connect is officially supported on Windows.  
# emerge --ask kdeconnect
See [https://community.kde.org/KDEConnect/Build_Windows here] for build instructions.
</syntaxhighlight>
 
On Gentoo, you may need to enable pulseaudio and bluetooth USE flags for respective features.
 
<b> For Fedora </b>
 
Run the following command
 
<syntaxhighlight lang="bash">
# dnf builddep kde-connect
# dnf install qt5-qtquickcontrols2-devel
</syntaxhighlight>
 
 
Be sure to uninstall the package-provided version of kdeconnect before continuing, otherwise, you will end up in a confusing situation where some plugins are being provided by the system-installed version and others are coming from your new build.
 
==== Installing using prefix.sh ====
 
For development, it is recommended to install to your home directory using prefix.sh. This gives a faster development cycle and avoids clobbering your system-installed version with a potentially unstable WIP version.
 
These steps are roughly the same for any KDE project:
 
To configure use
<syntaxhighlight lang="bash">
cd kdeconnect-kde
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=~/kde-prefix ..
</syntaxhighlight>
 
To build use
<syntaxhighlight lang="bash">
make -j8 install
</syntaxhighlight>
 
To run the daemon, do
<syntaxhighlight lang="bash">
source build/prefix.sh
killall kdeconnectd; ~/kde-prefix/lib64/libexec/kdeconnectd
</syntaxhighlight>
 
Other executables, such as the SMS app or the settings app, are on the path provided by prefix.sh, and can be found in <code>~/kde-prefix/bin</code>
 
==== Installing to the System ====
 
If you want to use the new version of '''KDE Connect''' daily, you can install it to the system. This is not recommended for day-to-day development since it requires <code>sudo</code> access.
 
To configure use
<syntaxhighlight lang="bash">
cd kdeconnect-kde
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
</syntaxhighlight>
To build use
<syntaxhighlight lang="bash">
make
sudo make install
</syntaxhighlight>
Note that this will override the '''KDE Connect''' provided by your distro
 
If you intend to develop '''KDE Connect''' or experience a crash and are asked to give a backtrace, build '''KDE Connect''' with debugging symbols:
<syntaxhighlight lang="bash">
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug ..
</syntaxhighlight>
 
If you install '''KDE Connect''' in a custom location, you'll need to run <code>kdeconnectd</code> manually, since DBus doesn't know about it.
 
For instructions on how to integrate the build with '''KDevelop''', check out this [https://nicolasfella.wordpress.com/2018/03/30/building-kde-connect/ blog post].


=== Android ===
=== Android ===


You can find the code on [https://invent.kde.org/network/kdeconnect-android Invent]. It's easiest to use '''Android Studio''' to build the app and install it to your phone, although it can be done on the command line using gradle.
The most convenient dev-flow way is to pass the [https://invent.kde.org/network/kdeconnect-android project URL] to '''Android Studio''', build the app and install it to your phone.
 
Remember to uninstall any already-installed KDE Connect app from your target Android device.
Running '''KDE Connect''' in the emulator is possible, but needs an advanced networking setup. See the guide posted for the [[/Android_Emulator/]]
You can also build the android app through CLI using gradle.
 
=== Windows ===
 
'''KDE Connect''' works quite well on Windows, with many features ported.
See [https://community.kde.org/KDEConnect/Build_Windows here] for build instructions


Refer to the [https://binary-factory.kde.org/job/kdeconnect-kde_Release_win64/ binary factory] for latest build.
You can also run the app in an emulated Android device for devel. See [/Android_Emulator/ here] for instructions.


=== MacOS ===
=== MacOS ===
Line 165: Line 70:
You can get the Nightly Build from the [https://binary-factory.kde.org/view/MacOS/job/kdeconnect-kde_Nightly_macos/ Binary Factory].
You can get the Nightly Build from the [https://binary-factory.kde.org/view/MacOS/job/kdeconnect-kde_Nightly_macos/ Binary Factory].


=== Plasmoid Development ===
 
=== Special Mentions ===
Special instructions for specfic topics.
 
==== Plasmoid Development ====


You can use <code>plasmawindowed</code> to easily run the Plasmoid (even on non-KDE environments).
You can use <code>plasmawindowed</code> to easily run the Plasmoid (even on non-KDE environments).


Set up your development environment as above, then run <code>make install</code>, then run <code>plasmawindowed org.kde.kdeconnect</code> to launch the Plasmoid and see your new changes.
Set up your dev environment as above, then run <code>make install</code>, then run <code>plasmawindowed org.kde.kdeconnect</code> to launch the Plasmoid and see your changes.


=== Mobile-Friendly QML App ===
==== Mobile-Friendly QML App ====


The kdeconnect-app component of the desktop version is suitable for mobile Linux environments, too.
The kdeconnect-app component of the desktop version is suitable for mobile Linux environments, too.


=== Desktop SMS Messaging App ===
==== Desktop SMS Messaging App ====


'''KDE Connect''' has an SMS messaging app which lets you type and view SMS messages from your computer. It supports basic features and works correctly most of the time. If you are interested in trying or developing it, you can build it from source. It is automatically built as part of the rest of '''KDE Connect''' and is output as 'kdeconnect-sms'.
'''KDE Connect''' has an SMS messaging app which lets you type and view SMS messages from your computer.  
It supports basic features and works correctly most of the time.  
If you are interested in trying or developing it, you can build it from source.  
It is automatically built as part of the rest of '''KDE Connect''' and is output as 'kdeconnect-sms'.


== Development ==
== Development ==
Line 223: Line 135:
</syntaxhighlight>
</syntaxhighlight>
# Now whenever there are new changes upstream, simply pull the upstream-master branch, then merge or rebase your local branches onto those changes!
# Now whenever there are new changes upstream, simply pull the upstream-master branch, then merge or rebase your local branches onto those changes!
==== Set up Code - OSS (or Visual Studio Code) as IDE ====
CAUTION: This guide expects that you can successfully build the source code and test any changes to it.
<br>
Developing KDE Connect with VSCode is quite simple but can be tricky for new contributors. To use the debugging capabilities of VSCode, we will create a .code-workspace file and update it according to our own use case.
Create a file <code>kde.code-workspace</code> and copy the contents below to it:
<syntaxhighlight lang="JSON">
{
"folders": [
{
"name": "kdeconnect-kde",
"path": "FIX_ME-1"
}
],
"launch": {
"configurations": [
{
"name": "KDE C Daemon",
"type": "cppvsdbg",
"request": "launch",
"program": "FIX_ME-2",
"args": [],
"cwd": "${fileWorkspaceFolder}",
"stopAtEntry": false,
"preLaunchTask": "Build",
"console": "internalConsole",
"internalConsoleOptions": "openOnSessionStart",
"sourceFileMap": {
"FIX_ME-3": "FIX_ME-4"
}
}
],
"compounds": []
},
"tasks": {
"tasks": [
{
"label": "Build",
"type": "shell",
"command": "FIX_ME-5",
"args": [],
"runOptions": {
"reevaluateOnRerun": true
},
"dependsOn": "Cleanup"
},
{
"label": "Cleanup",
"type": "shell",
"command": "FIX_ME-6",
"args": [],
"runOptions": {
"reevaluateOnRerun": true
}
}
]
},
"settings": {
"[cpp]": {
"editor.wordBasedSuggestions": false,
"editor.suggest.insertMode": "replace",
"editor.semanticHighlighting.enabled": true,
"editor.quickSuggestions": true
},
"C_Cpp.default.includePath": [
"FIX_ME-7"
],
"C_Cpp.default.defines": [
"FIX_ME-8"
],
"files.associations": {
"qdebug": "cpp",
"qstandardpaths": "cpp",
"qicon": "cpp",
"qfile": "cpp"
}
}
}
</syntaxhighlight>
Now, update the following strings according to your dev env:
# "FIX_ME-1"    - "path/to/kdeconnect-kde/repository"
# "FIX_ME-2"    - "path/to/built/bin/kdeconnectd"
# "FIX_ME-3"    - "source/path/picked_up/incorrectly/by/the/debugger"
# "FIX_ME-4"    - "alternate/path/to/pick_up"
# "FIX_ME-5"    - "command_to_build_your_project"
# "FIX_ME-6"    - "cleanup_any_files_or_running_processes_before_Build"
# "FIX_ME-7"    - "additional/paths/to/files/to_include/by/IDE"
# "FIX_ME-8"    - "ANY_DEFINES_SPECIFIC_TO_YOUR_BUILD_ENV"
Example workspace files :
<br/>
# [https://gist.github.com/tm9k1/2312937dbdda73b366d02829078540af Windows dev] (uses [https://community.kde.org/craft Craft])
# [https://gist.github.com/tm9k1/6267b5013e4415a3bd02a026bb0c6393 Linux dev] (uses [https://community.kde.org/craft Craft])
More info at: https://code.visualstudio.com/docs/editor/workspaces


===Development tips===
===Development tips===

Revision as of 02:59, 20 July 2021

This is the community page for KDE Connect. Feel free to edit it! It should contain useful and up-to-date resources for both users and developers.

What is KDE Connect?

KDE Connect is a project that enables all your devices to communicate with each other. Here are a few things KDE Connect can do:

  • Receive your phone notifications on your desktop computer and reply to messages
  • Control music playing on your desktop from your phone
  • Use your phone as a remote control for your desktop
  • Run predefined commands on your PC from connected devices. See the list of example commands for more details.
  • Check your phones battery level from the desktop
  • Ring your phone to help finding it
  • Share files and links between devices
  • Browse your phone from the desktop
  • Control the desktop's volume from the phone


To achieve this, KDE Connect:

  • implements a secure communication protocol over the network, and allows any developer to create plugins on top of it.
  • Has a component that you install on your desktop.
  • Has a KDE Connect client app you run on your phone.


This video from 2013 demonstrates some other cool features: https://www.youtube.com/watch?v=KkCFngNmsh0

More info at Albert Vaka's or Nico's blog.

Installation and Usage

Please see the KDE Connect Userbase page for detailed information on the different ways KDE Connect can be installed and used.

Building KDE Connect from source

KDE Connect is a free/ libre open source software, being developed for over 8 years now.

Linux Desktop

KDE Connect can be built directly from source using CMake and system-installed dependencies.

Alternatively, you may use a meta-build system like kdesrc-build or Craft, both of which have the added benefit of leaving your linux installation unaffected and containing the dev files to a single directory.

Using a meta-build system

  1. Craft is a cross-platform meta-build system that works well on Windows and Linux for KDE Connect devel.

See here for build instructions.

  1. kdesrc-build is a meta-build system that is used by many long-term KDE developers as their daily driver for KDE devel on Linux.

See here for build instructions.

Without a meta-build system

KDE Connect uses CMake as its build system, which will tell you if you are missing any dependencies. See here for build instructions.

Windows

KDE Connect is officially supported on Windows. See here for build instructions.

Android

The most convenient dev-flow way is to pass the project URL to Android Studio, build the app and install it to your phone. Remember to uninstall any already-installed KDE Connect app from your target Android device. You can also build the android app through CLI using gradle.

You can also run the app in an emulated Android device for devel. See [/Android_Emulator/ here] for instructions.

MacOS

KDE Connect works fairly well on macOS, however there is no official version as of yet. See here for build instructions.

You can get the Nightly Build from the Binary Factory.


Special Mentions

Special instructions for specfic topics.

Plasmoid Development

You can use plasmawindowed to easily run the Plasmoid (even on non-KDE environments).

Set up your dev environment as above, then run make install, then run plasmawindowed org.kde.kdeconnect to launch the Plasmoid and see your changes.

Mobile-Friendly QML App

The kdeconnect-app component of the desktop version is suitable for mobile Linux environments, too.

Desktop SMS Messaging App

KDE Connect has an SMS messaging app which lets you type and view SMS messages from your computer. It supports basic features and works correctly most of the time. If you are interested in trying or developing it, you can build it from source. It is automatically built as part of the rest of KDE Connect and is output as 'kdeconnect-sms'.

Development

KDE Connect is a perfect project to start contributing to KDE. You'll need a basic understanding of programming concepts, the rest can be learned by doing. Experience with Android or Qt is beneficial, but not needed.

We have a group to discuss development. You can access it from Telegram, IRC (#kdeconnect) or matrix.org (#freenode_#kdeconnect:matrix.org). Feel free to ask any development-related questions there. We also have a mailing list.

All patches are submitted on Gitlab. The Android repository is here and the C++ Desktop repository is here. Be sure to select the most relevant template. You don't need to assign any reviewers, the developers are subscribed to notifications. Should this be your first patch, it's good to know that it might take some time before your patch is reviewed (we all work on KDE Connect in our free time), and you'll probably have to make some changes a couple of times. That's not because you're new, that's what happens for all reviews (even for long-time contributors).

There are a couple of tasks marked as Junior Jobs on our workboard. Those have some extra information on how to approach them that help you get started.

Setting up KDE Connect Repository for Development

KDE Connect is actually composed of two repositories; one for the Android implementation and one for the C++ (Desktop) implementation. You can have a local clone of both on your computer and the steps to set them up are the same. For these directions, I will use the C++ repository, but if you want the Android repository, just replace every instance of 'kdeconnect-kde' with 'kdeconnect-android'

  1. Fork the repository
    • With your web browser, open the Web GUI to KDE Connect's GitLab: https://invent.kde.org/network/kdeconnect-kde
    • If you are not already, sign in with your KDE identity by clicking the "Sign In" button in the top left
    • Click the "Fork" button, near the top right
    • Wait for the forking to complete
  2. Clone your fork
    • Open your new fork in the GitLab web GUI
    • Click the "Clone" button in the top right
    • Select the method of cloning
      • I recommend SSH. This will require you add an SSH public key to your KDE GitLab account.
      • An HTTPS clone will require you to log in with your KDE Identity credentials to push changes.
    • In the folder you want to clone, do 'git clone <cloning path from above>'

You are all set up! See the optional steps for ways to make life easier.

Set up second remote (Optional)

Having a second remote allows you to have your local 'master' branch track the upstream kdeconnect-kde master branch, so you can easily get all the latest changes.

These steps assume you are using command-line git. If you are using a GUI tool, the steps will be different, but the ideas will be the same.

  1. On the command line, change to your local repository clone
  2. Execute:
# Note that we use HTTPS cloning here so that you don't need a verified account to pull changes!
git remote add upstream https://invent.kde.org/network/kdeconnect-kde.git
git fetch upstream
git checkout -b upstream-master --track upstream/master
  1. Now whenever there are new changes upstream, simply pull the upstream-master branch, then merge or rebase your local branches onto those changes!

Development tips

Restarting the daemon

Whenever you do a change to KDE Connect you need to restart the daemon for the change to take effect. 

killall kdeconnectd
build/bin/kdeconnectd

DBus inspection

The daemon communicates with various UI components (Plasmoid, CLI, Indicator etc.) over DBus. QDbusViewer allows inspecting the DBus interface provided by the daemon which can be incredibly useful for debugging.

Running KDE Connect on an emulator

How to setup running KDE Connect on an emulator is described here Android_Emulator

</translate>

Retrieved from "https://community.kde.org/index.php?title=KDEConnect&oldid=92583"