Gaphor on Linux#

Gaphor can be installed as Flatpak and AppImage on Linux, some distributions provide packages. Check out the Gaphor download page for details.

Older releases are available from GitHub.

CI builds are also available.

Development Environment#

There are two ways to set up a development environment:

GNOME Builder, ideal for “drive by” contributions.
A local environment.

GNOME Builder#

Open GNOME Builder 43 or newer, clone the repository. Check if the Build Profile is set to org.gaphor.Gaphor.json. If so, hit the Run button to start the application.

A Local Environment#

To set up a development environment with Linux, you first need a fairly new Linux distribution version. For example, the latest Ubuntu LTS or newer, Arch, Debian Testing, SUSE Tumbleweed, or similar. Gaphor depends on newer versions of GTK, and we don’t test for backwards compatibility. You will also need the latest stable version of Python. In order to get the latest stable version without interfering with your system-wide Python version, we recommend that you install pyenv.

Install the pyenv prerequisites first, and then install pyenv:

curl https://pyenv.run | bash

Make sure you follow the instruction at the end of the installation script to install the commands in your shell’s rc file. Next install the latest version of Python by executing:

pyenv install 3.x.x

Where 3.x.x is replaced by the latest stable version of Python (pyenv should let you tab-complete available versions).

Next install the Gaphor prerequisites by installing the gobject introspection and cairo build dependencies, for example, in Ubuntu execute:

sudo apt-get install -y python3-dev python3-gi python3-gi-cairo
gir1.2-gtk-4.0 libgirepository1.0-dev libcairo2-dev libgtksourceview-5-dev

Install Poetry using pipx:

pipx install poetry

Clone the repository.

cd gaphor
# activate latest python for this project
pyenv local 3.x.x # 3.x.x is the version you installed earlier
poetry env use 3.x # ensures poetry /consistently/ uses latest major release
poetry config virtualenvs.in-project true
poetry install
poetry run gaphor

NOTE: Gaphor requires GTK 4. It works best with GTK >=4.8 and libadwaita >=1.2.

Create a Flatpak Package#

The main method that Gaphor is packaged for Linux is with a Flatpak package. Flatpak is a software utility for software deployment and package management for Linux. It offer a sandbox environment in which users can run application software in isolation from the rest of the system.

We distribute the official Flatpak using Flathub, and building of the image is done at the Gaphor Flathub repository.

Install Flatpak
Install flatpak-builder
```
sudo apt-get install flatpak-builder
```

Install the GNOME SDK

flatpak install flathub org.gnome.Sdk 43

Clone the Flathub repository and install the necessary SDK:

git clone https://github.com/flathub/org.gaphor.Gaphor.git
cd org.gaphor.Gaphor
make setup

Build Gaphor Flatpak
```
make
```
Install the Flatpak
```
make install
```

Create an AppImage Package#

AppImage is a format for distributing portable software on Linux without needing superuser permissions to install the application. The AppImage file is one executable which contains both Gaphor and Python. It allows Gaphor to be run on any AppImage supported platform without installation or root access.

We build our AppImage by first bundling Gaphor with PyInstaller and then converting it in to an AppImage.

In order for the built AppImage to be compatible with older versions of Linux, we build the release versions using Docker with an older LTS version of Ubuntu.

poetry run poe package
cd _packaging/appimage
make dist

Linux Distribution Packages#

Examples of Gaphor and Gaphas RPM spec files can be found in PLD Linux repository:

https://github.com/pld-linux/python-gaphas
https://github.com/pld-linux/gaphor

There is also an Arch User Repository (AUR) for Gaphor available for Arch users.

Please, do not hesitate to contact us if you need help to create a Linux package for Gaphor or Gaphas.