1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<?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 plugins interface (API) and
the default scripts plugins (Perl, Python, Ruby, Lua), 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 have some variables and functions (mandatory,
without them the plugin can't load):
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>char plugin_name[]</literal></entry>
<entry>plugin name</entry>
</row>
<row>
<entry><literal>char plugin_version[]</literal></entry>
<entry>plugin version</entry>
</row>
<row>
<entry><literal>char plugin_description[]</literal></entry>
<entry>short description of plugin</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 (t_weechat_plugin *plugin)</literal></entry>
<entry>
function called when plugin is loaded, must return
PLUGIN_RC_OK if successful, PLUGIN_RC_KO if error
(if error, plugin will NOT be loaded)
</entry>
</row>
<row>
<entry><literal>void weechat_plugin_end (t_weechat_plugin *plugin)</literal></entry>
<entry>function called when plugin is unloaded</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
&plugin_api.en.xml;
<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 channel (ok that's not very useful,
but that's just an example!):
<screen>
#include <stdlib.h>
#include "weechat-plugin.h"
char plugin_name[] = "Double";
char plugin_version[] = "0.1";
char plugin_description[] = "Test plugin for WeeChat";
/* "/double" command manager */
int double_cmd (t_weechat_plugin *plugin, int argc, char **argv,
char *handler_args, void *handler_pointer)
{
if (argv[2] && (argv[2][0] != '/'))
{
plugin->exec_command (plugin, NULL, NULL, argv[2]);
plugin->exec_command (plugin, NULL, NULL, argv[2]);
}
return PLUGIN_RC_OK;
}
int weechat_plugin_init (t_weechat_plugin *plugin)
{
plugin->cmd_handler_add (plugin, "double",
"Display two times a message",
"msg",
"msg: message to display two times",
NULL,
&double_cmd,
NULL, NULL);
return PLUGIN_RC_OK;
}
void weechat_plugin_end (t_weechat_plugin *plugin)
{
/* nothing done here */
}
</screen>
</para>
</section>
</section>
&plugin_charset.en.xml;
&plugin_scripts.en.xml;
</chapter>
|
