Gaphor on Windows

Development Environment

Choco

We recommend using Chocolately as a package manager in Windows.

To install it, open PowerShell as an administrator, then execute:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

To run local scripts in follow-on steps, also execute Set-ExecutionPolicy RemoteSigned. This allows for local PowerShell scripts to run without signing, but still requires signing for remote scripts.

Git

To setup a development environment in Windows first install Git by executing as an adminstrator:

choco install git

MSYS2

Both of the development environments in the next steps need MSYS2 installed.

Install MSYS2:

Keep PowerShell open as administrator and execute:

choco install msys2

GTK and Python with gvsbuild (recommended)

gvsbuild provides a Python script helps you build the GTK library stack for Windows using Visual Studio. By compiling GTK with Visual Studio, we can then use a standard Python development environment in Windows.

Note: gvsbuild says it requires msys2, but does it for our needs?

First we will install the gvsbuild dependencies:

Visual C++ build tools workload for Visual Studio 2019 Build Tools
Python

Install Visual Studio 2019

With your admin PowerShell terminal:

choco install visualstudio2019-workload-vctools

Install the Latest Python

Download and install the latest version of Python:

Install from Chocolately with choco install python with admin PowerShell
Restart your PowerShell terminal as a normal user and check that python --version is correct.

Install gvsbuild

We have forked gvsbuild for now because gaphor has slightly newer dependency requirements than the upstream project. If we can get our changes upstream, then we’ll switch back to using that version directly.

Open a new regular user PowerShell terminal and execute:

mkdir C:\gtk-build\github
cd C:\gtk-build\github
git clone https://github.com/gaphor/gvsbuild.git

Build GTK

In the same PowerShell terminal, execute:

cd C:\gtk-build\github\gvsbuild
python .\build.py build -p=x64 --vs-ver=16 --msys-dir=C:\tools\msys64 --enable-gi --py-wheel --gtk3-ver=3.24 gobject-introspection gtk3 pycairo pygobject adwaita-icon-theme hicolor-icon-theme

Grab a coffee, the build will take a few minutes to complete.

Setup Gaphor

In the same PowerShell terminal, clone the repository:

cd (to the location you want to put Gaphor)
git clone https://github.com/gaphor/gaphor.git

Install Poetry (you may want to consider installing poetry via pipx, instead of pip):

PS > pip install --user poetry
PS > poetry config virtualenvs.in-project true

Install PyGObject and pycairo from gvsbuild

PS > Get-ChildItem C:\gtk-build\build\x64\release\*\dist\*.whl | ForEach-Object -process { poetry run pip install $_ }

Install Gaphor’s other dependencies

PS > poetry install

Add GTK to your path:

$env:Path = "C:\gtk-build\gtk\x64\release\bin;" + $env:Path

Launch Gaphor!

PS > poetry run gaphor

GTK and Python with MSYS2 (alternative method)

MSYS2 provides a bash terminal, with Python and GTK compiled against GCC. This is an alternative method to using gvsbuild above. The advantage is that you get a full bash environment in Windows, the disadvantage is that Python is very heavily patched to be built this way and often breaks.

Run C:\tools\msys64\mingw64.exe - the MINGW64 terminal window should pop up

$ pacman -Suy
$ pacman -S mingw-w64-x86_64-gcc \
    mingw-w64-x86_64-gtk3 \
    mingw-w64-x86_64-gtksourceview4 \
    mingw-w64-x86_64-pkgconf \
    mingw-w64-x86_64-cairo \
    mingw-w64-x86_64-gobject-introspection \
    mingw-w64-x86_64-python \
    mingw-w64-x86_64-python-pip \
    mingw-w64-x86_64-python-setuptools
$ echo 'export PATH="/c/Program Files/Git/bin:$PATH"' >> ~/.bash_profile

Restart the MINGW64 terminal.

Clone the repository.

Create and activate a virtual environment in which Gaphor can be installed:

$ cd gaphor
$ python3.9 -m venv .venv
$ source .venv/bin/activate

Install and configure Poetry:

$ pip install poetry wheel
$ poetry config virtualenvs.create false

Install Gaphor and give it a try:

$ poetry install
$ poetry run gaphor

Debugging using Visual Studio Code

Start a new PowerShell terminal, and set current directory to the project folder:

PS > cd (to the location you put gaphor)

Ensure that path environment variable is set:

PS > $env:Path = "C:\gtk-build\gtk\x64\release\bin;" + $env:Path

Start Visual Studio Code:

PS > code .

To start the debugger, execute the following steps:

Open __main__.py file from gaphor folder
Add a breakpoint on line main(sys.argv)
In the menu, select Run → Start debugging
Choose Select module from the list
Enter gaphor as module name

Visual Studio Code will start the application in debug mode, and will stop at main.

Packaging for Windows

In order to create an exe installation package for Windows, we utilize PyInstaller which analyzes Gaphor to find all the dependencies and bundle them in to a single folder. We then use a custom bash script that creates a Windows installer using NSIS and a portable installer using 7-Zip.

Follow the instructions for settings up a development environment above
Run C:\tools\msys64\mingw64.exe - a terminal window should pop up

$ source .venv/bin/activate
$ mingw32-make dist
$ cd packaging
$ mingw32-make all
$ cd windows
$ mingw32-make all