Fava GTK allows to use the Fava and Beancount double-entry bookkeeping software packages as a desktop application.
-
Makes it easy to install and use fava and beancount.
-
Simple installation using flatpak, no messing in the commandline - a convenient way to open and edit beancount files as in any other desktop application.
-
Built using GTK and webkit, packaged as flatpak application.
The easiest way to start using Fava GTK is to download and install the flatpak application package from the Fava GTK releases on Github, as detailed in the following.
Fava GTK has been developed and tested on Linux with GNOME 3.38. Other operating systems and desktop environments may or may not work. flatpak is needed to install and run the flatpak package.
Download a .flatpak file from one of Fava GTK's releases on github.
You can then install the application as follows.
flatpak install --user <file.flatpak>Once installed, you will find an application named "Fava" that can be started in the very same way as any other desktop application, e.g., using GNOME Shell.
The application window that is initially shown prompts to open a beancount file. If you don't have a beancount file yet, you can simply create an empty text file with a .beancount extension. Opening the beancount file will display fava's user interface, allowing to view and edit the beancount file.
Fava GTK is only a thin convenience layer around Fava and Beancount. These two programs provide the actual functionality. You will find documentation on how to use these programs for managing your finances on their respective websites.
All contributions are greatly appreciated... pull requests welcome, and so are bug reports and suggestions for improvement.
Starting Fava GTK from the commandline allows to view its debug output and helps understand what is going on "under the hood". This can be useful to analyze a problem prior to reporting a bug.
flatpak run io.github.beancount.FavaGtkFava GTK is written as a python application using the GTK user interface toolkit and targeting the GNOME desktop environment. The following requirements are needed to develop and run Fava GTK straight from its python source code.
System requirements - a modern GNOME installation will usually come with everything you need:
- python3 is needed, no support for python2. See setup.cfg for the specific version of python that is required.
- PyGObject is needed because it provides language bindings to GTK. If you are running GNOME you most certainly have it on your system already. Have a look at PyGObject's installation instructions and choose (or try out to see) if you want to install PyGObject using pip or using your operating system's package manager.
- WebKitGTK must be installed, specifically WebKit2 API Level4. If you are running GNOME, you probably have it on your system already.
- Optionally Glade in order to edit .ui files.
Python package dependencies:
-
Fava GTK depends on other python packages, as defined in the
requirements/*.infiles. Fava GTK aims for compatibility with the dependency versions defined in these files. -
Version-locked aka "frozen" requirement definitions can be found in the
requirements/*.txtfiles. These files are created automatically using pip-compile-multi. The version-locked requirements allow to create reproduceable development environments and package builds.
The Makefile provides commands that make it easy to set up a python virtual environment for developing Fava GTK.
# Run this command to create a python virtual environment for Fava GTK.
# PyGObject is used from your system-wide installation.
# All other dependencies are installed using locked version numbers in the virtualenv.
# Fava GTK is installed in the virtualenv in editable mode.
make venv
# To start Fava GTK using your virtual environment:
make run- Minor Upgrades within the constraints of
requirements/*.in: Simply runpip-compile-multi. This will lock packages to their newest version, within the given constraints. - Major Upgrades: Manually check if some of the packages in
requirements/*.inexist in a newer version.
Use pre-commit to lint the code before committing changes.
# to install pre-commit on your system,
# follow instructions from https://pre-commit.com/, for example:
pip install pre-commit # install pre-commit using pip
# to install the pre-commit git hooks in the cloned fava-gtk repo
pre-commit install # activates pre-commit in the current git repo
# to lint all code
pre-commit run --all
# to lint staged changes
pre-commit runFava GTK is packaged using flatpak-builder. The following software is needed to build flatpak application packages.
- flatpak-builder (installed using instructions from https://docs.flatpak.org/en/latest/first-build.html)
- appstream (provides the appstreamcli command, which is used to validate the appstream xml file)
- desktop-file-utils (provides the desktop-file-validate command, which is used to validate the desktop file)
Have a look at the targets available in the flatpak packaging Makefile. These targets build, install and launch the Fava GTK .flatpak application package. For example:
# to create a flatpak bundle
make distHow to release a new version of Fava GKT
- Test the flatpak image, a quick smoke test should suffice to verify that the build is working ok.
- Edit the version number in
setup.cfgto match the version that shall be released, git commit and push. Format the version number as, e.g.,1.2.3. - Tag the same version number, prefixed with letter
v, e.g.,v1.2.3, then rungit push --tags - Github's ci should build the flatpak package and upload it to a release with the same name.
- Edit the release notes on the github releases page, and paste the same release notes into the CHANGES file.
- Optionally set a next development version number in setup.cfg, e.g.,
1.2.4-dev, push changes.
fava-gtk is MIT licensed, see LICENSE file.
Most of fava-gtk's functionality comes from other software packages; many thanks in particular to the authors of of Fava and Beancount. fava-gtk's dependencies are licensed differently, see the requirements definitions in this repo for lists of packages that fava-gtk depends on.