pcb-rnd knowledge pool
Menu patching: what was wrong with the original system?
menu_patch_old by Tibor 'Igor2' Palinkas on 2020-07-18
Tags: announcement, menu, patching, patch
Abstract: pcb-rnd offers a more flexible menu description from version 2.2.4, based on run-time menu patching. This article describes the problems with the previous (dynamic, but not real-time patched) menu system to specify the reasons for the change.
There is a howto about how to use the system for maintaining your own menu modifications.
1. user aspects
The original system used a single lihata document to describe the menu tree. This was loaded from (typically) /usr/share/pcb-rnd/pcb-menu-default.lht.
A major problem was that some users wanted to make minor modifications to this file. But once you patch this file, you need to maintain it as new versions of pcb-rnd will change this file as well.
If you failed to merge upstream modifications into your modified menu file, you lost new features and sometimes introduced new bugs in your local version by getting your menu running old/obsolete/buggy actions that were already fixed in upstream. Or if you kept using the new upstream version of the menu file all the time, and forgot to merge your own changes, you could easily lose your new features or modified hotkeys.
For this, we needed something that allows the user injecting small files that make modifications to the existing upstream menu file runtime, so the original/upstream menu file doesn't need to be edited.
2. plugin aspects
There was also a major modularization problem, best demonstrated by the vendor drill plugin. In geda/pcb and early pcb-rnd plugins couldn't extend the menu system so many plugins ended up not creating menus for their features but relying on the central menu file having those menus defined. The vendor drill plugin had 3 such submenus spread across 3 different menus.
This has two major modularity problems:
- the submenus are there even if the plugin is not loaded, they are just defunct; this is an implicit dependency of the core (menu file) on plugins
- the plugin has an implicit dependency on the menu file too; this is more problematic if someone (against all recommendations) start to write an off-tree plugin: that plugin can't have its menus in the central menu file.
There was a way to create menus on the fly, from code, but that had its own problems (see below). So many plugins, especially the ones inherited from geda/pcb didn't bother and just relied on the central menu file to have the menus.
For solving this, we needed a way to make it very easy for plugins to create menus from data, not code.
3. script aspect and dynamic menu creation
As a pcb-rnd extension we already had actions for creating and removing menus from code (or scripts) on the fly. However it did not track order of operations or even who created what menus and why. As long as plugins and scripts (mostly) created submenus only, this didn't cause any problem. But this system couldn't really be used in more tricky situations:
- making modifications to existing submenus (e.g. on script or plugin load) and then undoing these modifications (e.g. on script or plugin unload)
- there are ugly corner cases lurking; for example assume two scripts A and B; A creates menu File/foo/bar, B creates File/foo/baz; they are both loaded; so a submenu File/foo is created with two further submenus bar and baz. Now unload script A, this should remove File/foo/bar. But although originally File/foo was also created by A, File/foo should not be removed because B uses it too! This could be solved by tricks like reference counting or ugly heuristics like "don't delete intermediate levels unless they are empty". But what we really need is a more elegant solution.
And the more elegant solution to both of these problems is a predictable, undoable way of editing the menu system on the fly. This means random parts of the code (plugins, scripts, user actions) should be able to make modifications that later on can be undone without having to undo anything else or without confusing the whole system.
The solutions to these problems are described in the menu patching announcement.