# pcb-rnd modularization

## Why bother...

I believe good software should be modular. This is especially important in the context of large software, such as CAD applications. There should be a thin core that can model the world and provide the basic operations defined on it but anything else should go in separate modules.

Fortunately PCB already had a strong infrastructure supporting this idea. It has dynamic loadable plugins and the GUI and exporters are in separate HID modules. While working on pcb-gpmi and later pcb-rnd, I added the gpmi module as a separate plugin.

In version 1.0.8 to 1.1.0 a considerable chunk of core code has been moved into core plugins. A core plugin is just a plugin that is maintained together with the core, in the same repository, still the code is somewhat detached from the core. More importantly, the user can choose, for each plugin, separately:

- to compile it as a buildin (static-link it into the pcb executable)
- to compile it as a plugin (dynamic-link it runtime, if the .so is installed in the plugins/ directory)
- to disable the plugin, so it is not compiled at all

I believe such modularization has benefits on multiple levels:

- it is possible to compile smaller, potentially faster executables by omitting features the specific user would never use anyway
- in a distribution dynamic-link plugins can be distributed as separate packages providing the user with the option to decide what features to install
- such plugins have to have some sort of APIs if they want to reference each other or if the code needs to reference them; such an API may not (and often did not) exist when the code is part of the core

## Progress in charts

### Before-after

All numbers are in SLOC and are acquired running sloccount on the given directory. While lines of code alone is not a true measure of complexity, it's a good estimation. The slices of pie charts are the major components of the pcb-rnd executable.

Before modularization: pcb-rnd version 1.0.7 Note: gpmi was already a plugin |  | After modularization: current pcb-rnd Note: gpmi is part of the "plugins" slice

### Zooming on to the plugins

total size per class
IO plugins

feature plugins
export plugins

HID plugins
import plugins

library plugins
footprint plugins

(Red means the plugin doesn't really work).

## Progress in numbers

Below is a table with the summary of core plugins.

module | size [sloc] | status | configure default | class | description
--- | --- | --- | --- | --- | ---
acompnet | 305 | WIP | disable | feature | Auto-complete the current network. A very limited autorouter/assistant.
act_draw | 975 | works | buildin | feature | Expose drawing related API as actions
act_read | 587 | works | buildin | feature | Data access related API as actions
ar_extern | 994 | WIP | buildin | feature | Autoroute using external process
asm | 653 | works | buildin | feature | hand assembly assistant GUI
autocrop | 51 | works | buildin | feature | Reduce the board dimensions to just enclose the objects on the board.
autoplace | 654 | works | buildin | feature | Automatically place subcircuits.
autoroute | 4421 | works | buildin | feature | Automatically route selected or all rats. This is the original autorouter.
cam | 1781 | works | buildin | export | Configurable output job based batch exporting
ch_editpoint | 190 | works | buildin | feature | crosshair: highlight object upon crosshair on edit point
ch_onpoint | 145 | works | buildin | feature | crosshair: highlight object upon crosshair on edit point
ddraft | 2128 | WIP | buildin | export | Actions and a command interpreter for supporting advanced/precise 2 dimensional drafting
diag | 751 | works | buildin | feature | Actions for pcb-rnd core diagnostics, intended for developers. These are not in core because end users normally don't need these. As a plugin, due to dynamic loading, it can be dropped on an existing pcb-rnd installation with minimal risk of scaring away a reproducible bug.
dialogs | 7541 | works | disable | feature | Interactive core functionality: HID-independent GUI dialogs (enabled by GUI HIDs)
distalign | 448 | works | buildin | feature | Introducing Align() and Distribute(), which work much like the similarly named functions in Visio. Given that PCB does not have the concept of "first selected object" to draw on, the reference points can be selected by arguments.
djopt | 2332 | works | buildin | feature | Various board optimization algorithms.
draw_csect | 811 | works | disable | feature | Draw cross section and layer map.
draw_fab | 291 | works | buildin | feature | Draw the fab layer (for various exporters).
draw_fontsel | 158 | works | disable | feature | Draw the font selector GUI
draw_pnp | 323 | works | buildin | feature | Draw a Pick-aNd-Place helper layer
drc_query | 2311 |  | buildin | feature | Scriptable DRC based on query()
emsim | 96 | WIP | disable-all | feature | electro-magnetic simulation using external process emsim-rnd
expfeat | 31 | works | disable | feature | Staging plugin for experimenting with new actions and dialogs before getting them into core or other plugins
export_bom | 359 | works | buildin | export | Export BoM (Bill of Materials) with configurable templates
export_c_draw | 317 | works | disable-all | export | C code usable in pcb-rnd preview draw
export_debug | 316 | works | disable-all | export | simple positional file format to compare exports
export_dxf | 2350 | works | buildin | export | Export dxf
export_emsim | 203 | WIP | disable-all | export | export in emsim-rnd tEDAx format for electromagnetic simulation
export_excellon | 577 | works | buildin | export | Export to excellon drill/cnc files
export_fidocadj | 283 | WIP | buildin | export | Export to FidoCadJ format (.fcd)
export_gcode | 309 | WIP | buildin | export | Export to gcode
export_gerber | 916 | works | buildin | export | Export to gerber
export_hpgl | 881 | works | buildin | export | draw one pen or one file per layer in thin-draw mode
export_ipcd356 | 385 | works | buildin | export | IPC-D-356 Netlist export.
export_lpr | 35 | works | buildin | export | Export to lpr (using export_ps to generate postscript)
export_oldconn | 235 | works | buildin | export | Export subc/terminal connection map in an old, custom file format
export_openems | 3208 | WIP | buildin | export | Export copper to OpenEMS simulation
export_openscad | 844 | works | buildin | export | Export openscad
export_png | 834 | works | buildin | export | Export to png, gif and jpeg
export_ps | 820 | works | buildin | export | Export postscript or embedded postscript.
export_stat | 322 | works | buildin | export | Export various board statistics in lihata format
export_stl | 1419 | works | buildin | export | Export triangulated surface model
export_svg | 324 | works | buildin | export | Scalable Vector Graphics (SVG) exporter
export_vfs_fuse | 312 | WIP | disable | export | Export all data and config of a board to a FUSE mountable filesystem
export_vfs_mc | 149 | WIP | disable | export | Export all data and config of a board to GNU mc
export_xy | 1212 | works | buildin | export | Template based export of XY centroid subcircuit data e.g. for pick & place.
extedit | 356 | works | buildin | feature | invoke external program to edit parts of the current board
exto_std | 1449 | WIP | buildin | feature | Extended objects for: line-of-vias, dimension
fontmode | 1064 | works | buildin | feature | Font editing actions.
fp_board | 120 | WIP | buildin | fp | Footprint: load a board and expose all the unique subcircuits on that board as a footprint library
fp_fs | 526 | works | buildin | fp | Footprint: file system based implementation. Used to be called Newlib: load footprints from directories. Run external processes for the parametric footprints.
fp_wget | 700 | works | buildin | fp | Footprint: get static (file) footprints from the web, e.g. from http://gedasymbols.org
import_accel_net | 211 | works | buildin | import | Import the netlist and footprints from a Accel netlist.
import_calay | 239 | works | buildin | import | Import the netlist and footprints from a calay netlist.
import_edif | 3637 | works | buildin | import | Import plugin for netlists in the EDIF format.
import_fpcb_nl | 224 | works | buildin | import | Import the netlist and footprints from freepcb format (exported by e.g. easyeda)
import_gnetlist | 184 | works | buildin | import | Import gEDA/gschem schematics running gnetlist
import_hpgl | 154 | works | buildin | import | Emulate a plotter and import the plot as lines, arcs and polygons.
import_ipcd356 | 456 | works | buildin | import | IPC-D-356 Netlist and pad centroid import
import_ltspice | 593 | works | buildin | import | Import the netlist and footprints from an ltspice .asc and .net pair of files
import_mentor_sch | 549 | works | buildin | import | Import Mentor Graphics Design Capture from flattened .edf netlist, using a parts conversion table.
import_mucs | 142 | works | buildin | import | Import lines and vias from MUCS unixplot .pl files
import_net_action | 81 | works | buildin | import | Import the netlist and footprints from an action script.
import_net_cmd | 73 | works | buildin | import | Import schematics/netlist by running a commandline
import_netlist | 151 | works | buildin | import | Import plugin for netlists in the classic pcb netlist format.
import_orcad_net | 186 | works | buildin | import | Import the netlist and footprints from a Orcad netlist.
import_pads_net | 209 | works | buildin | import | Import the netlist and footprints from a PADS netlist.
import_protel_net | 222 | works | buildin | import | Import the netlist and footprints from a Protel netlist.
import_sch2 | 560 | works | buildin | import | Imports footprints and netlist data from the schematics (or some other source).
import_sch_rnd | 127 | works | buildin | import | Import sch-rnd schematics or sch-rnd/Ringdove project, running sch-rnd
import_tinycad | 225 | works | buildin | import | Import the netlist and footprints from a tinycad netlist.
import_ttf | 759 | works | buildin | import | Import outline ttf glyphs into the current font, either as polygons or lines
io_altium | 2572 | WIP | buildin | io | load boards in the altium PcbDoc format
io_autotrax | 1597 | works | buildin | io | Import and export autotrax layouts and footprints.
io_bxl | 3007 | works | buildin | io | load footprints from the BXL format.
io_dsn | 2469 | works | buildin | io | Load and save specctra DSN files, import SES
io_eagle | 4598 | works | buildin | io | Load the design from eagle's xml and binary formats.
io_easyeda | 3722 | works | buildin | io | load boards and footprints in the EasyEDA
io_hyp | 4109 | works | buildin | io | Import plugin for hyperlynx geometry (no polygons yet).
io_kicad | 3696 | works | buildin | io | Load and save the design and footprints in Kicad's s-expression format - this is the new, currently preferred format in Kicad.
io_kicad_legacy | 914 | works | buildin | io | Export the design and footprints in Kicad's legacy format.
io_lihata | 5231 | works | buildin | io | Load and save the design and footprints in the lihata board format.
io_mentor_cell | 1841 | WIP | disable | io | Load Mentor Graphics cell footprint library and make footprints available (e.g. for fp_board)
io_pads | 4087 | works | buildin | io | load boards in the PADS ASCII format
io_pcb | 3486 | works | buildin | io | Load and save the design and footprints in the original gEDA/PCB text format.
io_tedax | 3739 | works | buildin | io | Import and export tEDAx netlists and footprints.
jostle | 421 | works | buildin | feature | Pushes lines out of the way.
lib_compat_help | 1445 | works | buildin | lib | a library of functions providing a simplified API compatibility layer, mainly for I/O plugins
lib_formula | 748 | works | buildin | lib | simple formulas, for efficient rule-of-thumb calculations
lib_hid_pcbui | 2459 | works | disable-all | lib | PCB related helper functions for GUI HIDs
lib_netmap | 1465 | works | disable-all | lib | create disposable cross-reference maps between all objects and all nets
lib_polyhelp | 1493 | works | buildin | lib | functions to help plugins processing polygons and PolyHatch() action
lib_vfs | 458 | works | disable-all | lib | Retrieve, sort and query data under VFS export plugins
millpath | 495 | WIP | disable | feature | Calculate and simulate toolpath for milling away opper
mincut | 893 | works | buildin | feature | Use the minimal cut algorithm to indicate shorts: instead of highlighting two random pins/pads, try to highlight the least number of objects that connect the two networks.
oldactions | 363 | works | disable | feature | Random collection of old/obsolete actions. Bell(): audible feedback, DumpLibrary(): print footprint library on stdout, a set of debug actions useful for writing pcb scripts: Debug(), DebugXY(), Return(). Old plugin actions to toggle or set settings that are now accessible via the unified config system (vendordrill, djopt)
order | 2041 | works | buildin | feature | order boards through the Internet
order_pcbway | 1185 | works | buildin | feature | order from PCBWay through the Internet
polycombine | 206 | works | buildin | feature | The selected polygons are combined together according to the ordering of their points.
polystitch | 95 | works | buildin | feature | The polygon under the cursor (based on closest-corner) is stitched together with the polygon surrounding it on the same layer. Use with pstoedit conversions where there's a "hole" in the shape - select the hole.
propedit | 2504 | works | buildin | feature | List and edit properties of a group of objects.
puller | 1823 | works | buildin | feature | Pull traces to minimize their length.
query | 6184 | works | buildin | feature | pcb-rnd query language: execute expressions on objects and rules for the programmed drc.
rbs_routing | 1931 | works | buildin | feature | Assisted routing by stretching traces as if they were rubber bands
renumber | 313 | works | buildin | feature | Renumber subcircuits (renaming them) and generate a text file for back annotation.
report | 1018 | works | buildin | feature | Report() and ReportObject() actions - print a report about design objects.
rubberband_orig | 1242 | works | buildin | feature | The original rubberband code.
serpentine | 375 | WIP | disable-all | feature | Create serpentines on existing lines.
shand_cmd | 165 | works | buildin | feature | vi-like command shorthands (1..3 character long commands)
shape | 926 | works | buildin | feature | Generate objects of regular shape (regular polygons, circle, round rect)
show_netnames | 317 | works | buildin | feature | display network names as overlay when zoomed in enough
smartdisperse | 164 | works | buildin | feature | Improve the initial dispersion of subcircuits by choosing an order based on the netlist, rather than the arbitrary subcircuit order. This isn't the same as a global autoplace, it's more of a linear autoplace. It might make some useful local groupings. For example, you should not have to chase all over the board to find the resistor that goes with a given LED.
suite | 407 | works | buildin | feature | Suite integration: features spanning across tools in the suite
teardrops | 423 | works | buildin | feature | Draw teardrops on pins.
tool_std | 2356 | works | buildin | feature | The basic set of PCB drawing tools
trimesh | 67 | WIP | buildin | feature | generic surface triangulation
vendordrill | 605 | works | buildin | feature | Vendor drill mapping.

### Classes

Each plugin implements a class (rarely a set of classes). Classes are:

name | description
--- | ---
feature | random features directly accessible for the user, usually actions
lib | support code library for other plugins (core doesn't depend on these); functionality not directly accessible for the user but other plugins may depend on it
hid | Human Interface Device: interactive user interface, usually GUI
import | load alien formats into the design space
export | save (parts of) the design space in alien formats
fp | footprint (element) library implementation
io | native file format (save & load) implementation

### Status

Common status column values mean:

name | description
--- | ---
works | production quality code - configures, compiles, tested
WIP | work in progress: the plugin may be avaialble for testing but is not yet production quality
abandoned | unmaintained plugin; may be in working condition but there is no developer supporting it
deprecated | legacy plugin scheduled for removal; may still work but will soon be removed; if your workflow depends on it, please report ASAP

### Plugin dependency map