dtool-lookup-gui

dtool-lookup-gui is a graphical user interface for dtool, dtool-lookup-server and dtool-lookup-server-dependency-graph-plugin written in Python and GTK.

Quick start

Just download the pre-packaged binaries of the latest release.

If the binaries won't run out-of-the-box on your system, continue below.

OS-specific notes

macOS

After downloading the dmg Apple Disk Image of the latest release and copying dtool-lookup-gui over to your Applications folder, macOS will likely complain about dtool-lookup-gui being damaged and refuse to execute it. This is due to the fact that we are no Apple-verified developers. To run the app anyway, open a terminal and remove Apple's quarantine attribute from the app with

sudo xattr -rds com.apple.quarantine /Applications/dtool-lookup-gui.app

That should enable you to launch the app as usual. Another option is to call

/Applications/dtool-lookup-gui.app/Contents/MacOS/dtool-lookup-gui

directly from the command line.

Linux

After downloading and extracting the tar.gz-packaged Linux build, you may run the bundled scripts set_launcher_icon.sh and soft_link_launcher.sh subsequently to add this launcher icon to your desktop environment:

This has been tested on Ubuntu 20.04 and GNOME 3.36.8.

The packaged Linux build will fail to launch out-of-the box under Wayland. If unsure whih display server is in use, check with

echo $XDG_SESSION_TYPE

This will likely output either x11 or wayland. If you are using Wayland, launch the app with environment variable GDK_BACKEND=x11 set, e.g. via

GDK_BACKEND=x11 ./dtool_lookup_gui

Development

Please read the contributing guidelines before diving into the development process.

Requirements

This application requires Gtk 3 and GtkSourceView 4.

On Ubuntu (20.04),

apt install -y gir1.2-gtksource-4

suffices to to install these dependencies from the standard system package repositories.

On recent macOS (>= 10.15) use homebrew,

brew install gtksourceview4 gnome-icon-theme

On earlie macOs, MacPorts allows the installation of gtksourceview4

sudo port -v selfupdate
sudo port install xorg-server
sudo port install gtksourceview4 py-gobject3 py-pip py-numpy py-scipy
sudo port install adwaita-icon-theme

sudo port select --set python python310
sudo port select --set pip pip310

mkdir -p ~/venv
python -m venv --system-site-packages ~/venv/python-3.10
source ~/venv/python-3.10/bin/activate

pip install --upgrade pip
pip install wheel
pip install dtool-lookup-gui dtool-s3 dtool-smb

This has been tested on macOS 10.13.6.

On Windows, use mingw64/msys2 and refer to the Using GTK from MSYS2 packages on the GTK project's pages.

Also refer to the build workflows .github/workflows/build-on-[linux|macos|windows].yml within this repository for understanding the requirements for the different systems.

Installation

For a locally editable install, clone this repository with

git clone git+https://github.com/livMatS/dtool-lookup-gui.git

change into the repository directory,

cd dtool-lookup-gui

create and activate a clean virtual environment,

python -m venv venv
source venv/bin/activate
pip install --upgrade pip

and perform an editable install with

pip install -e .

Also run

glib-compile-schemas .

from within subdirectory dtool_lookup_gui. Otherwise, GUI launch fails with

gi.repository.GLib.Error: g-file-error-quark: Failed to open file “/path/to/repository/dtool_lookup_gui/gschemas.compiled”: open() failed: No such file or directory (4)

Running the GUI

After installation, run the GUI with:

python -m dtool_lookup_gui

Note that when you run the GUI for the first time, you will need to configure the URL of the lookup and the authentication server as well as provide a username and a password. To do this, click on the "Burger" symbol and select Settings.

Pinned requirements

requirements.in contains unpinned dependencies. requirements.txt with pinned versions has been auto-generated with

pip install pip-tools
pip-compile --resolver=backtracking requirements.in > requirements.txt

GTK debugging

After

gsettings set org.gtk.Settings.Debug enable-inspector-keybinding true

use CTRL-SHIFT-D during execution to display the GTK inspector for interactive debugging.

GUI design

The GUI uses custom Gtk widgets. To edit the the XML UI definition files with Glade, add the directory glade/catalog to Extra Catalog & Template paths within Glade's preferences dialog.

Running unit tests

Running the unit tests requires pytest and pytest-asyncio. Then, run all tests from repository root with pytest.

Funding

This development has received funding from the Deutsche Forschungsgemeinschaft within the Cluster of Excellence livMatS.