This chapter describes WeeChat plugin API and default plugins provided with WeeChat.

A plugin is a C program which can call WeeChat functions defined in an interface. This C program does not need WeeChat sources to compile and can be dynamically loaded into WeeChat with command /plugin. The plugin has to be a dynamic library, for dynamic loading by operating system. Under GNU/Linux, the file has ".so" extension, ".dll" under Windows.

The plugin has to include "weechat-plugin.h" file (available in WeeChat source code). This file defines structures and types used to communicate with WeeChat. The plugin must use some mandatory macros (to define some variables) and some functions (without them the plugin can't load): Macro Description WEECHAT_PLUGIN_NAME plugin name WEECHAT_PLUGIN_DESCRIPTION short description of plugin WEECHAT_PLUGIN_VERSION plugin version WEECHAT_PLUGIN_WEECHAT_VERSION target WeeChat version where plugin will run (warning: plugin will not run on any other WeeChat version!) WEECHAT_PLUGIN_LICENSE plugin license Function Description int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[]) function called when plugin is loaded, must return WEECHAT_RC_OK if successful, WEECHAT_RC_ERROR if error (if error, plugin will NOT be loaded), argc/argv are arguments for plugin (given on command line by user) int weechat_plugin_end (struct t_weechat_plugin *plugin) function called when plugin is unloaded

Compile does not need WeeChat sources, only file "weechat-plugin.h". To compile a plugin which has one file "toto.c" (under GNU/Linux): $ gcc -fPIC -Wall -c toto.c $ gcc -shared -fPIC -o libtoto.so toto.o

Copy "libtoto.so" file into system plugins directory (for example "/usr/local/lib/weechat/plugins") or into user's plugins directory (for example "/home/xxxxx/.weechat/plugins"). Under WeeChat: /plugin load toto

Full example of plugin, which adds a /double command, which displays two times arguments on current buffer, or execute two times a command (ok that's not very useful, but that's just an example!): #include <stdlib.h> #include "weechat-plugin.h" WEECHAT_PLUGIN_NAME("double"); WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat"); WEECHAT_PLUGIN_AUTHOR("FlashCode <flashcode@flashtux.org>"); WEECHAT_PLUGIN_VERSION("0.1"); WEECHAT_PLUGIN_WEECHAT_VERSION("0.2.7"); WEECHAT_PLUGIN_LICENSE("GPL3"); struct t_weechat_plugin *weechat_plugin = NULL; /* "/double" command manager */ int double_cmd (void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol) { /* make C compiler happy */ (void) argv; if (argc > 1) { weechat_command (NULL, argv_eol[1]); weechat_command (NULL, argv_eol[1]); } return WEECHAT_RC_OK; } int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[]) { weechat_plugin = plugin; weechat_hook_command ("double", "Display two times a message", "msg", "msg: message to display two times", NULL, &double_cmd, NULL); return WEECHAT_RC_OK; } int weechat_plugin_end (struct t_weechat_plugin *plugin) { /* nothing done here */ (void) plugin; return WEECHAT_RC_OK; }