Buckle up, because this is a long “confusion-induced pain” user story. Hopefully it can provide some UX insights.
I use builder maybe once every few months to try to test silly one-liner patches I might do to some of the GNOME applications, and I’ve had very very little luck with it. Every time, whether it’s the flatpak version or the RPM version from Fedora, I would always get Builder confused or into an unworking/non-building state, and I don’t even know how… my suspicion is that in the majority of cases, it would have something to do with the build environment it creates or the SDKs it sets up.
The builder preferences dialog, and project properties, are very confusing to me. I can’t figure out why, for example, it would sometimes get things visibly wrong and, say, apply the “configuration” it had created for the Meld devel project and apply it by default to every new other project I’d create/open, even if there’s something like a “Default” configuration profile (from what I can see in the “Configure Project” dialog).
I don’t know how to properly explain the problem, because I don’t truly understand what’s going on, myself, so I don’t have the words to express it clearly. But basically I’ve encountered so many situations where Builder (and myself) gets super messed up, and what I would really want is a big “
RESET EVERYTHING ” button that only preserves the code folders themselves (i.e. the git checkouts and my changes to those files/folders on the filesystem). Something that would delete all SDKs in one go (there isn’t even a button to delete an individual SDK in the current GUI) and possibly all build files of the current project (there is apparently a “Rebuild” and “Clean” action per project, that I tried just now and… nothing visibly happens).
Today I wanted to do a one-liner patch attempt on GNOME Calendar’s .UI files, so I launched builder and told it to check out and build GNOME Calendar, among the list of preset applications it offered me, and I’ve been utterly unable to get it to even start building. I have no idea why. It just calls the project “dev” instead of recognizing as GNOME Calendar, even if Builder is the one that did the checkout by itself! The only clue I have is that my dev folder, as set in the global preferences, is ~/dev. And that ~/dev is a symbolic link to /mnt/extend/dev/, that is a folder on my SSD that is mounted on /mnt/extend/ (because I can’t have a SSD big enough to contain my home folder, I only use it for speed-critical applications, like building code), maybe that’s what’s freaking it out, but I think I recall seeing it work sometimes, and also trying without that symlink folder and it still choked. And I don’t know why a symlink would be a problem, especially if I’m using the system-installed version of GNOME Builder nowaydays (instead of the flatpak-installed version).
I’ve reached the point where I thought, “YOLO, I’m sick of this, I’ll just blindly rm -R .cache/gnome-builder/ (which currently has 25770 items, totalling 688 MB) and rm -R .local/share/gnome-builder (which has 116011 items, totalling 2.1 GB).” I shouldn’t have to do that, or if I do, there ought to be a big reset button in the GUI to do it for me. Nevertheless, I did nuke those folders now, and when I launch Builder again, the only thing that changed is that it doesn’t have my existing list of projects/checkouts pre-populated; the SDKs still show up in the Builder GUI “Configure Project” dialog, and it still is unable to build GNOME Calendar. For example, after telling it to “Open Project” and pointing it to the GNOME Calendar checkout it had created, this is what Builder looks like on startup:
What happens when I click the ~/dev/gnome-calendar “Recent project”:
I can imagine that doesn’t look normal, because it sets me in the dev folder. Again, maybe here it doesn’t like the symlink? More on that later…
Now I’m thinking “Yeah, it seems like nuking the cache and data folder did nothing? Where is it seeing all these SDKs from?” and realize it’s probably (?) showing whatever runtimes I have from my general “user” flatpak (as I can see them with flatpak list). But they’re all already up to date, so why is it giving me individual update buttons for all of them if those buttons don’t do anything?
I tried clicking the build (Play) button, the hammer, and the Build, Rebuild, Clean menubutton actions; none of them did anything.
Then I thought about the ~/dev symlink thing again, and went into Builder’s global preferences, told it to consider /mnt/extend/dev as the dev folder (but really, it should have been able to handle the symlink in the first place), removed the existing project and told it to add /mnt/extend/dev/gnome-calendar as a project, and yay, it showed something a bit more normal:
So hey, now it’s finally going to start building that thing correctly, right? Nope, this is what happened when I hit the play button:
The Meson build system
Version: 0.63.3
Source dir: /mnt/extend/dev/gnome-calendar
Build dir: ~/.cache/gnome-builder/projects/gnome-calendar/builds/default-host-x86_64-main
Build type: native build
Project name: gnome-calendar
Project version: 44.alpha
C compiler for the host machine: ccache cc (gcc 12.2.1 "cc (GCC) 12.2.1 20221121 (Red Hat 12.2.1-4)")
C linker for the host machine: cc ld.bfd 2.38-25
Host machine cpu family: x86_64
Host machine cpu: x86_64
Checking for function "strerror" : YES
Found pkg-config: /usr/bin/pkg-config (1.8.0)
Found CMake: /usr/bin/cmake (3.25.1)
Run-time dependency libical found: NO (tried pkgconfig and cmake)
I was about to give up again, then I had an idea: I went into the “Configure Project” dialog again, saw that it was using “Default” as the “Current Configuration”, and when I clicked that I saw that it offered me “org.gnome.Calendar.json”… and when you select that and click the play (build) button again, then it starts checking out SDKs to build the thing. That was definitely not intuitive. Why didn’t it prompt me for that choice in the beginning if it was important? Or have some warning icon with explanatory tooltip if you are using “Default” or the config from another project?
Anyway, after that, it finally built the thing. And then I realized I was sitting in a dark room because noon’s daylight had gone, and night had fallen 
So instead of being able to create and test a patch in a few minutes today, I’ve just wasted hours again trying to get anything to build, and nearly gave up entirely (on multiple occasions). I wish this was the first or only time this happened to me. Every time I wanted to use GNOME Builder, despite many (sometimes hours-long) troubleshooting sessions via IRC with maintainers of various projects, I’ve been wasting hours and days of my time (and theirs) trying to figure out what’s going on… and I’ve been questioning my sanity and competence, when I’m able to use advanced git features (like rebasing) without problems (and when I was previously able to compile GNOME apps by myself, even with jhbuild or other oldschool methods) but somehow can’t use this nice GUI app without getting utterly confused and messing things up.
I really want to like and use Builder more regularly, and just “Press button; Receive bacon” as it implicitly promises, but so far every attempt inexplicably landed me into mandelbug territory everytime. Is it just me being stupid, or is there something missing in the app to make this “clean room” workflow work, like a big reset button? Or better warnings, better distinction between local and system libraries and SDKs, or just symbolic links handling?
The only things I found to possibly be vaguely related are:
- Check if SDK updates are available (#433) · Issues · GNOME / gnome-builder · GitLab
- Toolchain selection is confusing (#1510) · Issues · GNOME / gnome-builder · GitLab
…but nothing about dropping caches and force-resetting non-user-generated data / build files, etc. Or symlinks (if that changes anything).
I realize this is not a terribly useful report here because my mental model so far appears to be unable to map to how Builder is probably meant to be used, and I really have no idea what I’m doing with it, but I hope this user story can be useful for something, somehow. I know I have a curse, but I might not be the only one struggling with this?
Maybe some actionable bug reports can be filed from what you may interpret of this confusion story? Happy to help there, but I don’t know what’s valid to file as bug reports (and the gitlab ticket template pointed me to the forum for any enhancement requests, so, well, here I am).