/[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.16 - (show annotations) (download)
Wed Mar 5 02:16:20 2003 UTC (16 years, 3 months ago) by wcc
Branch: MAIN
Changes since 1.15: +151 -162 lines
* More doc stuff.
* Reverted last snprintf changes.
* Cosmetic changes to addpatch.

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

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23