# 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 - see mods3 for a short list of all classes
  - $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 works, WIP, abandoned or deprecated - see mods3 for explanation
  - $lstate [optional] a chance to explain why the value of default is what it is; e.g. why a plugin is disabled
  - $package when pcb-rnd is packaged for a distribution or OS, which package this plugin should end up in (see also: trunk/doc/developer/packaging/)
  - $fmt-native only for io_ plugins: whether this format is considered native (see also: io_lihata's pup)
  - $fmt-feature-r only for io_ plugins: a read/load feature supported by the plugin (multiple entries of this should be added; see also: io_lihata's pup)
  - $fmt-feature-w only for io_ plugins: a write/save feature supported by the plugin (multiple entries of this should be added; see also: io_lihata's pup)
  - 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.)