|
|
[[_TOC_]]
|
|
|
|
|
|
# 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 | :negative_squared_cross_mark: |Mandatory |
|
|
|
| KDE4 libs (CoreAddons Config KHtml KDELibs4Support Completion KCMUtils ItemViews) | Base libraries | :negative_squared_cross_mark: | :negative_squared_cross_mark: | 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 library manager
|
|
|
|
|
|
**A set of minimal KMyMoney dependencies was upstreamed to vcpkg. Some of the ports required for optional functionality are still [pending approval](https://github.com/pulls?q=is%3Apr+is%3Aopen+author%3Awrobelda+repo%3Amicrosoft%2Fvcpkg+). You can use [this](https://github.com/wrobelda/vcpkg/tree/kmm_test) branch in the meanwhile, which has all of these PRs pulled-in.**
|
|
|
|
|
|
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 us to maintain a set of dependencies [and their corresponding versions](https://devblogs.microsoft.com/cppblog/take-control-of-your-vcpkg-dependencies-with-versioning-support/) 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
|
|
|
|
|
|
**It is on vcpkg's [roadmap](https://github.com/microsoft/vcpkg/wiki/Roadmap) to ship vcpkg with Vistual Studio Code and Visual Studio. Until then you'll need to follow the instructions below.**
|
|
|
|
|
|
Refer to the [Getting Started](https://github.com/microsoft/vcpkg#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](https://github.com/microsoft/vcpkg/blob/master/scripts/azure-pipelines/linux/provision-image.sh). 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](https://github.com/microsoft/vcpkg/blob/master/scripts/azure-pipelines/windows/deploy-visual-studio.ps1) 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](https://github.com/microsoft/vcpkg#using-vcpkg-with-cmake) guide on project's website for more details, as well as [CMake integration](https://github.com/microsoft/vcpkg/blob/master/docs/users/integration.md#cmake-integration) section of the documentation. Additional vcpkg CMake switches are documented [here](https://github.com/microsoft/vcpkg/blob/master/docs/users/manifests.md#cmake-integration).
|
|
|
|
|
|
## Compiling the dependencies
|
|
|
|
|
|
After setting up your dev environment as instructed above, compiling the project with CMake will automatically trigger vcpkg to build the required packages, according to the `vcpkg.json` manifest file that is present in the root folder of the repository.
|
|
|
|
|
|
Note that this will initially compile the complete tree of the dependencies – i.e. those that are explicitly defined by the manifest file, as well as their own dependencies. This means that it may take several hours before your environment is ready.
|
|
|
|
|
|
Once built, the binaries built will be cached as zip files [on your filesystem](https://github.com/microsoft/vcpkg/blob/master/docs/users/binarycaching.md#configuration) and re-used on each consecutive installation attempt. That having said, they will be _ignored_ each time the build configuration or [any other factor changes](https://github.com/microsoft/vcpkg/blob/master/docs/users/binarycaching.md#implementation-notes-internal-details-subject-to-change-without-notice) and, as a result, will get rebuilt, so do not be surprised when that happens.
|
|
|
|
|
|
In the future, we may set up CI/CD infrastructure to allow downloading the required pre-built packages.
|
|
|
|
|
|
You can also disable some optional components as needed – refer to the [switches](#cmake-switches) section and [VCPKG_MANIFEST_FEATURES](https://github.com/microsoft/vcpkg/blob/master/docs/users/manifests.md#vcpkg_manifest_features) CMake switch documentation for more information.
|
|
|
|
|
|
## Troubleshooting
|
|
|
|
|
|
* you can use `--debug` switch to force vcpkg to show detailed logs
|
|
|
* 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](#installing-vcpkg)
|
|
|
|
|
|
## More resources
|
|
|
|
|
|
* <https://github.com/microsoft/vcpkg>
|
|
|
* <http://vcpkg.io>
|
|
|
* <https://docs.microsoft.com/en-us/cpp/build/vcpkg>
|
|
|
|
|
|
# Docker
|
|
|
|
|
|
A `docker\Dockerfile` and a `docker\docker-compose.yaml` are provided for your convenience. They can be used to set up a complete development environment using the current stable Ubuntu distribution (you are welcome to contribute Dockerfiles for other distributions as well).
|
|
|
|
|
|
The `docker-compose.yaml` assumes some good defaults, while the customizable variables are in `.env` file. You may in particular want to tweak the `volumes` section for the folders that are mapped to your local filesystem, e.g. a `/kmm_books` volume mapped to `~/KMyMoney` folder, which is presumably where you'd keep your testing book files, or a `/root/.config/kmymoney` volume mapped to where your host operating system keeps KMyMoney's configuration files. What's more, check out the [Remote debugging](#remote-debugging-notes) notes to make sure you set up the GDB/LLDB pretty printers correctly.
|
|
|
|
|
|
Please refer to your IDE's of choice instructions on how to configure it for remote development/debugging, and also our [section](#setting-up-ides) on setting up the IDEs. The basic approach, however, is:
|
|
|
|
|
|
1. `docker-compose.yaml` sets the `DISPLAY` variable inside the container to `host.docker.internal:0`. `host.docker.internal`, in turn, is resolved internally in your Docker guest container to your host's IP address, which means that the KMyMoney executable running inside the container will be attempting to connect an X11 server running remotely on your host system.
|
|
|
2. Running the X11 server in your host, however, is not enough, as the default security settings forbid it from accepting any connections not coming from the localhost – and in this case, your guest container is such an "outside" system, with its own IP address.
|
|
|
3. You need to therefore set your server to accept connections from your guest container's IP address. The easiest way to do it is by issuing:
|
|
|
|
|
|
```shell
|
|
|
xhost + `docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' kmymoney_dev_env`
|
|
|
```
|
|
|
|
|
|
, where:
|
|
|
* `xhost` is _"a program used to add and delete host names or user names to the list allowed to make connections to the X server"_.
|
|
|
* `docker inspect` allows to pull the guest container's IP address
|
|
|
* `kmymoney_dev_env` is a name of the container, as defined by the `docker-compose.yaml`. If you changed it there, you need to use that name here, too.
|
|
|
4. Ideally you want the above command to be executed each time before you start your remote debugging session in your IDE.
|
|
|
|
|
|
## Troubleshooting
|
|
|
|
|
|
If you run into issues:
|
|
|
|
|
|
1. Make sure you can ping your host from your guest. Docker has a history of bugs related to `host.docker.internal` resolution, especially in experimental versions. Check it with:
|
|
|
|
|
|
```shell
|
|
|
docker exec -it kmymoney_dev_env ping host.docker.internal
|
|
|
```
|
|
|
|
|
|
, where `kmymoney_dev_env` is your container's name.
|
|
|
2. Make sure that the X11 server is running on your host:
|
|
|
|
|
|
```shell
|
|
|
telnet localhost 6000
|
|
|
```
|
|
|
3. ... and that it is accessible from your guest:
|
|
|
|
|
|
```shell
|
|
|
docker exec -it kmymoney_dev_env telnet host.docker.internal 6000
|
|
|
```
|
|
|
|
|
|
# Linux package managers
|
|
|
|
|
|
Most popular distributions ship KMyMoney in their official repositories, therefore also provide all the necessary dependencies. You may also decide to use [Docker container](#docker) for development, if you find it more convenient or useful, e.g. if your distribution provides a different (older) version of dependency required.
|
|
|
|
|
|
## Debian/Ubuntu
|
|
|
|
|
|
The easiest way to install dependencies is to:
|
|
|
|
|
|
1. Enable apt repositories with sources:
|
|
|
|
|
|
```shell
|
|
|
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 **Focal**:
|
|
|
|
|
|
```shell
|
|
|
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 focal main" >> /etc/apt/sources.list
|
|
|
sudo echo "deb-src http://archive.neon.kde.org/testing focal main" >> /etc/apt/sources.list
|
|
|
sudo apt get update
|
|
|
sudo apt get upgrade
|
|
|
```
|
|
|
|
|
|
Update the name of the Ubuntu release (**focal**) 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 Homebrew
|
|
|
|
|
|
On macOS the dependencies can be installed easily using [Homebrew](https://brew.sh) and the [KDE Homebrew tap](https://invent.kde.org/packaging/homebrew-kde).
|
|
|
|
|
|
To prepare the tap, as instructed by the KDE Homebrew tap [manual](https://invent.kde.org/packaging/homebrew-kde#homebrew-kde), issue the following:
|
|
|
|
|
|
```shell
|
|
|
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:
|
|
|
|
|
|
```shell
|
|
|
brew install --only-dependencies kmymoney
|
|
|
```
|
|
|
|
|
|
Or, for the master branch (HEAD) dependencies:
|
|
|
|
|
|
```shell
|
|
|
brew install --only-dependencies kmymoney --HEAD
|
|
|
```
|
|
|
|
|
|
Make sure to scroll up the terminal log and run all the manual steps as required by the brew formulas installed. At the very minimum you will have to issue `"$(brew --repo kde-mac/kde)/tools/do-caveats.sh"` once again.
|
|
|
|
|
|
At this point all the dependencies should be installed successfully.
|
|
|
|
|
|
Please refer to the [Compilation](#compilation) for further instructions, and also [macOS development instructions](#using-brew-dev-environment) for extra notes.
|
|
|
|
|
|
Note that Qt 5.15.x has a limited support for Apple Silicon: [QTBUG-85279](https://bugreports.qt.io/browse/QTBUG-85279), [QTBUG-85546](https://bugreports.qt.io/browse/QTBUG-85546), [Homebrew #6710](https://github.com/Homebrew/homebrew-core/pull/67170). As a result, brew build of ARM64 Qt comes without WebEngine enabled – which as of KMyMoney 5.1.x is still optional, as we default to QtWebKit. |