In KDE we have a great group of developers hacking on a variety of applications. We usually have no problems getting our software out to end users on Linux because distributions help us packaging and distributing our software.

Where we do have problems, for the major applications, is ensuring our software works on other platforms such as Windows and macOS. This short guide gives a few tips to understand how to make your KDE pet project work on Windows by at least testing it once on said system and verifying a few basic things.

## Build your application on Windows

Set up a Windows VM (Windows 7+), a compiler (MSVC2015+ (recommended) -- or let Craft auto-setup MinGW during bootstrap) and build your application using Craft. If set up properly, all you need to do now is to run something along:

craft filelight


Craft will take care of installing all dependencies required to build filelight (i.e. deps of Qt5, Qt5, deps of KF5, KF5, ...) and only then builds the filelight project.

The end result is one single install root which contains the images of every package you've just built. Now starting filelight is as easy as running this in the terminal:

filelight


## Run the unit tests

Again, easy to do with Craft. If your pet project has some unit tests availabe, you can easily run them by invoking e.g.:

craft --test kcoreaddons


This will invoke ctest in the correct build directory and run the project's test suite.

### Package the application

Craft on Windows has functionality to create installers out of installed packages.

craft --package filelight


The way this is implemented is pretty simple but powerful

• Craft collects all files of every image directories of the packages your application depends on
• Craft collects all files of the application's image directory
• Craft puts them into an intermediate install root.
• After that, Craft will strip unneeded files according to blacklists (cf. 'blacklist.txt' and similar functionality in blueprints)
• After that custom scripts may be run
• After that makensis is called (from the NSIS installer framework) which basically zips up the whole install root and generates a final installer executable

## Things you usually need to fixup

### Installer icon

Handled by: Craft

The very first impression counts, so why don't make your installer binary as sexy as possible?

Again let's take the installer generated for filelight. One version without an installer icon set, and one with the filelogo set as logo:

This is very easy to do with Craft which contains a few helpers to instruct the NSIS installer framework (the scriptable tool we use to generate Windows installers to begin with) properly to our likings.

An exemplary patch in craft-blueprints-kde.git (KDE's blueprint collection for Craft):

commit 1258a4450a1ee2f620856c150678dcaf5b5e7bad
Author: Kevin Funk <kfunk@kde.org>
Date:   Mon Nov 20 14:13:04 2017 +0100

Created with:
convert /usr/share/icons/breeze/apps/48/filelight.svg ./kde/kdeutils/filelight/filelight.ico

diff --git a/kde/kdeutils/filelight/filelight.ico b/kde/kdeutils/filelight/filelight.ico
new file mode 100644
index 0000000..1b6a71b
Binary files /dev/null and b/kde/kdeutils/filelight/filelight.ico differ
diff --git a/kde/kdeutils/filelight/filelight.py b/kde/kdeutils/filelight/filelight.py
index 0003f30..ac602c6 100644
--- a/kde/kdeutils/filelight/filelight.py
+++ b/kde/kdeutils/filelight/filelight.py
@@ -30,6 +30,7 @@ class Package(CMakePackageBase):
self.defines["productname"] = "Filelight"
self.defines["website"] = "https://utils.kde.org/projects/filelight/"
self.defines["executable"] = "bin\\filelight.exe"
+        self.defines["icon"] = os.path.join(self.packageDir(), "filelight.ico")

self.ignoredPackages.append("binary/mysql")
self.ignoredPackages.append("libs/qt5/qtdeclarative") # pulled in by solid


This patch adds an ICO file to the repository and references it in the filelight blueprint. Craft takes care of telling NSIS to use this ICO file as the installer icon internally while building your package with craft --package filelight.

### Application icon

Handled by: CMake

For getting the custom application, you need to embrace using Extra CMake Modules ECMAddAppIcon module which provides the CMake function ecm_add_app_icon(...) which in turn allows you to amend your executable with an application icon.

Here's an exemplary patch taken from filelight.git:

commit d7c7f1321547197e5bb9ceba6b8ccc51790bef8b
Author: Kevin Funk <kfunk@kde.org>
Date:   Mon Nov 20 23:14:30 2017 +0100

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 4c1e5dc..b8b6eda 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -25,6 +25,7 @@ cmake_minimum_required (VERSION 2.8.12 FATAL_ERROR)
find_package(ECM 1.3.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH}${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR}) +include(ECMAddAppIcon) include(ECMGenerateHeaders) include(ECMInstallIcons) include(ECMMarkNonGuiExecutable) diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 622c9d8..06f5e8d 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -34,8 +34,16 @@ set(filelight_SRCS summaryWidget.cpp historyAction.cpp mainWindow.cpp - main.cpp) - + main.cpp +) +set(filelight_ICONS +${CMAKE_CURRENT_SOURCE_DIR}/../misc/16-apps-filelight.png
+    ${CMAKE_CURRENT_SOURCE_DIR}/../misc/32-apps-filelight.png +${CMAKE_CURRENT_SOURCE_DIR}/../misc/48-apps-filelight.png
+    ${CMAKE_CURRENT_SOURCE_DIR}/../misc/64-apps-filelight.png +) +ecm_add_app_icon(filelight_SRCS ICONS +${filelight_ICONS})
ki18n_wrap_ui(filelight_SRCS dialog.ui)

$sudo apt-get install build-essential libbz2-dev libxslt-dev libxml2-dev shared-mime-info oxygen-icon-theme libgif-dev libvlc-dev libvlccore-dev doxygen gperf bzr libxapian-dev fontforge libgcrypt20-dev libattr1-dev network-manager-dev libgtk-3-dev xsltproc xserver-xorg-dev xserver-xorg-input-synaptics-dev libpwquality-dev modemmanager-dev libxcb-keysyms1-dev libepoxy-dev libpolkit-agent-1-dev libnm-util-dev libnm-glib-dev libegl1-mesa-dev libxcb-xkb-dev libqt5x11extras5-dev libwww-perl libxml-parser-perl libjson-perl libboost-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev libarchive-dev liblmdb-dev cmake git extra-cmake-modules "libkf5.*-dev" libgrantlee5-dev llvm libclang-dev  ## Git remote prefix Let's setup a "kde:" prefix for git commands. Add the following text to your ~/.gitconfig: [url "git://anongit.kde.org/"] insteadOf = kde: [url "ssh://git@git.kde.org/"] pushInsteadOf = kde:  ## Install kdesrc-build kdesrc-build is, simply put, a user-space package manager, which compiles KDE-related projects from source and installs them into a designated directory. Let's set up kdesrc-build to install KDevelop into our$HOME:

mkdir ~/kdesrc
cd ~/kdesrc
git clone kde:kdesrc-build
cd kdesrc-build
cp kdesrc-buildrc-kf5-sample ~/.kdesrc-buildrc

# Install a symlink of kdesrc-build to a location in PATH
mkdir ~/bin
ln -s $PWD/kdesrc-build ~/bin export PATH=~/bin:$PATH


You should append the line export PATH=~/bin:$PATH to ~/.bashrc so kdesrc-build is available in PATH everytime you open a terminal. ### Configure kdesrc-build edit ~/.kdesrc-buildrc  Replace /path/to/kdesrc-build/kf5-qt5-build-include with ~/kdesrc/kdesrc-build/kf5-qt5-build-include in that file Add ignore-kde-structure true and make-options -jN to the global section in ~/.kdesrc-buildrc (this will make your life easier...): global ... ignore-kde-structure true make-options -j5 # NOTE: 5 is the number of jobs, this should usually be (number-of-cpu-cores + 1) ... end global  ## Installing KDevelop and dependencies Let kdesrc-build handle the compilation + installation of KDevelop and its (direct) dependencies $ kdesrc-build --debug libkomparediff2 kdevelop-pg-qt kdevelop


The --debug parameter will give you the verbose output, all command invocations and compiler output. Helpful for trouble-shooting.

Note: If you ever want to update+recompile your complete KDevelop checkout(s), you simply run above command again (it'll reuse your old build information, so it'll just recompile the bare minimum)

## Setting up a script for preparing the environment

Copy these commands to a new file called ~/.env-kf5:

export KF5=~/kde-5
export QTDIR=/usr
export CMAKE_PREFIX_PATH=$KF5:$CMAKE_PREFIX_PATH
export XDG_DATA_DIRS=$KF5/share:$XDG_DATA_DIRS:/usr/share
export XDG_CONFIG_DIRS=$KF5/etc/xdg:$XDG_CONFIG_DIRS:/etc/xdg
export PATH=$KF5/bin:$QTDIR/bin:$PATH export QT_PLUGIN_PATH=$KF5/lib/plugins:$KF5/lib64/plugins:$KF5/lib/x86_64-linux-gnu/plugins:$QTDIR/plugins:$QT_PLUGIN_PATH
#   (lib64 instead of lib, on OpenSUSE and similar)
export QML2_IMPORT_PATH=$KF5/lib/qml:$KF5/lib64/qml:$KF5/lib/x86_64-linux-gnu/qml:$QTDIR/qml
$kdevelop  That's it already! You should have a working version of KDevelop 5 running now! # Hacking on KDevelop Enter the source directory, edit files (of course you can do that by importing ~/kdesrc/kdevelop into KDevelop, too! $ cd ~/kdesrc/kdevelop
<edit files>


Now, to recompile kdevelop, just invoke kdesrc-build again:

$kdesrc-build --debug kdevelop  OR just go to the build directory and invoke: $ cd ~/kdesrc/build/kdevelop
$make install  Restart KDevelop: $ kdevelop


## Contributing patches

The recommended way to contribute patches it to post them to KDE's Phabricator instance. The easiest way to create patches is to use Phabricator's Arcanist command-line tool.

The very brief version of what you have to do is:

$cd ~/kdesrc/kdevelop <edit files>$ arc diff
<arc will guide you through the required steps>


See here for more details: https://techbase.kde.org/Development/Phabricator#Using_Arcanist (in case you're not familiar with Arcanist at all)

# Troubleshooting

## Problems with kdesrc-build

In case kdesrc-build fails it will usually print a few lines like this at the end of the run:

<<<  PACKAGES FAILED TO BUILD  >>>
libkomparediff2 - ~/kdesrc/log/2016-02-16-07/libkomparediff2/cmake.log
:-(


Inspect that log to figure out what's going on:

$cat ~/kdesrc/log/2016-02-16-07/libkomparediff2/cmake.log CMake Error at CMakeLists.txt:5 (find_package): Could not find a package configuration file provided by "ECM" (requested version 0.0.9) with any of the following names: ECMConfig.cmake ecm-config.cmake Add the installation prefix of "ECM" to CMAKE_PREFIX_PATH or set "ECM_DIR" to a directory containing one of the above files. If "ECM" provides a separate development package or SDK, be sure it has been installed.  In this case: the ECM (extra cmake modules) package is missing. The way you usually fix these kind of problems is to head over to http://packages.ubuntu.com and search for the distro package providing a particular file (ECMConfig.cmake in this case). So the package search reveals extra-cmake-modules being a hot candidate; to fix above error we simply install the package and the restart the build: $ apt-get install extra-cmake-modules
<restart build>
\$ kdesrc-build ...


The error should be gone now.

# Help

We're highly active in IRC, feel free to join us by visiting #kdevelop on Freenode. A web-based client can be found here: https://kiwiirc.com/client/irc.freenode.org/kdevelop

Just contact one of the core developers with the nick names milian, scummos, apol or kfunk if you need help.

The other way to get in touch is to write a mail to kdevelop-devel@kde.org

See here for details on how to reach us: https://www.kdevelop.org/contribute-kdevelop

We're always trying to be as helpful as possible!

Enjoy!

Update (Jan 2018): Removed any mention of the kdevplatform repository, which is now part of the KDevelop repository. Thus kdevplatform no longer needs to be built separately.