Index: groups.html =================================================================== --- groups.html (nonexistent) +++ groups.html (revision 2035) @@ -0,0 +1,4 @@ + + +

The new config system in pcb-rnd

Why, what was wrong with the old one?

Index: index.html =================================================================== --- index.html (nonexistent) +++ index.html (revision 2035) @@ -0,0 +1,77 @@ + + +

The new config system in pcb-rnd

Why, what was wrong with the old one?

+The old config system had several limitations that would have been +hard to fix keeping the original design: +

config settings were specified in a flat list - no groupping +
the core had a rather static system - HIDs or plugins couldn't extend it, thus they had to invent their own config files +
... this led to a variety of configuration formats; using one format not always because it was better suited for the task, but for historical reasons +
... this also led to a collection of config files - again not always split by boundaries of settings, but often by arbitrary boundaries of code +
the old system didn't support lists or arrays well +
it didn't have a coherent concept of how settings from different sources would override eachother +
... this resulted in the rigid structure that most of the settings could come from only one place (e.g. if it's an user setting, the design won't be able to override it) +

+ +

What the new system offers

unified format: lihata ... +
... more future proof: generic markup language - easier to extend wihtout having to worry about breaking the syntax +
... the configuration is represented in a tree, groupped by the nature of settings +
... there are arrays and lists +
... a config file can overwrite a list or prepend/append to it (e.g. design-level config prepending an extra library path keeping system set paths as well) +
there are different sources of configuration, e.g. system-wise, user-wise, project-wise, etc. +
the user has the power to change default config priorty per setting; e.g. normally design config overrides user config, but it's possible to mark a setting from user config so strong that it overrides even the setting read from the .pcb file +
the way settings are stored is flexible and extensible so that a plugin can define their subtree of settings +
... since the API even makes it easier to access such settings (vs. parsing your own config file), plugins will tend to use the unified config format/system instead of inventing teir own +
... the GUI (gtk's preferences dialog) thus can automatically handle the new settings +
... plugins don't have to implement actions to set/toggle/query their settings for the menu system, there are generic config set/toggle/query actions the menu config can use +
... plugins also get the multi-source, priority-based config mechanism +
... which also means plugin settings can be automatically saved as user setting, project setting or even design setting +
all these are true for all kind of settings, be them GUI preferences, paths, layer colors, grid settings; there should be no exception +

+ +

How to get started

If you are an user, read the user documentation +
If you are an programmer, read the user documentation and the programmer documentation +
If you are a plugin programmer, there's a plugin programmer's conf checklist that summarizes what to do +

+ + +

But isn't this more complicated for the user?

+Hopefully not much. There are a few extra features, like +multiple sources with levels that did not +exist in pcb and lists with prepend/append. Some of these +features present in other software so users should be comfortable with the ideas. +The learning curve is probably compensated by the more orthogonal system. +The syntax is also geared for simplicity and easy use with text editors. +Finally, the new preferences dialog in the GTK HID and config actions help +the user to explore how settings got used from all the config sources. There's +an intended layering in complexity: simple things can be done easily without +having to understand the whole system. +

+All in all, the extra features the user needs to learn is comparable with +the old customs that he/she can forget. + +

And did it make the code more complicated?

+The size of the code did not change much after the initial config rewrite. +The new system has new features, some of which brought in a few hundred lines of +code, but a similar amount of old code could be removed. What came in is +infrastructure, what had to go was a bunch of repetitive config parsing, +boolean-setting-accessor-action code. This means on the long run, the more +settings are added, the more the new system pays back. +

+Read access, which is far the most common way to use the config in the +code (e.g. if (setting == true) { }) is very similar to the old Settings +system. Write access needs to go through a function call API, but this +is usually a single call per setting (instead of directly modifying a +variable). +

+For plugin programmers, the new system makes life much easier as they can +plug their settings in. + + + + Index: sources.html =================================================================== --- sources.html (nonexistent) +++ sources.html (revision 2035) @@ -0,0 +1,66 @@ + + +

The new config system in pcb-rnd

Sources

+There are different sources of configuration settings. These are +different configuration files, sometimes located on the file system. +The full list of config sources is: + + +

role	default setting prio	location	presence	remarks +
internal +	100 +	(compiled into the executable) +	always +	the ultimate fallback; allows pcb-rnd even if no other configuration file is found + + +
system +	200 +	/usr/share/pcb-rnd/pcb-conf.lht +	recommended +	should hold system and installation specific settigns, e.g. path to the system-wise installed footprint library + +
user +	300 +	~/.pcb-rnd/pcb-conf.lht +	recommended +	store user preferences, user's common footprint lib path, etc; this is the first file the user can modify (even from the GUI) + +
environment +	400 +	environment variables (TODO) +	occassional +	inject the same (temporary) settings in multiple pcb-rnd sessions without having to change config files + +
project +	500 +	projdect.lht in the project directory +	optional +	local project settings - useful for large projects with multiple design (.pcb) files + +
design +	600 +	saved in the design (.pcb) file +	optional, common +	per design deviation from the user+system config + +
cli +	700 +	command line argument +	occassional +	inject/change a setting for a single session; useful in batch/automated processing +

+ +

+Pcb-rnd reads them all, then merges all settings into a master binary +representation. If a setting is specified in multiple sources, the one +with the higher priority wins, except for lists where it is also possible +to prepend/append items. Default priorities are designed to result +precedence in an intuitive way (e.g. design settigns overwrite user settings). +However, priority can be changed per setting, resulting +in weak settings ("use this value if it was not already set") or strong settings +("I always want to use mincut, so I enable it from my user's config with high +priority and a version controlled project setting can not turn it off") + +