These are developer guidelines. For regular user support resources, please refer to our website.
- Build and runtime dependencies
- Building
- Installation
- CI/CD
- Developing under Linux
- Developing under macOS
- Developing under Windows
- Building and troubleshooting binary packages
- Setting up IDEs
- Debugging
- Coding practices
- Code standards
- Committing standards
- Release preparation and deployment proces
- Troubleshooting / FAQ
- Old documentation
Build and runtime dependencies
Dependencies list and minimal versions required
Dependency | Provided feature | master | Stable 5.x | Legacy 4.x | Requirement |
---|---|---|---|---|---|
Qt (Core DBus Widgets Svg Sql Xml Test) | Base libraries | 5.12.0 | 5.9.7 | 4.7.0 | Mandatory |
KF5 libs (Archive CoreAddons Config ConfigWidgets I18n Completion KCMUtils ItemModels ItemViews Service Wallet IconThemes XmlGui TextWidgets Notifications KIO) | Base libraries | 5.2.0 | 5.2.0 | Mandatory | |
KDE4 libs (CoreAddons Config KHtml KDELibs4Support Completion KCMUtils ItemViews) | Base libraries | 4.6.0 | Mandatory | ||
GMP | Arbitrary precision arithmetic | Mandatory | |||
libalkimia | Money basic value object based on GMP | 7.0 | 7.0 | Mandatory | |
KDEPIM libs (Holidays Gpgmepp QGpgme PimIdentities Akonadi Abc) | GPG encryption, KHolidays integration, obtain identity data | 4.6.0 | Optional | ||
KActivities | Activities support | Optional | |||
Gwenhywfar | HBCI/FinTs, OFX, PayPal support | 5.4.1 | 5.1.2 | Optional | |
AqBanking | HBCI/FinTs, OFX, PayPal support | 6.2.5 | 6.0.1 | Optional | |
libical | iCal support | Optional | |||
libofx | OFX plugin | 0.9.4 | 0.9.4 | 0.9.4 | Optional |
vcpkg
An effort is currently underway to include all the KMyMoney's dependencies into the vcpkg repository. The instructions below are not yet applicable to KMyMoney
vcpkg is a command-line package manager for C++, supported on macOS, Linux and Windows platforms. It is a preferred way of obtaining the dependencies due to its ability to deploy them according to a declarative vcpkg.json
manifesto provided with the source code. This allows to maintain a set of dependencies – and soon also their corresponding versions – independently for each branch and automatically switching between them as needed. It also guarantees reproducibility of the dev environment and substantially reduces the effort required to set up a working environment.
Installing vcpkg
Refer to the Getting Started guide on project's website.
Few extra notes:
- do not install vcpkg using brew on macOS, as it was previously found the be problematic.
- install all the additional packages:
- macOS:
brew install autoconf automake libtool bison pkg-config ninja
- Linux: use your distribution's package manager to install the packages listed here. Specifically, you need the packages listed as requirements for "qt5-base" and "qt5-x11extras".
- Windows: you need MS Visual Studio with all the required workloads installed. Please refer to this script for details (search for
Workloads
).
- macOS:
- for any additional required package that needs to be installed by hand, vcpkg will warn (but not fail) about it at the compilation time, so pay attention to its messages in terminal/console.
Setting-up your dev environment
Simply enable an additional switch in your CMake command:
-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
Refer to Using vcpkg with CMake guide on project's website for more details.
You may want to enable binary caching functionality for the vcpkg to re-use any of your previously built packages. As of vcpkg version 2020.07, it is stil an experimental feature and requires a VCPKG_FEATURE_FLAGS=manifest
environment variable set in order to work automatically.
Note that the binary caching will in the future be expanded to automatically download required pre-built packages from the vcpkg and/or KDE repository, however, at the moment you still need to compile all the packages locally. This means that it can take several hours before you're environment gets ready.
You can also disable some optional components as needed – refer to the switches section for more information.
Building
After setting up your dev environment, building the project with cmake will automatically trigger vcpkg to build and/or install the required packages, according to the vcpkg.json
manifest file that is present in the root folder of the repository.
Troubleshooting
- if seeing
CMake Error: CMake was unable to find a build program corresponding to "Unix Makefiles"
or a similar message right after starting CMake, or if it just seems that vcpkg chain is not in use at all, check thevcpkg-manifest-install-out.log
&vcpkg-manifest-install-err.log
files for errors. - if seeing an error about missing dependencies, scroll your terminal back and see if you missed a warning about a external package required – see above
More resources
- https://github.com/microsoft/vcpkg
- http://vcpkg.readthedocs.io
- https://docs.microsoft.com/en-us/cpp/build/vcpkg
CMake switches
There are several CMake options available that can be enabled/disabled to change the set of features enabled or the compilation behavior .
You can look them up and adjust interactively with:
$ ccmake .
Docker
Debian/Ubuntu
The easiest way to install dependencies is to:
- Enable apt repositories with sources:
sudo sed -i -- 's/#[ ]*deb-src/deb-src/g' /etc/apt/sources.list` sudo apt-get update
- Install all build dependencies of
kmymoney
package:sudo apt-get build-dep kmymoney
- Install any additional, optional dependencies:
sudo apt-get install qt5-default libsqlcipher-dev libqt5sql5-* breeze-icon-theme
Bleeding edge KDE Neon Ubuntu repositories
If you need to test something with libraries newer than provided by the distribution's stable repositories, you may try to add KDE experimental repository to your apt sources to get ahold experimental versions of the dependency packages. For example, for Ubuntu 20.04 LTS Bionic:
sudo apt-get install apt-utils
sudo apt-get install gnupg wget
sudo wget -qO - http://archive.neon.kde.org/public.key | apt-key add -
sudo echo "deb http://archive.neon.kde.org/testing bionic main" >> /etc/apt/sources.list
sudo echo "deb-src http://archive.neon.kde.org/testing bionic main" >> /etc/apt/sources.list
sudo apt get update
sudo apt get upgrade
Update the name of the Ubuntu release (bionic) as needed.
However, please do not try this on your regular development box. Use a disposable dev box (VMs, containers) instead, as it can – and often will – damage the consistency of the operating system.
macOS
On macOS the dependencies can be installed easily using Homebrew and the KDE Homebrew tap.
To prepare the tap, as instructed by the KDE Homebrew tap manual, issue the following:
brew untap kde-mac/kde 2> /dev/null
brew tap kde-mac/kde https://invent.kde.org/packaging/homebrew-kde.git --force-auto-update
"$(brew --repo kde-mac/kde)/tools/do-caveats.sh"
Next, install the dependencies:
brew install brew install kde-mac/kde/kdiagram kde-mac/kde/kf5-breeze-icons kde-mac/kde/kf5-kactivities kde-mac/kde/kf5-kcmutils kde-mac/kde/kf5-kdewebkit kde-mac/kde/kf5-kio kde-mac/kde/kf5-kitemmodels kde-mac/kde/kf5-kross kde-mac/kde/libalkimia libical libofx sqlcipher
Make sure to scroll up the terminal log and run all the manual steps as required by the brew formulae:
ln -sfv "$(brew --prefix)/share/kf5" "$HOME/Library/Application Support"
ln -sfv "$(brew --prefix)/share/knotifications5" "$HOME/Library/Application Support"
ln -sfv "$(brew --prefix)/share/kservices5" "$HOME/Library/Application Support"
ln -sfv "$(brew --prefix)/share/kservicetypes5" "$HOME/Library/Application Support"
At this point all the dependencies should be installed successfully.
Please refer to the macOS development instructions for compilation instructions.
Windows
Building
Installation
CI/CD
Developing under Linux
Developing using Docker Linux image
Developing under macOS
using craft root dev environment
using brew dev environment
To compile make sure to use Qt from homebrew and to have gettext in the path:
cd kmymoney # i.e. the source folder
mkdir build
cd build
CMAKE_PREFIX_PATH=/usr/local/opt/qt PATH=$PATH:/usr/local/opt/gettext/bin cmake ..
cmake -DCMAKE_BUILD_TYPE=Release ..
# look for messages about missing dependencies!
make kmymoney
using vcpkg
Developing under Windows
using craft root dev environment
using WSL
using vcpkg
Building and troubleshooting binary packages
craft macOS packages
craft Windows packages
craft blueprints
macOS brew packages
AppImage packages
Setting up IDEs
KDevelop
Clion
VS
VSCode
QtCreator
GitHub Codespaces
Debugging
Pretty printers/Data formatters
There's three types of pretty printers (GDB) or data formatters (LLDB) to be considered when working with KMyMoney:
Qt structures
The most complete and up-to-date printers are provided by the Qt itself, via the Qt Creator, so if you're using it as your IDE of choice, you can skip this section. KDevelop also ships with own formatters (GDB, LLDB), albeit they may not be up to par with Qt's own.
If you use any other IDE, the recommended way to install any those is to check them out directly from their repositories and configure debugger(s) to use them. Since the source code for both of them is very heavy, the instructions below perform a sparse checkout to only get the scripts needed (requires git version > 2.26.0).
from Qt Creator
Qt Creator provides printers for both debuggers, so let's configure them both, even if you tend to use one of them only:
-
mkdir .gdb
andmkdir .lldb
(if any doesn't exist) cd .gdb
-
git clone --filter=blob:none --no-checkout --depth 1 --sparse https://github.com/qt-creator/qt-creator
- the
--depth 1
will checkout master only. Skip it if you want to be able to switch between branches in the future.
- the
cd qt-creator && git sparse-checkout init --cone
git sparse-checkout add "share/qtcreator/debugger"
git checkout
ln -s ~/.gdb/qt-creator ~/.lldb/
You can naturally do a git pull
in .gdb/qt-creator
or .lldb/qt-creator
folder at any time to update the scripts as needed.
Now that you have a copy of the scripts, let's make debuggers use them:
GDB
Qt Creator's GDB printers are currently broken, refer to https://bugreports.qt.io/browse/QTCREATORBUG-25199 for updates
Edit the ~/.gdbinit
and add the following lines:
python import sys
python from pathlib import Path
python sys.path.insert(1, str(Path.home().joinpath('.gdb/qt-creator/share/qtcreator/debugger')))
python from gdbbridge import *
LLDB
Edit the ~/.lldbinit
and add the following lines:
from KDevelop
KDevelop provides printers for both debuggers, so let's configure them both, even if you tend to use one of them only:
-
mkdir .gdb
andmkdir .lldb
(if any doesn't exist) cd .gdb
-
git clone --filter=blob:none --no-checkout --depth 1 --sparse https://invent.kde.org/kdevelop/kdevelop
- the
--depth 1
will checkout master only. Skip it if you want to be able to switch between branches in the future.
- the
cd qt-creator && git sparse-checkout init --cone
git sparse-checkout add "plugins/gdb/printers" && git sparse-checkout add "plugins/lldb/formatters"
git checkout
ln -s ~/.gdb/kdevelop ~/.lldb/
You can naturally do a git pull
in .gdb/kdevelop
or .lldb/kdevelop
folder at any time to update the scripts as needed.
Now that you have a copy of the scripts, let's make debuggers use them:
GDB
Edit the ~/.gdbinit
and add the following lines:
python import sys
python from pathlib import Path
python sys.path.insert(1, str(Path.home().joinpath('.gdb/kdevelop/plugins/gdb/printers')))
python from qt import register_qt_printers
python from kde import register_kde_printers
python register_qt_printers (None)
python register_kde_printers (None)
LLDB
Edit the ~/.lldbinit
and add the following lines:
KDE structures
According to this post, KDE doesn't provide any explicit printers for for KDE classes as we don't have anything that doesn't build off the basic Qt types.
KMyMoney structures
Remote debugging notes
If you're debugging in a remote session, make sure that the ~/.gdbinit
or ~/.lldbinit
and ~/.lldb
or ~/.lldb
(respectively) are being copied by your IDE to your remote host. Alternatively, if you're using Docker for debugging, you can have them bind-mounted, but bear in mind that if you symlinked .gdb
or .lldb
subfolders as instructed above, these will not be readable from within the container.
Debugging binary packages
Coding practices
Overridden Qt types
KMyMoney has overridden some of the Qt types for our own convenience.
QSqlQuery
as KMMSqlQuery
KMMSqlQuery
is a convenience class overridden to enable advanced SQL tracing for debugging purposes. Disabled by default, enabled with ENABLE_SQLTRACER
CMake switch.
Icons
Using icons in the code
#include "icons/icons.h"
- Reference an icon of choice using
QIcon Icons::get(Icons::Icon icon)
, whereIcons::Icon icon
is a key value of one theiconMappings
pre-defined in icons.cpp, e.g.:
ui->m_updateButton->setIcon(Icons::get(Icon::DialogOK));
Adding a new icon
-
Add a new entry to the
iconMappings
hash table in icons.cpp- Value must be a name of an icon from the Breeze iconset
- For the Key, think of a name that accurately describes an actual action in the context it will be used, as opposed to just mirroring the filename of the Breeze icon you chose to represent it. This in particular applies when you're being creative and repurpose an icon to use it out of its original context. For example, an entry for an action that downloads online statements for all accounts is defined as:
{Icon::AccountUpdate, QStringLiteral("edit-download")}
- Such approach allows us to easily refactor it in the future, should we e.g. decide that
edit-download
doesn't really cut it and we want to work with Breeze VDG team to come up with a unique, non-generic icon for this action. - That having said, some keys will naturally match the name of icons used, e.g.
{Icon::DialogOK, QStringLiteral("dialog-ok")}
. - NOTE: it is OK if for several Keys to reference the same Breeze icon (have same value). It is also OK to add a placeholder Key and not reference any Breeze icon at all.
- Such approach allows us to easily refactor it in the future, should we e.g. decide that
-
Copy the referenced Breeze icon(s) to the source code. The copy_from_breeze.sh script will do that automatically for both regular and dark icons:
- checkout out the breeze-icons repository
-
cd ~/sourcecode/kmymoney/icons
and run./copy_from_breeze.sh ~/sourcecode/breeze-icons
- this will not only copy your newly added icons, but may also potentially update some of the previously checked-in icons that had since been updated in
breeze-icons
repository by the KDE VDG team. In such case,git add
and commit your icons only.
Packaging specifics
Embedding of the icons with the code is used on Linux/BSD for both Release and Debug builds, but only for Debug builds on Windows and macOS. This is because for Release builds on these, craft builds KMyMoney by linking it to the KIconThemes
library, which, in turn, sources the upstream breeze icons into icontheme.rcc
and bundles it with the package.
Note that the disadvantage of using icontheme.rcc
is that it does not support Dark icons, and so we're most likely going to unify macOS and Windows packages behavior with *nix in the near future.
Code standards
Committing standards
Please refer to the general KDE Commit Policy
Release preparation and deployment proces
Troubleshooting / FAQ
The git branch is broken! What do I do now?
Usually the reason for this is that one of the developers made a change to the code that requires a clean reconfigure. Please run a git pull --rebase
to update your local repository.
If you still have a problem compiling, contact the project maintainers. Refer to the Support page for the means of contact available.
When I compile from source, all the icons show up as missing. What did I do wrong?
Usually the reason for this is that you didn’t run ‘make install’ as root. This step actually copies all of the icons, and other files needed by KMyMoney to run properly. If you did run this, make sure you passed the correct prefix to ‘configure’ at the beginning of your compile.
You may also want to look into the prefix.sh
script if you're debugging or running the executable from a local, relative location.
Note that this issue is solved in master by having the icons embedded into binaries.
How can I use distcc to help speed up compilation of KMyMoney, or other KDE (C++) applications?
distcc is a tool developed from the Samba team to help distribute compiling of applications on multiple machines at once. You have to set up distcc on each machine that you want to compile on, and distcc takes care of distributing the compile tasks to all of the various machines. An article at ibm.com is what got me started, and cut down my compile times by a factor of 8.
After I first installed distcc, I couldn't get the distributed compiling to work. I stumbled upon this post in the gentoo forums which told me how to get distcc to work with C++ applications. After I created the /usr/bin/dist++ shell script, (and performing an 'export CXX=dist++'), the next time I ran make on KMyMoney, it was being compiled on two machines.
My compile with distcc was about 8 times as fast as compiling just on my local machine. My local machine is a Athlon XP 1700, 512 MB ram. Compiling with just the local machine took 17m51s after running make clean on my current codebase. I added my second computer, a 2.4 GHz Celeron, with 384 MB ram, and the compile time shrank to 2m45s.
Another useful link on this topic is at OSNews.com.
Old documentation
The below is likely outdated and needs to be rewritten/incorporated into the up-to-date instructions above
Building and Installation
If possible, it is always preferred to use a package specifically prepared for your distribution. However, if one is not available, or you want a more recent version, you can use the latest tarball. If you really need the most recent version, such as to test a new bug fix, get the source from [https://projects.kde.org/projects/extragear/office/kmymoney KDE Git] at
git clone git://invent.kde.org/office/kmymoney
To install, read the README.cmake file in the root folder of the source. The basic steps are the following:
First, make sure you have uninstalled any old versions of kmymoney through your package manager and/or sudo make uninstall depending on how it was installed last time. Then:
$ mkdir build
$ cd build
$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/
# optional, to adjust build configuration
$ ccmake .
$ make
$ sudo make install
It is important that the prefix is the same one that is used by your already installed KDE software. If it does not match, you will run into problems later. The separate build directory is mandatory (out of source build). The install step should be executed with admin privileges. Either switch to root or use sudo, or the appropriate steps for your installation.
To execute, either look for KMyMoney on the Office menu, or type kmymoney in a console window.
Link to Debian bugs
The bugs in Debian tracker can be linked back to http://build.kde.org
- Open a bug report in KDE Bug Tracking System (BTS)
- Link it to Debian bug number using "forwarded". See http://www.debian.org/Bugs/server-control#forwarded
- When the bug is fixed in KDE BTS, the status will be synced in Debian BTS too.
Localization
If you are installing from Git source, you need to install your locale files by hand. If you are installing from the tarball provided above, please skip this section.
To localize you will need to download the appropriate kmymoney.po file from http://websvn.kde.org/trunk/l10n-kf5/<country_code>/messages/extragear-office/, replacing <country_code> with the correct one for your locale e.g. es would give http://websvn.kde.org/trunk/l10n-kf5/es/messages/extragear-office/. Once done, either by switching to root or using sudo, do the following:
-
Copy the kmymoney.po file into /usr/share/locale/<country_code>/
-
In that folder run:
$ msgfmt kmymoney.po -o LC_MESSAGES/kmymoney.mo
Note: use the msgfmt that comes with your distribution.
Reporting bugs
Obtain a useful backtrace on Windows
If you would like to create a bug report about an application crash on Windows you need to take care of the following to create a useful report:
- make sure that you can reproduce the crash
- download the debug information that matches your version ([http://downloads.sourceforge.net/project/kmymoney2/KMyMoney-Windows/4.6.3/kmymoney-4.6.3-debug-info.7z 4.6.3])
- extract the archive in a folder of your choice (in this example c:\temp\kmm-debug-info) using 7z archiver
- open cmd.exe
- run set _NT_SYMBOL_PATH=c:\temp\kmm-debug-info
- run "c:\Program Files\KMyMoney\bin\kdeinit4.exe" --terminate
- run "c:\Program Files\KMyMoney\bin\kmymoney.exe"
- try to reproduce the crash and use DrKonqi the KDE crash handler that appears when the application crashes (only on Windows 7) to report the crash on bugs.kde.org Notes:
- DrKonqi will inform you if the crash report is useful or not (it contains the debug information or not)
- if DrKonqi says that the report is not useful something went wrong in the above steps
- if you can't reproduce the crash immediately you can run KMyMoney for a while in an environment in which _NT_SYMBOL_PATH is defined as above (you can use a batch file for that)
- when you no longer need the debug information you can safely delete the folder c:\temp\kmm-debug-info
Other
Windows specific configuration options
KDE provided file dialogs for example for importer
add to share/config/kdeglobals
[KFileDialog Settings]
Native=false
Enable debug log level for online banking plugin
Open a command shell in kmymoney 'bin' dir and run
set AQBANKING_LEVEL=debug
set GWEN_LOGLEVEL=debug
Then start kmymoney with
kmymoney
Enable verbose log level for online banking plugin
Open a command shell in kmymoney 'bin' dir and run
set AQBANKING_LEVEL=verbous
set GWEN_LOGLEVEL=verbous
Then start kmymoney with
kmymoney
Show aqbanking log file path
- Start kmymoney
- Open Settings->configure KMymoney
- In the Main tab select "Support" -> on that page there is a link to the current aqbanking lo path