Gaphor on Linux¶

Gaphor can be installed as Flatpak 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

Next, clone the repository, after which you need to execute the following consecutive commands:

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 install
poetry run pre-commit install

Now, you can run gaphor as

poetry run gaphor

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

Debugging using Visual Studio Code¶

Before you start debugging you’ll need to open Gaphor in vscode (the folder containing pyproject.toml). You’ll need to have the Python extension installed.

Create a file .vscode/launch.json with the following content:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Gaphor UI",
            "type": "python",
            "request": "launch",
            "module": "gaphor",
            "justMyCode": false,
            "env": {
                "GDK_BACKEND": "wayland"
            }
        }
    ]
}

GDK_BACKEND is added since VSCode by default uses XWayland (the X11 emulator).

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 offers 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
```

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.