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 Libera 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 101