pcb-rnd - plugin development - per plugin config subtree

Each plugin can maintain its own configuration subtree within the central conf tree. For this, the plugin needs to create the subtree under its own name under the plugins/. From then on, the config values are loaded and handled by the central system and are accessible through a global struct variable declared within the plugin.

the config header

The source of all information on what nodes consists the plugin's own subtree is the file pluginname_conf.h in the plugin dir. It can be created by copying and renaming this template.

The structure must reproduce the plugin sub-struct and the pluginname sub-struct nested in it, in order to keep the C struct field reference path the same as the textual conf path.

Create an empty file called pluginname_conf_fields.h for placeholder. Do not add it to the svn repo.

tmpasm

The conf file must be registered in the tmpasm file. Add these lines in Plug.tmpasm to set the file name:

put /local/rnd/mod/CONFFILE {pluginname.conf}
put /local/rnd/mod/CONF {$(PLUGDIR)/pluginname/pluginname_conf.h}
put /local/rnd/mod/CONFVAR {pluginname_conf_internal}

Create the conf variable

The conf access variable should be a global variable in the main plugin c file:

#include "pluginname_conf.h"

const conf_pluginname_t conf_pluginname;

#include "conf_internal.c"

From now on, the example fields can be accessed like:

conf_pluginname.plugins.pluginname.snow

Note: these variables are strictly read-only. Use conf_set*() from src/conf.h to change the value.

plugin init

Copy these lines in the plugin init callback:

rnd_conf_plug_reg(conf_pluginname, pluginname_conf_internal, pluginname_cookie);
#define conf_reg(field,isarray,type_name,cpath,cname,desc,flags) \
	rnd_conf_reg_field(conf_pluginname, field,isarray,type_name,cpath,cname,desc,flags);
#include "pluginname_conf_fields.h"

plugin uninit

On uninit all local config nodes need to be removed from the config system. This is easy, since all our nodes are under a single subtree. Copy this line in the plugin uninit callback:

	rnd_conf_plug_unreg("plugins/pluginname/", pluginname_conf_internal, pluginname_cookie);

make dep

After committing all these, you will need to run make dep in src/. Before committing that, double check svn diff: it must not have any unrelated change, only files related to your plugin.

When done, the build system knows how to generate pluginname_conf_fields.h - remove the dummy empty file and run make to get it generated.

default values

For setting default values, a local default config file needs to be set up.