Where are gnome-shell's UI javascript files on Ubuntu 20.04?

Answer compat:
Ubuntu 20.04.2
gnome-shell version: 3.36.4
display server: X.Org Server

Important note:

Making any mistake while altering gnome-shell's files can introduce a deadlock of your graphical session. Attempt it only if you are familiar with common methods of system recovery.

Also, executing changes in this answer will demand an additional workflow to handle gnome-shell updates with due caution, as explained below.

Modifying functionality

On Ubuntu 20.04, gnome-shell's javascript files are normally packaged up inside the file:

/usr/lib/gnome-shell/libgnome-shell.so

To override them, one needs to extract copies of the subject files, and ask Gnome to use the copies.

Below I provide an abstracted, task-agnostic walk-around. To see a similar procedure in action on a specific practical task, see this answer.

The to-be-modified file copies can be organized in an arbitrary location, in this walk-around I use the following location:

~/.gnome-shell-custom-overlays/

To enable this "customization platform", one needs to place the following line in ~/.profile:

export G_RESOURCE_OVERLAYS="/org/gnome/shell=$HOME/.gnome-shell-custom-overlays"

For this to take effect, logging out and logging back in is necessary.

A note on dependencies:

Before I got this procedure working on my machine, I already had the libgtk-3-dev package installed. It's for development / debugging, just like the resource overlays feature seems to be so. Therefore right now I cannot determine whether respecting the G_RESOURCE_OVERLAYS environment variable depends on the presence of this package or not... Just in case, be ready to install it.

Setting up subject files:

One can list the contents of libgnome-shell.so as follows:

gresource list /usr/lib/gnome-shell/libgnome-shell.so

The next step is extracting the to-be-modified file. Let's use an example where this file is located in gnome-shell's ui/ subdirectory.

mkdir ~/.gnome-shell-custom-overlays/ui

gresource extract /usr/lib/gnome-shell/libgnome-shell.so \
/org/gnome/shell/ui/fileName.js > ~/.gnome-shell-custom-overlays/ui/fileName.js

Tweaking:

To see the effect of tweaks on the customized file, reloading the gnome-shell after each edit seems to be necessary. It can be done quickly by issuing the r command through the Run command dialog (revealed by Alt+F2).

At this point you should have a working override which persists through reboots.

A note on recovery:

If a modification attempt goes wrong, it should be possible to switch to a virtual console environment (with e.g. Ctrl+Alt+F3). From there, commenting out the G_RESOURCE_OVERLAYS line in ~/.profile and subsequently rebooting should disengage the override and thus have the capacity to restore the system.

A note on using G_RESOURCE_OVERLAYS

It may be the case that this feature is aimed primarily at debugging and development, and perhaps not for permanent usage.

The system's stability may be impacted: when I first enabled this, I saw some previously not experienced weirdness with my sound settings, and some window-flickering. A few restarts of the gnome-shell and a (few?) reboot(s?) however solved it, and from the next day on I haven't experienced any further anomalies.

Furthermore, in the "Logs" app I can see that the event of using G_RESOURCE_OVERLAYS gets logged in the "security" section, so that's good to consider.

Regarding receiving system updates while using G_RESOURCE_OVERLAYS:

The following section is entirely speculation, I have no confirmation about whether any of this is valid; yet it may be useful to consider:

If and when gnome-shell receives an update, I see a chance that the customized gnome-shell files might lose their compatibility, and may even cause the desktop to break.

I believe in such case one could suspend using the G_RESOURCE_OVERLAYS feature through ~/.profile (as discussed in the recovery section), subsequently repeat extracting the subject files from the fresh libgnome-shell.so, and re-apply the modifications in a compatible manner.

In case an update causes such an event of incompatibility, I speculate some risk involving the desktop crashing already while the configuration stage of the updates are being executed; I can vision significant collateral damage inflicted on other systems in such a case. (I might be wrong.)

Nevertheless, for this reason, I would consider to let gnome-shell updates to be installed separate from other updates, so that the event could not interfere with the installation of other packages.

A layer of control, for stability:

To manage the aforementioned risks, one can put gnome-shell on hold status, that prevents its updates from installing, until one is ready to deal with them.

The procedure then looks like this:

  • hold gnome-shell: sudo apt-mark hold gnome-shell
  • live life in peace for however long
  • when gnome-shell has available updates, it will show up in the updates dialog, but its checkbox will be unchecked, therefore will not be installed
    • one should be able to go on like this until one is ready to perform the update
    • when ready to update, follow according to the next steps
  • run the updater, and let every update install, apart from gnome-shell's
    • reboot if necessary, and run the updater again, just to ensure that no other updates are available at the moment, apart from gnome-shell's
  • disable G_RESOURCE_OVERLAYS in ~/.profile, and restart gnome-shell
    • confirm that G_RESOURCE_OVERLAYS are indeed not used, by verifying the lack of UI customizations
  • unhold gnome-shell: sudo apt-mark unhold gnome-shell
  • run the updater and let gnome-shell update this time
  • re-enable G_RESOURCE_OVERLAYS in ~/.profile and restart gnome-shell
    • deal with any fallout of incompatibility, if necessary
      • this might involve disabling G_RESOURCE_OVERLAYS again (from a virtual console, if necessary), and re-establishing the overridden files with renewed, this time compatible modifications in them
  • having achieved a stable state again, put gnome-shell back on hold again
    • repeat the above procedure when new updates arrive

Compiling the modified files back into libgnome-shell.so

I reckon the risks around the updates can be avoided if one, instead of relying on the resource overlays feature permanently, compiles the modified files back into libgnome-shell.so (because then an update does not cause an event of incompatibility; instead it just rewrites libgnome-shell.so in one go).

However, unfortunately, this task seems to depend on a significant amount of Gnome- and/or Ubuntu-developer know-how; mere agility around code-editors does not seem to cut it.

The compiler, glib-compile-resources, requires an XML-formatted list of the resources to be compiled, and its output cannot be easily reattached to an existing .so ELF file.

source

At a guess, you are missing the C code used by the lower-level parts of gnome-shell, which goes into the same library as the JavaScript resources.

If you obtained gnome-shell by compiling it from source code (for instance in jhbuild) [...]

If you obtained gnome-shell from a distribution like Debian, Ubuntu [...], you will need to apply your JavaScript changes as local changes to that distribution's gnome-shell package, rebuild the gnome-shell package with a local change to the version number, and install the new package.

source

Compiling the entirety of gnome-shell from source is no small feature. Actually it has such an extensive impact, apparently with so many things that could go wrong with it, that I personally feel it puts the reasonability of the choice in question.

Nevertheless, if you can share the actual steps of compiling gnome-shell in the context of Ubuntu successfully, please submit an answer.


References / literature:

  • Credit to Superuser Q/A
  • Gnome devs' reference
  • Gnome cookbook on Arch wiki