sch-rnd-aux knowledge pool
A hidden risk of gschem external symbol refs
| geda_symref_bug by Tibor 'Igor2' Palinkas on 2022-05-09 | Tags: insight, geda, gschem, lepton-eda, bug, sym, symbol, library, external, reference |
Abstract: Demonstrate and explain a hidden risk of silent failure with external symbol references in gEDA (gschem or lepton-eda).
1. A hidden risk of external sym refs
By default gschem saves external symbol references, which means it saves the basename of the symbol ("res.sym" in our example) in the sheet file. Then upon load gschem goes and looks up the first matching file from the current library.
This is said to be good because if you fix a symbol in your library, it automatically affects all old sheets that uses that symbol whenever you are going to load those sheets.
Trivial risks/drawbacks are:
- it is real easy to break existing sheets by changing anything in the library; in other words: if you maintain both a large library and a large collection of sheets, it's fairly hard to predict the outcome/risks of fixing a symbol
- sheets with such external sym refs are non-portable: on another system a different library, or just different order of library directories or different versions of the same symbols may be present and there's no reliable way to match sheet's expectations to a random lib
- when any of these breaks, it typically breaks silently: gschem will have no idea about the mismatching symbol
There are two ways to avoid all the above:
- a) embedding all symbols in the sheet
- b) creating a local symbol library with a local gafrc and manually place all symbols the sheet is using (and then manually keep this local lib up to date as sheet's symbol usage changes over time)
Unfortunately method b) is not as safe as we like to believe, and this is related to (the missing) "project file concept" that gafrc sort of tries to work around.
2. Proof of concept
Unpack the tarball and cd to its geda_symref_bug, then run:
gschem p1/A.sch p2/B.sch
This will load two schematics, each with a different resistor symbol shorted. The symbols are loaded from the corresponding local libraries, p1/sym1/ and p2/sym2/.
In the library window both sym1 and sym2 are accessible. Place the other style res symbol on each page, so both pages have both kind of symbols. Then save all, quit and load both pages again the same way:
gschem p1/A.sch p2/B.sch
Suddenly the newly placed resistor is of the wrong symbol on both pages!
So what worked in the initial edit silently breaks after a reload.
3. Why it breaks
This is because the external symbol file reference works in two different ways:
- 1. when you initially place the symbol, it is loaded into the buffer from the specific directory you clicked on in the library window and gschem remembers that (I am not sure, either the actual graphics or the full path), so initially both pages can have the two different res symbols.
- 2. when you then quit and reload, each gafrc is loaded for each sheet again and for each sheet there will be only one res symbol: the one from its own local sym lib.
This means sheet files intended to be reused in multiple designs as a building block shouldn't rely on local symbol libraries and gafrc, because when the sheet is then used in a random "project", and edited, it may accidentally get symbols that look good at placement but will silently fail when reloading even the same "project".
(Since there's no real project file in gEDA, "project" in this context means loading multiple sheets in the GUI editor or passing the same sheets together to the netlister.)