Mercurial > pidgin

comparison doc/plugin-ids.dox @ 20808:e96daf6bc511

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
I basically copied most of http://developer.pidgin.im/wiki/CHowTo/ChoosingPluginIds into plugin-ids.dox.
author Will Thompson <will.thompson@collabora.co.uk>
date Sun, 07 Oct 2007 19:07:06 +0000
parents e0613cf8c493
children
comparison
equal deleted inserted replaced
20807:e0613cf8c493 20808:e96daf6bc511
1 /** @page plugin-ids Plugin IDs 1 /** @page plugin-ids Plugin IDs
2 2
3 @section Introduction 3 @section Introduction
4 Every plugin contains a unique identifier to prevent duplicate plugin 4 Every plugin contains a unique identifier to prevent duplicate plugin
5 loading and conflicts. This, which will be called a plugin ID from here 5 loading and conflicts. Third-party plugins (that is, plugins written by
6 on, must follow a specific format. This format categorizes a plugin and 6 anyone who is not a libpurple, Pidgin, or Finch developer) are expected
7 makes duplicate IDs unlikely. 7 to use a plugin ID that follows a specific format. This format
8 8 categorizes plugins and makes duplicate IDs highly unlikely.
9 9
10 @section Format 10 @section Format
11 The basic format of a plugin ID is as follows: 11 The basic format of a plugin ID is as follows:
12 12
13 <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt> 13 <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt>
14 14
15 The @em type indicator specifies the type of plugin. This must be one 15 The @em type indicator specifies the type of plugin. This must be one
16 of the following: 16 of the following:
17 17
18 - core - Core plugin, capable of being loaded in any program using 18 - core - A core libpurple plugin, capable of being loaded in any
19 libpurple. It must not use any UI-specific code. 19 program using libpurple. Core plugins may not contain any
20 - prpl - Protocol plugin, providing additional protocols to 20 UI-specific code.
21 connect to. 21 - prpl - A protocol plugin. This is a special type of core plugin,
22 - lopl - Loader plugin, which loads scripts as plugins (like Perl 22 which provides libpurple the ability to connect to
23 or TCL). 23 another IM or chat network.
24 - gtk - GTK+ 2.x plugin. It may use GTK+ code, but cannot use any 24 - lopl - A loader plugin, which loads scripts as plugins. Perl and
25 window toolkit code (such as X11 or Win32). 25 Tcl plugins are made possible by loader plugins.
26 - gtk-x11 - GTK+ 2.x plugin using X11 code. 26 - gtk - A GTK+ 2.x (a.k.a. Pidgin) plugin. These plugins may use
27 - gtk-win32 - GTK+ 2.x plugin using Win32 code. 27 GTK+ code, but may not use window toolkit code, such as
28 - qpe - Gaim for Qtopia plugin. 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.
29 37
30 The @em username must be a unique identifier for that person. It 38 The @em username must be a unique identifier for you. It
31 @em should be your SourceForge ID. Do @em not leave this field 39 @em should be your http://developer.pidgin.im Trac user ID. Failing that, you
32 blank. 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!
33 43
34 The @em pluginname is the name of your plugin. It can be whatever you like, 44 The @em pluginname is the name of your plugin. It is usually all
35 though it's common to keep it all lowercase. Do not use spaces! If you 45 lowercase letters and matches the static plugin ID (the first argument to
36 want a space, use a '-'. Please do not put a version indicator in the ID. 46 the PURPLE_INIT_PLUGIN() macro call), although it can be anything you
37 The PurplePlugin structure already has a field for this. 47 like. Do @em not include version information in the plugin ID--the
48 #PurplePluginInfo structure already has a field for this.
38 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.
39 91
40 @section plugin-db Plugin Database 92 @section plugin-db Plugin Database
41 Although it doesn't exist yet, in time there will be a plugin database 93 Although it doesn't exist yet, in time there will be a plugin database
42 on the Pidgin website, where users can download and install new plugins. 94 on the Pidgin website, where users can download and install new plugins.
43 Plugins will be accessed by your plugin ID, which is one reason why it 95 Plugins will be accessed by your plugin ID, which is one reason why it