Icon theme cache issues

So I spent a good deal of saturday chasing down a bug in Agave that was reported by somebody trying to make a Debian package of it. Some time ago, when the second "GNOME Goal" was introduced for Installing theme-friendly icons, I decided I'd do that to Agave as well. (By the way, those little goals were kind of a nice way for new contributors to feel useful, are there plans for any more?). Everything worked fine until a couple days ago when I had a report of a crash when installing the application to /usr due to an icon not being found in /usr/local/share/icons/hicolor/...

Why was it looking in /usr/local/...??? I scoured my source code for hard-coded references to /usr/local, and not finding any, I sat scratching my head for a good long while. Now, somebody more familiar with gtk icon theme issues may have recognized the problem immediately, but it took me quite a while to figure it out, so I thought I'd post the solution in case anybody else runs in to the same issue. The problem only shows up if you've first installed the application to /usr/local (the default) and then uninstalled it and installed it to /usr.

The GNOME Goal page mentioned above suggests an install-data-hook rule which updates the gtk icon cache after the program's icons are installed. So the icon cache in /usr/local gets updated when you first install the program to /usr/local. Unfortunately, after uninstalling the application, the icon cache is not updated, so gtk still thinks there are application icons located under /usr/local.

Since /usr/local/ is in the icon theme search path before /usr, when the application is installed to /usr, it will find the stale icon cache in /usr/local and think it found the icon you've requested. Unfortunately the icon that it 'found' has already been deleted, so it will try to load an icon from /usr/local that doesn't exist, and the program crashes. The solution is to simply add an uninstall-hook that also updates the gtk icon cache so that you don't have a stale icon cache after you run `make uninstall`. Something like the following:

gtk_update_icon_cache = gtk-update-icon-cache -f -t $(datadir)/icons/hicolor
install-data-hook: update-icon-cache
uninstall-hook: update-icon-cache
update-icon-cache:
        @-if test -z "$(DESTDIR)"; then
                 echo "Updating Gtk icon cache.";
                 $(gtk_update_icon_cache);
         else
                 echo "*** Icon cache not updated.  After install, run this:";
                 echo "***   $(gtk_update_icon_cache)";
         fi