Skip to content

GitLab

KMyMoney
KMyMoney
Last edited by Dawid Wrobel
Page history

Home

These are developer guidelines. For regular user support resources, please refer to our website.

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).
  • 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 the vcpkg-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

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:

  1. Enable apt repositories with sources: 
    sudo sed -i -- 's/#[ ]*deb-src/deb-src/g' /etc/apt/sources.list`
sudo apt-get update
  2. Install all build dependencies of kmymoney package: sudo apt-get build-dep kmymoney
  3. 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:

  1. mkdir .gdb and mkdir .lldb (if any doesn't exist)
  2. cd .gdb
  3. 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.
  4. cd qt-creator && git sparse-checkout init --cone
  5. git sparse-checkout add "share/qtcreator/debugger"
  6. git checkout
  7. 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:

  1. mkdir .gdb and mkdir .lldb (if any doesn't exist)
  2. cd .gdb
  3. 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.
  4. cd qt-creator && git sparse-checkout init --cone
  5. git sparse-checkout add "plugins/gdb/printers" && git sparse-checkout add "plugins/lldb/formatters"
  6. git checkout
  7. 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

#12

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

  1. #include "icons/icons.h"
  2. Reference an icon of choice using QIcon Icons::get(Icons::Icon icon), where Icons::Icon icon is a key value of one the iconMappings pre-defined in icons.cpp, e.g.:
    ui->m_updateButton->setIcon(Icons::get(Icon::DialogOK));

Adding a new icon

  1. 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.

  2. 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

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/&lt;country_code&gt;/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
  1. Start kmymoney
  2. Open Settings->configure KMymoney
  3. In the Main tab select "Support" -> on that page there is a link to the current aqbanking lo path