# Plugins

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

## Plugins in 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.

## Write a plugin

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

&plugin_api.en.xml;

### Compile plugin

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

### Load plugin into WeeChat

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

### Plugin example

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;
    }

&plugin_irc.en.xml;

&plugin_fifo.en.xml;

&plugin_xfer.en.xml;