Changes between Version 1 and Version 2 of CHowTo/ChoosingPluginIds

Timestamp:

Jul 16, 2007, 6:04:26 PM (17 years ago)

Author:

John Bailey

Comment:

Migrated the document on Plugin IDs from the doxygen-generated stuff to the wiki

CHowTo/ChoosingPluginIds

@@ -1 +1 @@
 = Choosing Plugin IDs =
-This page is a placeholder pending the completion of this document.
+Until now, the documents in the How-To series have focused primarily on basic introductions to facilities provided by the plugin API and the necessary things to make libpurple recognize a plugin.  Now, however, we're going to take a step back and discuss another important topic, choosing a plugin ID.  A plugin's ID is a unique identifier that prevents loading of duplicate plugins and conflicts.
+
+Third-party plugins (that is, plugins written by anyone who is not a libpurple, Pidgin, or Finch developer) are expected to use a plugin ID that follows a specific format.  This format categorizes plugins and makes duplicate ID's highly unlikely.
+
+[[TOC(inline,noheading)]]
+
+== Format of the ID ==
+The format of a plugin ID for third-party plugins is as follows:
+
+  ''type''-''username''-''pluginname''
+
+The ''type'' indicator specifies the type of plugin.  This is one of the following:
+ * '''core''' - A core libpurple plugin, capable of being loaded in any program using libpurple.  Core plugins may not contain any UI-specific code.
+ * '''prpl''' - A protocol plugin.  This is a special type of core plugin, which provides libpurple the ability to connect to another IM or chat network.
+ * '''lopl''' - A loader plugin, which loads scripts as plugins.  Perl and Tcl plugins are made possible by loader plugins.
+ * '''gtk''' - A GTK+ 2.x plugin.  These plugins may use GTK+ code, but may not use window toolkit code, such as X11, Win32, Cocoa, or Carbon.
+ * '''gtk-x11''' - A GTK+ 2.x plugin that uses X11 code.  These plugins may use both GTK+ code and X11 code, allowing to hook into features specific to X11.
+ * '''gtk-win32''' - A GTK+ plugin that uses Win32 code.  These plugins may use both GTK+ code and Win32 code, allowing to hook into features available on Windows.
+ * '''gnt''' - A GNT (a.k.a. Finch) plugin.  These plugins may use GNT code.
+ * '''qpe''' - A plugin for the (now-abandoned) Qutopia user interface.
+
+The ''username'' must be a unique identifier for you.  It ''should'' be your developer.pidgin.im Trac user ID.  Failing that, you could use your !SourceForge user ID or your freenode IRC nickname, if you have either.  The developer.pidgin.im Trac user ID is preferred.
+
+The ''pluginname'' is the name of your plugin.  It is usually all lowercase letters and matches the static plugin ID (the first argument to the `PURPLE_INIT_PLUGIN()` macro call), although it can be anything you like.  Do '''''__NOT__''''' include version information in the plugin ID--the `PurplePluginInfo` structure already has a field for this.
+
+== One Last Rule for Plugin ID's ==
+The last rule of plugin ID's is the most important of all.  Plugin ID's may '''''NOT''''' contain spaces.  If you need a space, use another hyphen (`-`).
+
+== Exceptions to the Rule ==
+As with any rule there are exceptions.  If you browse through the source tree you will see that the plugins we distribute with the Pidgin source do not contain a username field.  This is because while one developer may have written each specific plugin, the plugins are maintained collectively by the entire development team.  This lack of a username field is also an indicator that the plugin is one of our plugins and not a third-party plugin.
+
+Another exception to the rule is the [http://plugins.guifications.org/trac/wiki/PluginPack Purple Plugin Pack].  All plugins whose lives started in the Purple Plugin Pack use "plugin_pack" for the username field to indicate origination in the Purple Plugin Pack.
+
+These two exceptions are mentioned here for completeness.  We don't encourage breaking the conventions set forth by the rules outlined above.
+
+== Examples of Well-Chosen Plugin ID's ==
+The following is a list of well-chosen Plugin ID's listing a few good examples.
+ * "'''gtk-amc_grim-guifications'''" - This is the plugin ID for the [http://plugins.guifications.org/trac/wiki/Guifications Guifications 2.x] plugin.
+ * "'''gtk-rlaager-album'''" - This is the plugin ID for the Album plugin, which is now part of the Purple Plugin Pack.  Its ID follows the rules because its life started prior to its inclusion in the Plugin Pack.
+ * "'''core-rlaager-irchelper'''" - This is the plugin ID for the IRC Helper plugin, which is now part of the Purple Plugin Pack.  Its ID follows the rules because its life started prior to its inclusion in the Plugin Pack.
+
+== What Now? ==
+Now that you've selected a proper plugin ID, continue reading the [wiki:CHowTo C Plugin How-To] series!