weechat/doc/en/plugins.en.xml

<?xml version="1.0" encoding="iso-8859-1"?>

<!--

WeeChat documentation (english version)

Copyright (c) 2003-2008 by FlashCode <flashcode@flashtux.org>

This manual is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This manual is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

-->

<chapter id="chapPlugins">
  <title>Plugins</title>
  
  <para>
    This chapter describes WeeChat plugin API and default plugins provided with
    WeeChat.
  </para>
  
  <section id="secPluginsInWeeChat">
    <title>Plugins in WeeChat</title>
    
    <para>
      A plugin is a C program which can call WeeChat functions defined in
      an interface.
    </para>
    
    <para>
      This C program does not need WeeChat sources to compile and can be
      dynamically loaded into WeeChat with command
      <command>/plugin</command>.
    </para>
    
    <para>
      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.
    </para>
    
  </section>
  
  <section id="secWriteAPlugin">
    <title>Write a plugin</title>
    
    <para>
      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.
    </para>
    
    <para>
      The plugin must use some mandatory macros (to define some variables)
      and some functions (without them the plugin can't load):
      
      <informaltable colsep="0" frame="none">
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Macro</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>WEECHAT_PLUGIN_NAME</literal></entry>
              <entry>plugin name</entry>
            </row>
            <row>
              <entry><literal>WEECHAT_PLUGIN_DESCRIPTION</literal></entry>
              <entry>short description of plugin</entry>
            </row>
            <row>
              <entry><literal>WEECHAT_PLUGIN_VERSION</literal></entry>
              <entry>plugin version</entry>
            </row>
            <row>
              <entry><literal>WEECHAT_PLUGIN_WEECHAT_VERSION</literal></entry>
              <entry>
                target WeeChat version where plugin will run (warning: plugin
                will not run on any other WeeChat version!)
              </entry>
            </row>
            <row>
              <entry><literal>WEECHAT_PLUGIN_LICENSE</literal></entry>
              <entry>plugin license</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
      
      <informaltable colsep="0" frame="none">
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Function</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry><literal>int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[])</literal></entry>
              <entry>
                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)
              </entry>
            </row>
            <row>
              <entry><literal>int weechat_plugin_end (struct t_weechat_plugin *plugin)</literal></entry>
              <entry>function called when plugin is unloaded</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </para>
    
    <section id="secCompilePlugin">
      <title>Compile plugin</title>
      
      <para>
        Compile does not need WeeChat sources, only file
        "<literal>weechat-plugin.h</literal>".
      </para>
      
      <para>
        To compile a plugin which has one file "toto.c" (under GNU/Linux):
<screen>
<prompt>$ </prompt><userinput>gcc -fPIC -Wall -c toto.c</userinput>
<prompt>$ </prompt><userinput>gcc -shared -fPIC -o libtoto.so toto.o</userinput>
</screen>
      </para>
      
    </section>
    
    <section id="secLoadPlugin">
      <title>Load plugin into WeeChat</title>
      
      <para>
        Copy "libtoto.so" file into system plugins directory (for example
        "<literal>/usr/local/lib/weechat/plugins</literal>") or into
        user's plugins directory (for example
        "<literal>/home/xxxxx/.weechat/plugins</literal>").
      </para>
      
      <para>
        Under WeeChat:
        <screen><userinput>/plugin load toto</userinput></screen>
      </para>
      
    </section>
    
    <section id="secPluginExample">
      <title>Plugin example</title>
      
      <para>
        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!):
<screen>
#include &lt;stdlib.h&gt;

#include "weechat-plugin.h"

WEECHAT_PLUGIN_NAME("double");
WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat");
WEECHAT_PLUGIN_AUTHOR("FlashCode &lt;flashcode@flashtux.org&gt;");
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 &gt; 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,
                          &amp;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;
}
</screen>
      </para>
      
    </section>
    
    <!-- &plugin_api.en.xml; -->
    
  </section>
  
  <section id="secDefaultPlugins">
    <title>Default plugins</title>
    
    &plugin_irc.en.xml;
    
    <!-- &plugin_charset.en.xml; -->
    
    &plugin_fifo.en.xml;
    
    <!-- &plugin_scripts.en.xml; -->
    
  </section>
  
</chapter>