doc/plugin-ids.dox

   1 /** @page plugin-ids Plugin IDs
   2
   3  @section Introduction
   4   Every plugin contains a unique identifier to prevent duplicate plugin
   5   loading and conflicts. Third-party plugins (that is, plugins written by
   6   anyone who is not a libpurple, Pidgin, or Finch developer) are expected
   7   to use a plugin ID that follows a specific format. This format
   8   categorizes plugins and makes duplicate IDs highly unlikely.
   9
  10  @section Format
  11   The basic format of a plugin ID is as follows:
  12
  13   <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt>
  14
  15   The @em type indicator specifies the type of plugin. This must be one
  16   of the following:
  17
  18     - core      - A core libpurple plugin, capable of being loaded in any
  19                   program using libpurple. Core plugins may not contain any
  20                   UI-specific code.
  21     - prpl      - A protocol plugin. This is a special type of core plugin,
  22                   which provides libpurple the ability to connect to
  23                   another IM or chat network.
  24     - lopl      - A loader plugin, which loads scripts as plugins. Perl and
  25                   Tcl plugins are made possible by loader plugins.
  26     - gtk       - A GTK+ 2.x (a.k.a. Pidgin) plugin. These plugins may use
  27                   GTK+ code, but may not use window toolkit code, such as
  28                   X11, Win32, Cocoa, or Carbon.
  29     - gtk-x11   - A GTK+ 2.x plugin that uses X11 code. These plugins may
  30                   use both GTK+ code and X11 code, allowing to hook into
  31                   features specific to X11.
  32     - gtk-win32 - A GTK+ plugin that uses Win32 code. These plugins may use
  33                   both GTK+ code and Win32 code, allowing to hook into
  34                   features available on Windows.
  35     - gnt       - A GNT (a.k.a. Finch) plugin. These plugins may use GNT code.
  36     - qpe       - A plugin for the (now-abandoned) Qutopia user interface.
  37
  38   The @em username must be a unique identifier for you. It
  39   @em should be your http://developer.pidgin.im Trac user ID. Failing that, you
  40   could use your SourceForge user ID or your Freenode IRC nickname, if you
  41   have either. The http://developer.pidgin.im Trac user ID is preferred.
  42   Do @em not leave this field blank!
  43
  44   The @em pluginname is the name of your plugin. It is usually all
  45   lowercase letters and matches the static plugin ID (the first argument to
  46   the PURPLE_INIT_PLUGIN() macro call), although it can be anything you
  47   like. Do @em not include version information in the plugin ID--the
  48   #PurplePluginInfo structure already has a field for this.
  49
  50  @section nospaces One Last Rule for Plugin IDs
  51
  52   The last rule of plugin IDs is the most important of all. Plugin IDs may
  53   @em NOT contain spaces. If you need a space, use another hyphen (-).
  54
  55  @section exceptions Exceptions to the Rule
  56
  57   As with any rule there are exceptions. If you browse through the source
  58   tree you will see that the plugins we distribute with the Pidgin source
  59   do not contain a username field. This is because while one developer may
  60   have written each specific plugin, the plugins are maintained
  61   collectively by the entire development team. This lack of a username
  62   field is also an indicator that the plugin is one of our plugins and not
  63   a third-party plugin.
  64
  65   Another exception to the rule is the <a
  66   href="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin
  67   Pack</a>. All plugins whose lives started in the Purple Plugin Pack use
  68   <tt>"plugin_pack"</tt> for the username field to indicate origination in
  69   the Purple Plugin Pack.
  70
  71   These two exceptions are mentioned here for completeness. We don't
  72   encourage breaking the conventions set forth by the rules outlined above.
  73
  74  @section examples Examples of Well-Chosen Plugin IDs
  75
  76   The following is a list of well-chosen Plugin IDs listing a few good examples.
  77
  78     - <tt>"gtk-amc_grim-guifications"</tt> - This is the plugin ID for the
  79                                              Guifications 2.x plugin.
  80     - <tt>"gtk-rlaager-album"</tt> - This is the plugin ID for the Album
  81                                      plugin, which is now part of the
  82                                      Purple Plugin Pack. Its ID follows the
  83                                      rules because its life started prior
  84                                      to its inclusion in the Plugin Pack.
  85     - <tt>"core-rlaager-irchelper"</tt> - This is the plugin ID for the IRC
  86                                           Helper plugin, which is now part
  87                                           of the Purple Plugin Pack. Its ID
  88                                           follows the rules because its
  89                                           life started prior to its
  90                                           inclusion in the Plugin Pack.
  91
  92  @section plugin-db Plugin Database
  93   Although it doesn't exist yet, in time there will be a plugin database
  94   on the Pidgin website, where users can download and install new plugins.
  95   Plugins will be accessed by your plugin ID, which is one reason why it
  96   must be unique.
  97
  98  */
  99
 100 // vim: syntax=c.doxygen tw=75 et