GNOME on pesader

Accessibility Hackathon

Tue, 23 Jul 2024 11:00:38 -0300

When you stop and think about it, user interfaces are almost entirely designed around sight: they display graphical elements that are mostly interacted with by pointing and clicking (or touching). However, as we know, not everyone has “perfect” vision: some are color blind, some are short sighted, some are long sighted, etc. In many cases, these people can still interact with the same user interfaces as everyone else, but those with more severe visual impairments need a different method to use their computers.

That’s when the Screen Reader comes in! The Screen Reader is a software that adapts computers to the needs of users with low vision or blindness, by reading descriptions of user interfaces out loud and facilitating keyboard navigation.

Today, we will explore the web with Orca, the Screen Reader of the Linux Desktop! After that, we will contribute towards improving the experience of Orca users.

Mind you that Screen Readers have tons of advanced features to empower users with as much efficiency as possible. Because of that, it can be challenging to use this kind of software if you are not used to it. I invite you to embrace this challenge as an opportunity to experience the desktop from a different perspective, and to appreciate the way other people user their computers.

Without further ado, let’s get going!

Enabling and Disabling Orca

You can enable and disable Orca by pressing Super + Alt + s. This can also be configured via GNOME Settings, under “Accessibility” > “Seeing” > “Screen Reader”.

Turn up and the volume and make sure you hear a robotic voice saying “Screen Reader on” and “Screen Reader off”. Then, open the Firefox web browser and check if Orca describes the current open tab. If it is quiet, try closing and re-opening Firefox again or disabling and re-enabling Orca.

Controlling Orca

Orca is controlled entirely from the keyboard, having dozens of shortcuts. Besides, these keyboard shortcuts are slightly different if you have a Number Pad (NumPad) or not. I have laid out the most important ones below, but an exhaustive list can be found in the quite excellent Orca documentation.

Orca Modifier

Key	Without a NumPad (Laptop)	With a NumPad (Desktop)
`Orca Modifier`	`Caps Lock`	`NumPad Ins`

Important shortcuts

Action	Without a NumPad	With a NumPad
Toggle screen reader	`Super` + `Alt` + `s`	`Super` + `Alt` + `s`
Interrupt screen reading	`Orca Modifier` (press)	`Orca Modifier` (press)
Toggle caret mode in Firefox	`F7`	`F7`
Where am I	`NumPad Enter`	`Orca Modifier` + `Enter`
Display page structure	`Alt` + `Shift` + `h`	`Alt` + `Shift` + `h`
Display page buttons	`Alt` + `Shift` + `b`	`Alt` + `Shift` + `b`
Read current line	`NumPad 8`	`Orca Modifier` + `i`
Read current word	`NumPad 5`	`Orca Modifier` + `k`
Read onward	`NumPad +`	`Orca Modifier` + `;`
Next link	`k`	`k`
Previous link	`Shift` + `k`	`Shift` + `k`
Next paragraph	`p`	`p`
Previous paragraph	`Shift` + `p`	`Shift` + `p`
Next button	`p`	`p`
Previous paragraph	`Shift` + `p`	`Shift` + `p`

Activity: Exploring the web with Orca

Open the Firefox web browser and head to https://flathub.org. Find an app that looks interesting to you and explore its page using Orca. Try to navigate the entire page!

Feel free to use the questions below as a guide to your exploration:

Can you read the app description? Try to do it twice.
Can you click the “Install” button? What happens when you do?
Can you figure out if the app is verified or not? How so?
Can you guess what the screenshots of the app are showing?
Can you find the link to the source code of the app?

Part II - Captioning Screenshots in Flathub

Flatpak and Flathub

Flatpak is a modern packaging technology, which aims to work on all Linux distributions. In turn, Flathub is an app store for software that was packaged using Flatpak. Flathub has been embraced as the main channel for publishing applications by many projects, most notably GNOME!

App listings

Each app that is published on Flathub has a page for itself, which is called “app listing”. You will find lots of important information about an app on its listing, such as:

Name
Description
Author
License
Permissions
Screenshots

All this information is sourced from a special file called “MetaInfo File”, that is typically hosted on the app’s repository. Its filename usually ends with .metainfo.xml.in.in. You can click here to see an example of a MetaInfo File. You can read more about this file format on Flathub’s MetaInfo Guidelines.

Screenshot captions

To promote high-quality listings, Flathub publishes its own Quality Guidelines.. These guidelines encourage maintainer’s to add captions to their images, which, as we learned in the first activity, helps people who use Screen Readers understand the content of the screenshots of the app. To quote the Quality Guidelines:

Every screenshot should have a caption briefly describing it. Captions should only be one sentence and not end with a full stop. Don’t start them with a number.

To be more precise, good captions should clearly convey the functionality demonstrated in the screenshot, as well as give a general idea of the user interface on display. I have cataloged dozens of Flathub listings on this Google Sheet:

GUADEC 2024 - Accessibility Hackathon

There you find listings with Caption status set “Exemplary”, which are great models of how captions should be written.

Activity: Contributing with captions

Now, we will improve the accessibility of the Linux Desktop (albeit slightly), by contributing to Flathub with screenshot captioning. To do that, follow the instructions laid out below:

Open the Google Sheet on this link
Choose an app with Caption status set “Absent”
Assign “In-progress” to its Caption status
Put your name(s) on its Group column
Head to the Flathub listing link of the app
Find the repository of the app (usually under “Browser the source code” on “Links”)
Log in or create an account on the platform that hosts the repository of the app (GitHub, GitLab, etc)
Go back to the repository of the app, and find its MetaInfo File. It is typically placed in a data/ directory, at the root of the repository.
On the MetaInfo File, look for the screenshot tags and find the files referenced in it
Inside each screenshot element, there is an image element. For each of those, create a new line with caption tags. The caption goes in between them, like so:

<screenshot>
 <image>https://raw.githubusercontent.com/SeaDve/Kooha/main/data/screenshots/screenshot2.png</image>
+ <caption>In-progress recording duration and button to stop recording</caption>
</screenshot>

When you are done writing your captions, proof read them and run them through a spellchecker. I haven’t found any great ones online, but Language Tool’s is passable.
Commit your changes, following the commit message conventions of the project you are contributing to. If this convention is not documented anywhere, try to infer it looking at the commit history.
Open a Pull Request (PR) / Merge Request (MR) with your contribution, explaining what you did and why it is important. You can use my explanation as a model.
Put a link to your PR/MR on the sheet.
Wait for the maintainer’s feedback

Part III: Farewell

Thank you for attending this workshop. I hope you had a good time!

Until the next one!

GUADEC 2023

Tue, 01 Aug 2023 19:15:26 -0300

A few days back, I went for the first time to the GNOME Users and Developers Everywhere Conference (GUADEC). Even though I’m just a Google Summer of Code intern, the GNOME Foundation was kind enough to sponsor my trip to Riga, Latvia, where the event took place this year.

The city

After an 18h trip to Riga, I thought I would collapse on my hotel’s bed as soon as I stepped into my room. However, I was so incredibly overwhelmed by Riga’s unique beauty that I dropped all my stuff in the hotel as fast as I could, then left for a quick stroll.

My first destination ended up being the Saint Peter’s Chapel, and for good reason! It is the tallest building in the city and, since Riga is extraordinarily flat, you can see everything from up there. I arrived a few days before the conference but hadn’t made any plans, so I took the opportunity of the bird’s-eye-view to scan the whole city for interesting places to visit.

Here’s the problem: everything looks interesting in Riga. Take this building for example:

This beautiful, intricately detailed Art Noveau building would be a tourist attraction on its own was it placed on the streets of my motherland. If you take a closer look, you will realize that the sign on it reads “Eliza Kofisops”. “Kofisops”? Yeah, that’s right, this amazing building is nothing but an ordinary every-day-life coffee shop!

In spite of the choice paralysis, I ended up visiting lots of places. Some of the highlights were the Occupation Museum, the Fashion Museum, the National Library, and the suburbs waking tour.

The conference

Time flew as I was touristing through Riga and, before I knew, GUADEC 2023 was upon me!

The presentations

One of the best parts of attending GUADEC was seeing the impressive amount of ongoing work. Usually, the news only cover features and enhancements that are ready, so it was very exciting to get a glimpse of what the future holds for GNOME.

That is especially true of the work being done by the GNOME Design Team and GNOME Foundation. For that reason, some of my favorite talks were “GNOME Design: State of the Union” by the Design Team, and “Beyond the Code: Another side of GNOME” by Melissa Wu.

I also had a legit fun time with some of the lightning talks. Jussi Pakkanen’s analogy between geomtry problems and preferences was nothing short of brilliant and Tobias Bernard’s surprise lighting talk on GNOME’s logo was a bold hot take on branding.

If I were to cite every other talk I enjoyed I would probably end up listing the entire schedule of the conference so let’s just stick with this subset 😅.

The contributions

At my very first GUADEC I already had the honor to present a few things! It was a bit unnerving to speak in front of such a distinguished audience, but the excitement prevailed over every other feeling.

On the second day, I presented a Lightning Talk on “How to make a FOSS contribution event” in which I talked about the work I do at LKCAMP, the FOSS student club that I participate in.

On the third day, I presented yet another Lightning Talk. This time I spoke about my work as a Google Summmer of Code intern, on “Integrating the functionality of GNOME Network Displays into GNOME Shell”.

Finally, in the last day, I held a workshop for first time contributors. Most attendees, however, were not anywhere near “first time contributors”. For that reason, I ended up changing up the structure of the event a bit and focus a bit more on my method (or rather, LKCAMP’s method) for making events to enlist new contributors to open source.

The afterword

Again, I would like to express my gratitude towards the GNOME Foundation for making this trip possible. I had an amazing time getting meeting the faces behind the usernames that I had been interacting with for years, and none of that would have been possible without the Foundation’s support.

More speficially, I would to thank Melissa Wu for patiently and diligently answering all my questions regarding the trip and Asmit Malakannawar for providing me with the documents (e.g. invitation letter) needed to facilitate my immigration into Latvia.

Hope to see you again in Denver for GUADEC 2024!

1st Contribution Hackathon, by LKCAMP

Sat, 29 Jul 2023 09:46:26 +0300

The 1^st Contribution Hackathon was created by LKCAMP, the Free and Open Source Software study group of the Universidade Estadual de Campinas (Unicamp) that I have been a member of for years. Over time, we have made many iterations of this event in our university and even took it to the GUADEC (GNOME’s global conference) in 2023.

That being said, thank you for coming to this edition of the 1^st Contribution Hackathon! We welcome you into our history. Now, buckle up!

Resources

You can access a page with links to all the resources you’ll need to participate in this event by clicking here. Open it and pin that tab in web browser for the entire duration of the event!

Setup

There are three components that we need for making the contribution: flatpak, flathub, and GNOME Builder. Here’s how to get each of them:

Flatpak

Flatpak is a packaging format for graphical applications that works on any GNU/Linux distribution. It is the most widely embraced packaging format for GNOME applications. To get flatpak on your distro of choice, run:

Ubuntu:

 sudo apt install flatpak

Arch:

 sudo pacman -S flatpak

Fedora:

 # already installed

Flathub

Flathub is an app store for the flatpak packaging format. It’s one of the biggest software catalogs in the Linux world! You can get it on your computer by running:

flatpak remote-add --user --if-not-exists flathub \
 https://flathub.org/repo/flathub.flatpakrepo

GNOME Builder

Finally, GNOME Builder is an integrated development environment (IDE) for developing applications in the GNOME ecosystem. Install it with:

flatpak install org.gnome.Builder

And you’re all set!

What is GNOME?

GNOME is a software platform. That means GNOME provides an integrated stack for software development, distribution, and consumption.

An important part of this ecosystem are the GNOME apps, to which we’ll contribute in this event! These apps are built with GTK, using GNOME Human Interface Guidelines (HIG).

What is GTK?

GTK is a fundamental building block for the applications that belong in the GNOME software platform. In programmer’s lingo, GTK is an object oriented widgets-based framework for developing graphical applications. Now let’s break that down in plain English:

Object oriented:

Object Oriented Programming is a programming paradigm that seeks to improve code organization, reduce code duplication, among many other things. Object Oriented Programming is very “concept heavy”, so teaching everything about it is out of scope for this event. Still, we hope to spark your curiosity enough for you to look it up on your own later :)

Widgets-based:

In GTK, every graphical element is a “widget”. These widgets are organized hierarchically, for example Window → Header bar → Menu button. Here are some of the widgets and their names, in the wonderful Frog application:

Widgets’ behavior and appearance can be configured with a programming language (C, Python, Rust, JavaScript, Vala, etc) and/or a markup language (XML, Blueprint, etc).

Graphical applications:

Graphical applications are applications that show a window to the user. Some applications are not graphical, for example, that ones that run directly on the terminal.

Access Keys

What?

GTK has a feature called Access Keys (also known as “mnemonics”). Here’s how it works:

Hold the Alt key until some characters are underlined
Press an underlined characters while you hold Alt
The action associated with that widget will be triggered

Why?

Access Keys are an important for two use cases:

Offering a keyboard-centric workflow for power users
Improving the accessibility of the GNU/Linux desktop

How?

To implement an Access Key for a widget within a application, you need to prepend an underline (_) to whichever character you want to highlighted when the user hold the Alt key. For example, to highlight the C in button whose label is "Continue", go with "_Continue".

Then, activate the Access Key feature for that widget. To do that you need to set the property “user-underline” to True.

This can sometimes be done with programming or markup languages. For programming languages, you’ll find some examples in the official documentation. Luckly for you, we have also made some additional examples, which you can checkout in the Projects Sheet. Here are some highlights:

Example in XML

Contribution by Gustavo Pechta to the app “Komikku” (link).

Example in Python

Contribution by Tárik Sá to the app “What IP” (link).

Example in Javascript

Contribution by Pedro Sader Azevedo to the extension “Space Bar” (link).

GNOME Human Interface Guidelines

Now you might asking yourself: How to I decide which widgets to add mnemonics to? Which characters should I choose to underline?

The answer to all these questions (and plenty more) lie in the GNOME Human Interface Guidelines (HIG). This document describes, in a very detailed manner, directives for building graphical user interfaces that comply with the design standards of GNOME.

The HIG contains a section on Access Keys, that you should read thoroughly (it’s very short). When you’re back, here’s summary on how to implement Access Keys in GNOME apps:

As many as you can
Prioritize most used widgets
Prefer the first letter
Avoid thin letters (i)
Avoid ambiguous letters (I, l)
Avoid letters with descenders (g, y, q)
Avoid vowels (a, e, i, o, u)

Tip: view switchers are usually good candidates for Access Keys! They can often be found in preferences screens and look like this:

Git

The most popular version control system is git. We’ll need to use its command line interface (CLI) to make our contribution but, unfortunately, git is a very complex and convoluted tool. Teaching all about it would take a very long (probably a workshop of its own). If want a deeper introduction to the concepts of git you can read “The tip of the git iceberg”, by yours truly 😉.

That being said, we’ll only give you what you need for this workshop:

Download the source code of the application

git clone https://...

Create a new branch for your contribution

git checkout -b add-access-keys

See commit history to check for conventions

git log

Create a new version of the application

git commit

Send your branch to your GitHub/GitLab account

git push origin add-access-keys

Warning: We’ll contribute to projects that are hosted on GitHub and GitLab. Although there’s only link for GitHub (github.com), there are multiple links to GitLab (gitlab.com, gitlab.gnome.org, etc). Make sure you create your account using the same GitLab link as your chosen project is hosted at.

After you’ve pushed your changes to your GitHub/GitLab account, you have to request that the maintainers of the project accept your contribution. This is known as a “merge request” (MR) or a “pull request” (PR).

When either of these git platforms detect a git push coming from you, they will offer you to create an MR/PR. Accept the offer and write a detailed description of what your contribution does. Again, you can check the examples in the Project Sheet.

Hackathon

Finally, you’re all set! Follow the steps below to make your first code contribution to GNOME and don’t hesitate to ask any questions.

Open the page of links and pin that tab in your browser
Pick a project and write down your name in the sheet
Find the project’s repository in its Flathub page
Install it and check if still doesn’t have Access Keys
Create an account and access token at GitHub/GitLab
Fork the the project and clone your fork
Build once without any modifications
Implement the Access Keys following the HIG
Check the commit conventions
Commit, push, and make a PR/MR
Put the PR/MR link in the sheet
Wait for feedback and iterate

Attribution

This blog post is a slightly re-written translation of this blog post by LKCAMP, which was originally written in Brazilian Portuguese by myself and Tárik Sá.

Hello Planet GNOME!

Tue, 09 May 2023 17:10:50 -0300

Hi, everyone!

I’m Pedro Sader Azevedo, a Computer Engineering student at Universidade Estadual de Campinas (Unicamp) in Brazil. In the next few months I’ll be working as a Google Summer of Code (GSoC) intern to integrate the functionality of GNOME Network Displays into GNOME Settings, with the guidance of Felipe Borges, Claudio Wunder, Jonas Ådahl, and Anupam Kumar.

More about me

During the pandemic, when every aspect of life was moved to the digital realm, I learned about Free Software and was won over by its principled stance on technology. I decided to take back my computing and became a user (and vocal advocate) of GNU/Linux!

Soon after, I helped organize The Week of Computing at my university. I invited a representative of GNOME (the one and only Georges Stavracas!), whose talk was especially impressive to me as I thoroughly identified with the values of freedom, collaboration, and inclusivity embodied by the project.

I started contributing with translations (which I still do a lot!) and was so warmly welcomed that I soon started programming as well. I also contribute with community-engagement, by helping the Free and Open Source Software study group LKCAMP organize events that promote usage of and contribution to FOSS projects.

More about my internship

The goal of the internship is to the add networks displays (i.e. “screen casting”) to GNOME Settigs. I plan to do that by separating the backend of GNOME Network Displays into a library, then using that library to implement the new feature on the settings app.

This change will contribute to the general impression of using a “first-class” operating system that seamlessly integrates with others. While it is true that the app already provides said feature, finding it directly in Settings is much more reassuring and convenient than having to install a separate program just for that.

If there’s anything you’d like to discuss, feel free to reach out to me using any of the communication plaforms listed here (I’m most active on Matrix though).

Thank you for reading!

Making 4 GNOME Shell extensions compatible with GNOME 44

Mon, 08 May 2023 19:14:37 -0300

I absolutely love extensions, in general. I remember being blown away every time I found a notably extensible software, from Firefox add-ons in my early days of surfing the web to Neovim plugins in my latest coding endeavors.

This is why, once I started using GNU/Linux, I was amazed by GNOME Shell extensions. Being able to customize the appearance and behavior of my desktop environment as easily as used to with VS Code extensions was unimaginable coming from Windows and I loved every bit of it.

Since then, I’ve been a GNOME Shell extension fanatic and only upgraded my workstation when all extensions were made compatible with the latest version of GNOME. The addition of an upgrade assistant to Extension Manager made the wait easier, though not shorter.

Now that my current distro of choice (Fedora Silverblue) allows upgrading early and safely, I decided to do something different: upgrade right away and contribute to the extensions with GNOME 44 support!

These were the extensions I chose to contribute with:

ddterm

A drop down terminal extension for GNOME Shell. With tabs. Works on Wayland natively. I use it every day as my music player, with ncspot.

Focus changer

Change focus between windows in all directions, using vim-like mappings (Super + h, j, k, l). Can’t beat that muscle memory!

Focused Window dbus

Exposes a dbus method to get active window title and class. Required to get ActivityWatch working on mutter.

Reading Strip

Works as a reading guide for computer and this is really useful for people affected by dyslexia. Useful to avoid mixing up table rows and columns!

Here’s how that experiment went.

Upgrading to GNOME 44

As I said, version upgrades are safe and easy on Fedora Silverblue! All I had to do was pin my current deployment with:

sudo ostree admin pin 0

Then rebase to latest Fedora release:

rpm-ostree rebase fedora:fedora/38/x86_64/silverblue

Locating extension directories

With GNOME 44 installed on my machine, it was time to locate where the GNOME Shell extensions were installed. Extensions installed via EGO or Extension Manager are located at $HOME/.local/share/gnome-shell/extensions.

Each extension has a dedicated folder, whose name looks like extension-name@author.example.com.

Editing the `metadata.json` file

On each of these directories there’s a metadata.json, that includes a list called “shell-version” with the versions of GNOME supported by the extension. My first test was to simply add “44” to that list and see what happened, like so:

 "shell-version": [
 "40",
 "41",
 "42",
- "43"
+ "43",
+ "44"
 ],

Restarting the session

Wayland requires logging out to restart the session, so I logged out and logged in again.

Tweaking, if needed

To my surprise, three out of four extensions worked by simply changing the metadata.json file!

The Focused Window dbus extension loaded properly, but when I tried to actually call its dbus method I got an error saying that the canshade window property didn’t exist. Since that didn’t seem essential for the extension’s funcionality I removed the code related to that and tried again. This time, it worked perfectly!

Contributing

After using the extensions on GNOME 44 for a few days without any issues I decided to contribute to them. Some extensions a specific commit tag for changes made to metadata.json, so I made sure to use them in my contributions.

I think this a simple but valuable contribution, making it an excellent gateway into contributing to GNOME Extensions and FOSS projects in general. Give it a shot! 🧩❤️

Adding an RSS feed for GNOME-related posts

Mon, 08 May 2023 09:40:43 -0300

I recently got news that I was accepted as a Google Summer of Code (GSoC) contributor for the GNOME Project! I’ll work on integrating the functionality of GNOME Network Displays into GNOME Settings, and I’ll be reporting my progress publicly in this blog.

Before the contribution period starts, there’s a month-long Community Bonding Period. On GNOME, GSoC interns are asked to add an RSS feed of their blogs to Planet GNOME. For that purpose, I’ll show in this post how I added and configured an RSS feed for my Hugo-powered blog.

You are welcome to use my website’s theme if you want a blog with the same looks and functionality, but you can also uso this as a guide for implementing an RSS feed on your theme. Either way, I’ll assume you have a working Hugo theme you can build from as some knowledge about Hugo (taxonomies, page variables, config.toml options, etc).

1. Reference the RSS feed in `<head>`

Thankfully, Hugo has built-in support for RSS feeds! The first thing you need to do to use this feature in adding a reference to the RSS output format on the <head> tag of your blog, like so:

{{ with .OutputFormats.Get "RSS" -}}
{{ printf `<link rel="%s" type="%s" href="%s" title="%s">` .Rel .MediaType.Type .RelPermalink $.Site.Title | safeHTML }}
{{- end }}

It is a best-practice to define this tag in a file that you use as a base for all other files in your website (I do it in the baseof.html file).

2. Configure a baseName in `config.toml`

You should now add the following to the config.toml file of your website:

[outputFormats]
[outputFormats.RSS]
 mediaType = "application/rss+xml"
 baseName = "feed"

If you push these changes, you will have an RSS feed for any taxonomy (tags, categories, authors, etc) of your blog! To get the RSS .xml file, head over to the taxonomy list and append “/feed” to it. Take a look:

3. Override the default RSS template

You may find that the content of the RSS feed isn’t exactly what you hoped for. By default, Hugo only includes a summary (the first paragraph) in the feeds, but you probably the whole thing to be included in Planet GNOME! To fix that, you’ll need to write a custom rss.xml template. Luckly, you won’t have to start from the ground-up – let’s just copy Hugo’s default and start from there.

First, copy the contents of this file to layouts/_default/rss.xml. Then do the following change:

- <description>{{ .Summary | html }}</description>
+ <description>{{ .Content | html }}</description>

If you want to include only one section of content in your RSS feed, now’s the time to do that too. For instance, to include only “posts” you may do the following change:

- {{- if or $.IsHome $.IsSection -}}
- {{- $pages = $pctx.RegularPages -}}
- {{- else -}}
- {{- $pages = $pctx.Pages -}}
- {{- end -}}
+ {{- if or $.IsHome $.IsSection -}}
+ {{- $pages = (where (where $pctx.RegularPages ".Section" "posts") "Kind" "page") -}}
+ {{- else -}}
+ {{- $pages = (where (where $pctx.Pages ".Section" "posts") "Kind" "page") -}}
+ {{- end -}}

You can checkout the rss.xml for my website here.

4. Add custom markdown render hook

If you inspect the .xml file generated by Hugo at this point, it is possible that the paths for markdown images are wrong. This happens because it is common to use relative paths for including images in markdown, but the RSS feed doesn’t factor that in by default.

Gladly, Hugo allows tweaking the conversion of markdown to html with Markdown Render Hooks, which can be used to convert relative paths to absolute paths. If you store all images related to a blog post in its dedicated directory (like I do), all you need to do is create a file named render-image.rss.xml under the /layouts/_default/_markup/ directory and fill it with:

<p class="md__image">
 <img src="{{ printf "%s%s" .Page.Permalink .Destination | safeURL }}" alt="{{ .Text }}"/>
</p>

You can checkout the render-image.rss.xml for my website here.

5. Test the feed in an aggregator

You’re done! I recommend you try adding your blog to an RSS feed reader/aggregator, so you can make sure it works as intended. I like using NewsFlash for this, so here’s how you can do it there.

First, find the page in your blog that lists the content that you want to add to the feed. In my case, I want all posts tagged with GNOME to be included in Planet GNOME, so the link to the page that lists those is https://pesader.dev/tags/gnome:

Copy that link and add it to NewsFlash (appending /feed is optional):

And make sure it’s working (especially the images!):

That’s all for today, hope you learned something useful!

Sources

Safely building and running GNOME Settings with toolbx

Mon, 03 Apr 2023 18:20:51 -0300

Toolbx is a utility that empowers users and developers to install software on isolated environments, drastically reducing the risk of compromising the stability of their operating system. It is also indispensable for users of immutable distros (e.g. Fedora Silverblue, Endless OS, Vanilla OS, etc) like myself.

On this blog post I’ll share how I used toolbx to safely build and run GNOME Settings.

Step 0: backup all your settings

The isolation provided by toolbx only applies to system directories (those that you need sudo to make changes to). That means your $HOME directory is as vulnerable to mishaps as it is outside of the toolbx!

Since your preferences are stored within your $HOME directory make sure you back them up before meddling with an unstable version of the GNOME Settings app. To make the backup run:

dconf dump / > $HOME/preferences_backup.ini

Again, since your $HOME directory is not safer inside a toolbx, move that file somewhere else (e.g. a USB stick, a trusted cloud storage provider, etc). To restore the backup file, move it back to your $HOME directory and run:

dconf load -f / < $HOME/preferences_backup.ini

Step 1: choose the right toolbx image

To choose the operating system that will run on our toolbx, you need to pick its base image. To figure that out, take a look at the .gitlab-ci.yml:

.fedora.container.common:
 # ...
 tags: [ crun ]
 variables:
 # ...
 FDO_DISTRIBUTION_TAG: '2023-03-14.0-main'
 FDO_DISTRIBUTION_VERSION: rawhide

Looks like GNOME Settings is targetting Fedora Rawhide, which is a rolling build of Fedora that has the purpose of testing software for upcoming releases. That said, you can create your toolbx with the following command:

toolbox create gnome-control-center --image registry.fedoraproject.org/fedora-toolbox:rawhide

If you are doing this for the first time, this command will download the Fedora Rawhide toolbx image. It will take some time and some storage (500Mb) but don’t worry it’ll be worth it! Once the toolbx is created, enter it with:

toolbox enter gnome-control-center

Step 2: installing dependencies

To install the dependencies needed to build GNOME Settings, simply run:

sudo dnf builddep gnome-control-center

Step 3: building and running

Finally, head to the root of its repository and run:

make _build && ninja -C _build

This will build GNOME Settings at ./_build/shell/gnome-control-center.

Step 4: taking advantage of the isolation

To run the executable file, you can leave the toolbx and execute like so:

exit
./_build/shell/gnome-control-center

However, you may want to run it inside your toolbx! If that’s the case, you also have to install your local build of GNOME Settings. To do that, run:

ninja -C _build install

This will allow you to take advantage of the isolated environment provided by toolbx! For instance, when was writing this contribution to the applications panel, I wanted to test a few apps that I didn’t have (nor wanted to have) installed on my system. To address that, I installed a few applications inside my development toolbx! As you can see, the Settings app lists different applications when I open it from inside or from outside of the toolbx:

Outside toolbx	Inside toolbx

That’s all! Hope this was useful for you!

Credit

This post is a personal take on the GNOME Settings’ own guide on building with toolbx.

Entering the rabbit hole of GNOME Network Displays

Mon, 03 Apr 2023 15:34:02 -0300

In this blog post I’ll walk you through my journey of builiding and contributing to GNOME Network Displays, a standalone application for screencasting. Fasten your seatbelts, it’s gonna be a bumpy ride!

Building the application

First, I cloned the repository of the application and created a fresh Fedora Rawhide (currently labelled as 39) toolbx for this project. To do that I ran:

toolbox create gnome-network-displays --image registry.fedoraproject.org/fedora-toolbox:39

Following the build instructions on the README.md file I ran:

sudo dnf builddep gnome-network-displays
meson build
ninja -C build

But I got this error:

ninja: error: '/usr/lib64/libavahi-gobject.so', needed by 'src/gnome-network-displays', missing and no known rule to make it

That’s when one of my favorite dnf subcommands came into play: dnf provides tells you which package provides a given file path. So, to find out how to install the missing /usr/lib64/libavahi-gobject.so on my toolbx, I ran:

$ dnf provides /usr/lib64/libavahi-client.so
Fedora rawhide openh264 (From Cisco) - x86_64 426 B/s | 2.5 kB 00:05
Fedora - Rawhide - Developmental packages for the next Fedora release 4.3 MB/s | 66 MB 00:15
Fedora - Modular Rawhide - Developmental packages for the next Fedora release 351 kB/s | 1.6 MB 00:04
avahi-devel-0.8-20.fc38.x86_64 : Libraries and header files for avahi development
Repo : @System
Matched from:
Filename : /usr/lib64/libavahi-client.so

avahi-devel-0.8-20.fc38.x86_64 : Libraries and header files for avahi development
Repo : rawhide
Matched from:
Filename : /usr/lib64/libavahi-client.so

Alright, so the missing package is avahi-devel. After installing that, I got a another error:

ninja: error: '/usr/lib64/libavahi-gobject.so', needed by 'src/gnome-network-displays', missing and no known rule to make it

Let’s hear what dnf provides has to say about this one:

$ dnf provides /usr/lib64/libavahi-gobject.so
Last metadata expiration check: 0:30:58 ago on Mon 03 Apr 2023 04:28:17 PM -03.
avahi-gobject-devel-0.8-20.fc38.x86_64 : Libraries and header files for Avahi GObject development
Repo : rawhide
Matched from:
Filename : /usr/lib64/libavahi-gobject.so

Looks like avahi-gobject-devel was the culprit this time around, so I installed it and attempted to build the application again and… Success!

Since the build dependencies of the gnome-network-displays rpm package were clearly outdated, I made a pull request over the Fedora Package Sources to update it.

Running the application

Equipped with my own build of GNOME Network Displays, I decided to see what it was all about. I enabled Miracast on my TV and waited for the application to pick it up. And waited. And waited. And waited.

Something was off.

My first suspicion was firewall configuration and (thankfully) I was right. Browsing the repository of GNOME Network Displays I found out that this commit added integration with the default firewall utility of Fedora Silverblue.

All I needed to do was change my firewall zone to WiFi P2P.

Upon doing that, my device started being detected! Once I clicked it though:

To proceed, I installed the GStreamer OpenH264 Encoder (which is provided by the gstreamer1-plugin-openh264 package). With that I was finally able to start the connection, but the display mirroring didn’t actually work.

** (gnome-network-displays:17808): DEBUG: 17:47:13.929: Got state change notification from streaming sink to state ND_SINK_STATE_WAIT_SOCKET
** (gnome-network-displays:17808): DEBUG: 17:47:59.487: WFDP2PProvider: Device state changed. It is now 120. Reason: 11
** (gnome-network-displays:17808): DEBUG: 17:47:59.494: WfdServer: Finalize
** (gnome-network-displays:17808): DEBUG: 17:47:59.495: WfdMediaFactory: Finalize
** (gnome-network-displays:17808): DEBUG: 17:47:59.495: Got state change notification from streaming sink to state ND_SINK_STATE_ERROR
** (gnome-network-displays:17808): DEBUG: 17:47:59.518: WFDP2PProvider: Device state changed. It is now 30. Reason: 0
** (gnome-network-displays:17808): DEBUG: 17:47:59.771: WFDP2PProvider: Peer removed
** (gnome-network-displays:17808): DEBUG: 17:47:59.771: MetaSink: Priority sink updated. Priority: 100

From the logs, it looks like timeout, but I decided to investigate that later.

Making a contribution

One of the first things I noticed upon launching GNOME Network Displays was that I could not move its window by dragging its header bar not resize its window by dragging its borders. I spent some hours trying to fix that but didn’t manage to.

After all, I acknowledged my own defeat and decided to make a simple contribution fixing some typos. However, there will be no truce! Mark my words:

GNOME Network Displays, we will meet again!

Using the GTK Inspector in GNOME Boxes

Sun, 02 Apr 2023 11:07:02 -0300

The GTK Inspector is a powerful tool that allows developers to better understand how the code is “mapped” to the user interface of a GTK application. It can usually be activated using the keyboard shortcut Ctrl + Shift + i, but that isn’t working on GNOME Boxes. Although I’ve made an attempt to fix this issue, changes to GNOME Boxes can a long time to land because it follows the release schedule of GNOME (about once every six months). Considering this, I’ve put together this guide to use the GTK Inspector in GNOME Boxes in its current state.

Method 1: enviroment variable

Setting the environment variable GTK_DEBUG to interactive upon launching GNOME Boxes (or any GTK application!) will launch the GTK Inspector alongside it.

If you installed Boxes using a package provided by your distribution run:

GTK_DEBUG=interactive gnome-boxes

If you installed GNOME Boxes as a flatpak, run:

GTK_DEBUG=interactive flatpak run org.gnome.Boxes

However, if you want to use the GTK Inspector with your own build of GNOME Boxes, you should probably use one of the following methods.

Method 2: toggle option in Builder

On the most recent versions of GNOME Builder you can launch the inpector alongside the application you are compiling by simply toggling an option on the run menu, as you can see below:

This will take care of everything for you (thanks GNOME Builder!).

Method 3: project configuration in Builder

If your version of GNOME Builder does not have the feature mentioned above yet, don’t worry there’s still hope! First, head to the project configuration page by hitting Alt + , or clicking the “Configure Project…” option in the dropdown menu of the omnibar:

Then, append GTK_DEBUG=interactive under the “Configure Options” text box:

What we did here was changing the flatpak manifest of GNOME Boxes using a nice graphical user interface (thanks GNOME Builder!). Since you would want to keep our changes to that file to yourself, you should tell git to ignore it. Using .gitignore is no-go because the .gitignore file itself is being tracked by git. Instead we should add the path of the flatpak manifest to .git/info/exclude, so git will ignore it locally, like so:

echo "build-aux/flatpak/org.gnome.BoxesDevel.json" > .git/info/exclude
git update-index --assume-unchanged build-aux/flatpak/org.gnome.BoxesDevel.json

Later, if you want to make a contribution that involves changing the flatpak manifest, remove the line that contains build-aux/flatpak/org.gnome.BoxesDevel.json from .git/info/exclude and run:

git update-index --no-assume-unchanged build-aux/flatpak/org.gnome.BoxesDevel.json

Method 4: export package in Builder

In case you need more flexibility with your custom build of Boxes (say, scripting) you’re better off exporting and installing a package. GNOME Builder makes this very easy (thanks again GNOME Builder!). First, build the application once by clicking the hammer in the omnibar. Then, click the “Export” button and wait.

Once it’s done, the file explorer will open in a directory with the exported .flatpak package. Now, simply double-click it to install using GNOME Software. When installation is complete, you’ll be able to access the GTK Inspector using the first method I presented:

GTK_DEBUG=interactive flatpak run org.gnome.BoxesDevel

If you built the application with the project configuration described in the third method, the GTK Inspector will always launch along side your build of GNOME Boxes. In that case, you can even launch Boxes via the applications menu (its icon will be wrapped in “under construction” tape, as the one on the left side of the image).

That about covers it! While I hope this blog post becomes obsolete when someone fixes the issue of the keyboard shortcut not working (possibly myself?), I also think this was a great opportunity to learn more about flatpak and GNOME Builder.

See you in the next one!