doc/plugins/contrib/verboserpc.mdwn

   1 [[!meta author="spalax"]]
   2 [[!template id=plugin name=verboserpc author="[[Louis|spalax]]"]]
   3
   4 Debugging [external plugins](//ikiwiki.info/plugins/write/external/) is a pain, as soon as RPC is involved… This kind-of plugin tries to make it a little bit less painful.
   5
   6 It acts as a proxy between Ikiwiki and the plugin (which, for the record, is an executable program communicating with Ikiwiki using [XML RPC](http://www.xmlrpc.com/) on standard input/output), and logs everithing on standard error.
   7
   8 [[!toc]]
   9
  10 # Example
  11
  12 A sample output of a wiki compilation is shown below.
  13
  14     $ ikiwiki --setup wiki.setup --refresh --verbose
  15     -> <?xml version="1.0" encoding="utf-8"?><methodCall><methodName>import</methodName><params></params></methodCall>
  16     <- <?xml version='1.0'?>
  17     <- <methodCall>
  18     <- <methodName>hook</methodName>
  19     <- <params>
  20     <- <param>
  21     <- <value><string>call</string></value>
  22     <- </param>
  23     <- <param>
  24     <- <value><string>getsetup</string></value>
  25     <- </param>
  26     <- <param>
  27     <- <value><string>type</string></value>
  28     <- </param>
  29     <- <param>
  30     <- <value><string>getsetup</string></value>
  31     <- </param>
  32     <- <param>
  33     <- <value><string>id</string></value>
  34     <- </param>
  35     <- <param>
  36     <- <value><string>foo</string></value>
  37     <- </param>
  38     <- <param>
  39     <- <value><string>last</string></value>
  40     <- </param>
  41     <- <param>
  42     <- <value><boolean>0</boolean></value>
  43     <- </param>
  44     <- </params>
  45     <- </methodCall>
  46     -> <?xml version="1.0" encoding="utf-8"?><methodResponse><params><param><value><string>1</string></value></param></params></methodResponse>
  47     <- <?xml version='1.0'?>
  48     <- <methodResponse>
  49     <- <params>
  50     <- <param>
  51     <- <value><struct>
  52     <- <member>
  53     <- <name>null</name>
  54     <- <value><string></string></value>
  55     <- </member>
  56     <- </struct></value>
  57     <- </param>
  58     <- </params>
  59     <- </methodResponse>
  60     rebuilding wiki..
  61     scanning index.mdwn
  62     building index.mdwn
  63     done
  64
  65 # Enabling the plugin
  66
  67 Let us say you want to debug a plugin `foo`, located somewhere in your [`libdir`](https://ikiwiki.info/plugins/install/).
  68
  69 1. Do not not enable plugin `foo` in the ikiwiki setup file.
  70 2. Create a symbolic link named `foo.verboserpc` in one of your `libdir`, linking to the `verboserpc` plugin.
  71 3. In your setup file, enable plugin `foo.verboserpc`.
  72
  73 That's it. When called, the `verboserpc` plugin will be called as `foo.verboserpc`, and will run program `foo`, while transmitting (to Ikiwiki and `foo`) and logging (to standard error) any input/output.
  74
  75 # Does it work?
  76
  77 Well… External plugins are still a pain to debug, even with this tool. If your plugin is written using python, and you are using the [`proxy`](http://source.ikiwiki.branchable.com/?p=source.git;a=blob;f=plugins/proxy.py;h=b61eb466c8d47ef839fc24e5d0ba54be3a9b23fa;hb=HEAD), it might be useless, since this proxy already have an option to log RPC calls (by giving `debug_fn=sys.stderr.write` as an option to the constructor of [`IkiWikiProcedureProxy`](http://source.ikiwiki.branchable.com/?p=source.git;a=blob;f=plugins/proxy.py;h=b61eb466c8d47ef839fc24e5d0ba54be3a9b23fa;hb=HEAD#l217)).
  78
  79 I am not sure that this plugin is the solution to the problem of debugging external plugins. I am still publishing it here, hoping that someone might improve it into something useful…
  80
  81 # Download and install
  82
  83 Code and documentation can be found here : [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/VerboseRPC]].