Building and Running

Downloading

Forking

First, you'll need to download the repository by cloning it with git.

If you're planning on making a contribution, you'll need to fork the repo.

If you're not sure how to fork or maintain a repo, take a look at GitHub's fork a repo page. It'll show you how to fork, download your fork, set our repo as the upstream (original) branch and keep your fork up to date with our repo.

Note: If you're only interested in trying out the latest changes, just git clone the repo.

Dependencies

Once you've done that, download these dependencies:

libgee-0.8-dev
libcairo2-dev
libjson-glib-dev
libgdk-pixbuf2.0-dev
libwnck-3-dev
libgtksourceview-3.0-dev
libjson-glib-dev
meson
valac

Building and running

First time configuring

Next, you'll need to configure the build environment.

meson build
cd build
meson configure -D prefix=/usr

This configures the build environment in the build directory and navigates inside it.

Build, install and run the app with debug messages

Finally, install and run Desktop Folder. Using env G_MESSAGES_DEBUG=all enables the output of debug messages.

sudo ninja install && env G_MESSAGES_DEBUG=all com.github.spheras.desktopfolder

If you're translating, you can stop here! Follow the rest of the instructions at Translating.

Running with a debugger

A debugger can be really useful for locating the source of crashes and bugs.

It can also be useful for just understanding what the program does in an interactive step-by-step environment.

Configure the build environment

To get the most out of the debugger, you'll want to enable including debug information (e.g. variables) with the build. To do this, we're going to create a separate build directory.

Go to the root directory of the repository, and configure the build environment as before, except in the debug directory:

meson debug
cd debug
meson configure -D prefix=/usr

This configures the debug build environment in the debug directory and navigates inside it.

Then, add the debug arguments:

meson configure -D vala_args=-g
meson configure -D c_args=-g

Next, we're going to set up a debugging GUI.

perf

If you want to use perf run this as well:

meson configure -D c_args="-g -fno-omit-frame-pointer"

See this for information on how to use perf.

Installing a debugger

gdbgui (recommended)

gdbgui is a debugger that runs in the browser.

Installing gdbgui

sudo pip install gdbgui --upgrade

Using gdbgui

Once you've installed gdbgui, run it with the Desktop Folder binary as an argument:

gdbgui com.github.spheras.desktopfolder

To enable debug messages, run set environment G_MESSAGES_DEBUG =all in gdbgui's console.

gdbgui will go to the main method of the app (it will not be running yet). This allows you to add breakpoints to the code before running the application. To open a source file, start typing the name of the source file you want to open in the source file search box (e.g. PhotoSettings) and select the .vala file when you see it. If you want to look through all the source files, just type in .vala and they will all be listed.

When you're ready, click the ↻ button at the top right (or press r) to start the application. At this point it will be loaded but paused. Either click ▶️ or ⬇ depending on what you want to do:

• The ▶️ button (Continue, or c key) runs the application until it reaches a breakpoint.
• The ⬇ arrow (Step, or s key) steps into the next function call. You will likely see machine instructions while using this, just continue stepping until you see the next part of the code (use breakpoints instead if you don't want to see the machine instructions).
• To restart the application from the beginning, press the ↻ button (or r key) at the top right again.

When you make a change to the code

If you make a change to the code, all you have to do is rebuild the app, kill the running process and reload the debugger:

• sudo ninja install
• Kill the running process (either by sending a SIGKILL inside gdbgui or running killall com.github.spheras.desktopfolder)
• Refresh the page with F5. Press Leave Page with Enter if it asks you to confirm.

Nemiver

Nemiver is GNOME's debugger GUI. Install Nemiver with sudo apt install nemiver.

You might also need glibc-source. Install with sudo apt install glibc-source.

Build, install and run the app with Nemiver

Once you have Nemiver installed and have configured the debug build directory, use this one-liner command (instead of the one above) to run Desktop Folder with the debugger:

sudo ninja install && env G_MESSAGES_DEBUG=all nemiver com.github.spheras.desktopfolder

Using Nemiver

Nemiver will pause the program just before it starts running. This allows you to add breakpoints to the code before running the application. To open a source file:

• Press Ctrl - O (or File -> "Open Source File..."
• Click "Select from File System"
• Go back one directory (click the tab before build)
• Go to the src/ folder
• Find and open the source file you want.

GTK Inspector

To enable the GTK Inspector on your elementary installation:

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

This enables the inspector for your whole system. You can disable this again by changing true to false at the end of the command.

To use the GTK Inspector:

• Make sure the window you want to debug is active.
• Put your mouse over the element you want to inspect and press Ctrl+Shift+I.