pcb-rnd hacking - simple core plugins

Introduction

Setting up a new core plugin

• 1. make up a name for the plugin. There are a few conventions. This document will refer to the name as plg, always replace it with your chosen name.
• 2. cd src_plugins; svn mkdir plg
• 3. copy Makefile, Plug.tmpasm and .pup from another, small plugin, for example from the report plugin (the next points will assume you picked this plugin as the source of the copy)
• 4. edit Makefile: replace report to plg
• 5. edit plg.pup; there should be short summary about the purpose of the plugin then "#key: value" pairs for statistics:
  • $class the same as the plugin name prefix (see conventions. ) or (feature) for feature plugins; it's redundant but is kept for supporting external plugins
  • $short short description - should be less than 32 characters; this shows up in the configure summary
  • $long long description - used for documantation; no length limitation, but must be a single line
  • $state either works or disabled
  • $lstate [optional] a chance to explain why the value of default is what it is; e.g. why a plugin is disabled
  • default disable-all or disable or buildin or plugin
  • dep [optional] a single plugin name on which plg depends; multiple dep lines can be added
  • conflict [optional] a single plugin name on which plg conflicts with; multiple dep lines can be added
  • autoload [optional] when 1, the plugin is automatically loaded and initialized (when not disabled); do not set this on libs and other code that are accessible only as a dependency of other plugins; set this 1 on HID, io, import, export, feature plugins
  Values of default:
  • buildin - unless the user requests otherwise, your plugin is linked into the executable
  • plugin - unless the user requests otherwise, your plugin is dynamically linked; not recommended: the policy is to let users explicitly request dynamic linking
  • disable - unless the user requests otherwise, your plugin is not compiled (recommended until the plugin gets some user testing)
  • disable-all - the plugin stays disabled even with ./configure --all=* and the only way to enable it is to excplicitly name it
  IMPORTANT: all fields are single-line, do not use semicolon (';') in any of the fields.
• 6. edit Plug.tmpasm:

  put /local/pcb/mod {plg}
  put /local/pcb/mod/OBJS [@ $(PLUGDIR)/plg/foo.o $(PLUGDIR)/plg/bar.o @]
  put /local/pcb/mod/CONF {$(PLUGDIR)/plg/foo_conf.h}
  put /local/pcb/mod/YACC [@ $(PLUGDIR)/plg/bary @]
  put /local/pcb/mod/LEX  [@ $(PLUGDIR)/plg/barl @]
  		

  • /local/pcb/mod: the name of the module we are compiling
  • /local/pcb/mod/OBJS: a space separated list of object files to compile
  • /local/pcb/mod/CONF: optional: the name of the conf struct header - if the plugin doesn't have runtime configuration settings, remove this line
  • /local/pcb/mod/YACC: optional: if you have files for yacc-processing, list them without the .y suffix here (space separated)
  • /local/pcb/mod/LEX: optional: if you have files for lex-processing, list them without the .l suffix here (space separated)
  • Leave the switch part on the bottom intact.
• 7. create your C sources and headers in src_plugins/plg/ The order of entries in the file is the same as the order in the summary table at the end of ./configure; insert your plugin in the right group!
• 8. run "make map_plugins" in src/ to get your new plugin on the plugin list
• 9. run ./configure --buildin-plg
• 10. run make to see if it compiles and test
• (11. while developing, you can run make from src_plugins/plg - if your plugin is a builtin, it will recompile pcb-rnd. For some of us it's convenient to run make in the same directory where all the source files are.)