/[cvs]/eggdrop1.9/doc/MODULES
ViewVC logotype

Contents of /eggdrop1.9/doc/MODULES

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.15 - (show annotations) (download)
Sat Mar 1 08:25:58 2003 UTC (16 years, 7 months ago) by wcc
Branch: MAIN
Changes since 1.14: +7 -1 lines
* Tcl cleanups.
* More documentation.

1 Eggdrop Module Information
2 Last revised: March 01, 2003
3 _________________________________________________________________
4
5 Eggdrop Module Information
6
7
8 INDEX
9
10 I. What are modules?
11 II. Why use modules?
12 III. How to install a module
13 IV. Modules included with Eggdrop
14 V. Programming modules
15 VI. What to do with a module?
16
17
18 I. What are modules?
19
20 Modules are portions of code which are loaded separately to the bot itself
21 and provide extra services. For example, the filesys module provides the
22 entire file system.
23
24
25 II. Why use modules?
26
27 Modules allow C coders to add their own enhancements to the bot without
28 recompiling the whole thing, and without increasing the size of the Eggdrop
29 core.
30
31
32 III. How to install a module
33
34 Please note that these are only basic instructions for compiling and
35 installing a module. Please read any and all directions included with
36 the module you wish to install.
37
38 1. Download and un-tar the Eggdrop source code.
39
40 2. Place the new module in its own directory (named 'modulename') in
41 modules/.
42
43 3. Run ./bootstrap (from eggdrop1.7.x/).
44
45 4. Run ./configure.
46
47 5. Type 'make'.
48
49 6. Copy the compiled module file (modulename.so) into your bot's modules
50 folder.
51
52 7. Add 'loadmodule modulename' to your eggdrop.conf file (do not
53 add the .so suffix).
54
55 8. Rehash or restart your bot.
56
57 To see your currently running modules type '.module'.
58
59
60 IV. Modules included with eggdrop
61
62 blowfish Eggdrop can encrypt your userfile, so users can have secure
63 passwords. Please note that when you change your encryption
64 method later (i.e. using other modules like a md5 module),
65 you can't use your current userfile anymore. Eggdrop will not
66 start without an encryption module.
67
68 channels This module provides channel related support for the bot.
69 Without it, you won't be able to make the bot join a channel
70 or save channel specific userfile information.
71
72 compress This module provides provides support for file compression.
73 This allows the bot to transfer compressed user files and,
74 therefore, save a significant amount of bandwidth.
75
76 console This module provides storage of console settings when you exit
77 the bot or type .store on the partyline.
78
79 filesys This module provides an area within the bot where users can
80 store files. With this module, the bot is usable as a file
81 server.
82
83 irc This module provides basic IRC support for your bot. You have
84 to load this if you want your bot to come on IRC.
85
86 javascript This module provides JaveScript scripting support.
87
88 notes This module provides support for storing of notes for users
89 from each other. Note sending between currently online users
90 is supported in the core, this is only for storing the notes
91 for later retrieval.
92
93 perlscript This module provides Perl scripting support.
94
95 server This module provides the core server support. You have to load
96 this if you want your bot to come on IRC. Not loading this is
97 equivalent to the old NO_IRC define.
98
99 tclscript This module provides Tcl scripting support.
100
101 uptime This module reports uptime statistics to http://uptime.eggheads.org.
102 Go look and see what your uptime is! It takes about 9 hours to
103 show up, so if your bot isn't listed, try again later. See
104 doc/settings/mod.uptime for more information, including details
105 on what information is sent to the uptime server.
106
107
108 V. Programming modules
109
110 WARNING:
111 This section is very likely to be out of date. It was not updated for
112 quite some time. The most reliable way to learn about module
113 programming is to take a deep look at the other available modules.
114
115 Note: This is for a simple module of 1 source file. If you're doing a
116 multiple source file module, you shouldn't need to read this anyway. ;)
117
118 (a) Create a modules/<module> directory in your Eggdrop tree and cd to it.
119
120 (b) Create a `Makefile' for your module (see the example module distributed
121 with the bot). This should ensure that your module gets compiled.
122
123 (c) Next, you want to create a file called MODULE.c (MODULE is the module
124 name).
125
126 (1) Things you need to include in your source code:
127
128 (i) #define MODULE_NAME "module-name"
129
130 You MUST use this. It's required by several short cuts in the
131 code, and it's got to be the name you will be using in .loadmod
132
133 (ii) #define MAKING_MODULENAME
134 You MUST also include this, or else the module won't work.
135 MODULENAME is the name of your module (MODULE_NAME), but in caps.
136
137 (iii) #include "lib/eggdrop/module.h"
138
139 This provides all the accessible functions in Eggdrop. Examine
140 lib/eggdrop/module.h closely to find a list of functions available.
141
142 (iv) #include any other standard C header files you might need
143 (Note stdio.h, string.h, stdlib.h, and sys/types.h are already
144 included).
145
146 (v) eggdrop_t *egg = NULL;
147
148 This variable provides access to all the Eggdrop functions; without
149 it, you can't call any Eggdrop functions (heck, the module won't
150 even load).
151
152 (2) CORE functions every module needs.
153
154 *SIDENOTE* I suggest that in a single source file module, you define all
155 functions/variables (except global and module_start) as static. This will
156 drastically reduce the size of modules on decent systems.
157
158 In each of these cases, MODULE refers to the name of your module.
159
160 (i) char *MODULE_start(Function *func_table)
161 - This function is called when the module is first loaded.
162 You MUST do several things in this function:
163 (a) egg = func_table; (so you can make Eggdrop calls)
164
165 (b) module_register(MODULE_NAME, MODULE_table, major, minor);
166 This records details about the module for other modules and
167 Eggdrop itself to access. Major is a major version number,
168 minor is a minor version number, and MODULE_table is a
169 function table (see below).
170
171 (c) module_depend(MODULE_NAME, "another-module", major, minor);
172 This lets Eggdrop know that your module NEEDS "another-module"
173 of major version 'major' and at least minor version 'minor'
174 to run, and hence should try to load it if it's not already
175 here. This will return 1 on success, or 0 if it can't be done
176 (at which stage you should return an error).
177
178 (d) Any other initialization stuff you desire should be included
179 in this function. See below for various things you can do.
180
181 (e) a return value of some sort
182 Returning NULL implies the module loaded successfully,
183 therefor the bot can continue. Returning a non-NULL STRING
184 is an error message. The module (and any other dependant
185 modules) will stop loading and an error will be returned.
186
187 (ii) static Function *MODULE_table = {
188 MODULE_start,
189 MODULE_close,
190 MODULE_expmem,
191 MODULE_report,
192 any_other_functions,
193 you_want_to_export
194 };
195 Ok, it's not a function. It's a list of functions which any
196 other module can call up, so you can provide services for other
197 modules (e.g. transfer has raw_dcc_send in it's table to allow
198 the filesys to send files to others). The first 4 functions are
199 FIXED. You MUST have them; they provide important system info.
200
201 (iii) static char *MODULE_close ()
202 - This is called when the module is unloaded.
203 Apart from tidying any relevant data (I suggest you be thorough,
204 we don't want any trailing garbage from modules), you MUST do
205 the following:
206
207 (a) module_undepend(MODULE_NAME);
208 This lets Eggdrop know your module no longer depends on any
209 other modules.
210
211 (b) Return a value. NULL implies success; any non-NULL STRING
212 implies that the module cannot be unloaded for some reason,
213 and hence the bot should not unload it (see blowfish for
214 an example).
215
216 (iv) static void MODULE_report (int idx)
217 This should provide a relatively short report of the module's
218 status (for .module/.status).
219
220 (3) AVAILABLE FUNCTIONS
221
222 WRITE ME
223
224
225 VI. What to do with a module?
226
227 If you have written a module and feel that you wish to share it with the
228 rest of the Eggdrop community, upload it to the incoming directory on
229 incoming.eggheads.org (/incoming/modules/1.7). Place a nice descriptive
230 text (modulename.desc) with it, and it'll make its way to the modules
231 directory on ftp.eggheads.org. Don't forget to mention in your text file
232 which version Eggdrop the module is written for.
233 _________________________________________________________________
234
235 Copyright (C) 1999, 2000, 2001, 2002, 2003 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23