pcb-rnd knowledge pool
How to use the automated integrity check system
| integrity by Tibor 'Igor2' Palinkas on 2017-06-03 | Tags: howto, bug, report, bugreport, integrity, check, test, debug |
Abstract: Automatic data model integrity checks on the fly. How to enable it and how to use it to narrow down and report bugs.
Imported from the mailing list archives.
Historical background
The original data mode we inherited from gEDA/pcb is rather limited (some may even call it broken). There are special cases upon special cases, or in other words, kludges on kludges. All the restrictions of footprints are primarily coming from this (despite of the popular misconception of being a file format issue).
It has been like this since the late '90s. They needed elements so they added them. They made elements as good as the software needed back then. Later on the rest of the software got a lot of additions, like mask, paste, outline, etc, and the model they chose for elements became too restrictive.
As of 2017, with the subcircuits we are redesigning the internal data model, after ~2 decades. Why noone else dared to do this before us has many factors, ranging from "too much work" through "it's not that bad anyway" to the most important one:
"we have working code now, why to risk introducing 1000 bugs with a huge rewrite instead of just gluing on yet another kludge?"
End of historical bakground
integrity checking
And indeed, we do risk having 1000 new bugs with the rewrite. To reduce the risks, an integrity check feature is introduced. To enable it:
- please ./configure current svn head with --buildin-diag
- please enable the plugins/diag/auto_integrity config setting; it can be found in the config pov subtree in the preferences menu (best is to create it for the design then check it in and apply; from then on if you save this board (design), it will remember your setting)
- when enabled, the diag plugin runs a set of integrity checks on the board and buffers, after each user input (mouse click, key stroke). If an operation breaks the integrity of the data model, you'll learn about it immediately after the user input: it will generate loud error messages
Test/bugreport method:
- 0. please enable the auto-integrity checks and start editing boards. Try to use all sort of different editing actions, in all possible combinations on all possible object types. Save boards, load boards, import stuff from different formats, play tricks with the buffer, etc. Then the first time you get an integrity error:
- 1. stop editing - once the integrity is broken, it won't heal, we are interested only in the event of how it gets broken, not how it stays broken
- 2. write a note about what the last user action was e.g. "moved a selected copper arc from within a polygon to outside of the polygon"; any detail may matter; most likely only the last action matters, but it may be that the combination of the last few actions trigger it
- 3. start a fresh board, enable the auto integrity checks and try to reproduce the error with a few steps (e.g. in the above example draw a poly, draw an arc in it, move out the arc and see if it causes integrity error)
- 4. if it does cause an integrity error, please send me the recipe, the "step-by-step reproduction on a fresh board" instructions you figured in step 3.
- 5. if it doesn't, please try again from step 3 or 2; saving and sending the board or the error messages doesn't help me finding the bug; only a reproducible recipe helps.