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

Annotation of /eggdrop1.9/doc/MODULES

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


Revision 1.15 - (hide 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 wcc 1.14 Eggdrop Module Information
2 wcc 1.15 Last revised: March 01, 2003
3 wcc 1.14 _________________________________________________________________
4    
5     Eggdrop Module Information
6 segfault 1.1
7 fabian 1.3
8     INDEX
9    
10 wcc 1.14 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 fabian 1.3
32 wcc 1.14 III. How to install a module
33 fabian 1.3
34 wcc 1.14 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 fabian 1.3
38 wcc 1.14 1. Download and un-tar the Eggdrop source code.
39 fabian 1.3
40 wcc 1.14 2. Place the new module in its own directory (named 'modulename') in
41     modules/.
42 fabian 1.3
43 wcc 1.14 3. Run ./bootstrap (from eggdrop1.7.x/).
44 fabian 1.3
45 wcc 1.14 4. Run ./configure.
46 tothwolf 1.8
47 wcc 1.14 5. Type 'make'.
48 fabian 1.3
49 wcc 1.14 6. Copy the compiled module file (modulename.so) into your bot's modules
50     folder.
51 fabian 1.3
52 wcc 1.14 7. Add 'loadmodule modulename' to your eggdrop.conf file (do not
53     add the .so suffix).
54 fabian 1.3
55 wcc 1.14 8. Rehash or restart your bot.
56 fabian 1.3
57 wcc 1.14 To see your currently running modules type '.module'.
58 fabian 1.3
59    
60 wcc 1.14 IV. Modules included with eggdrop
61 fabian 1.3
62 wcc 1.14 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 fabian 1.3
68 wcc 1.14 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 tothwolf 1.8
72 wcc 1.14 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 tothwolf 1.8
76 wcc 1.14 console This module provides storage of console settings when you exit
77     the bot or type .store on the partyline.
78 fabian 1.3
79 wcc 1.14 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 segfault 1.1
83 wcc 1.14 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 wcc 1.15
86     javascript This module provides JaveScript scripting support.
87 segfault 1.1
88 wcc 1.14 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 fabian 1.3
93 wcc 1.15 perlscript This module provides Perl scripting support.
94    
95 wcc 1.14 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 wcc 1.15
99     tclscript This module provides Tcl scripting support.
100 fabian 1.3
101 wcc 1.14 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 fabian 1.3
107    
108 wcc 1.14 V. Programming modules
109 segfault 1.1
110 wcc 1.14 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 fabian 1.3
115 wcc 1.14 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 tothwolf 1.8
118 wcc 1.14 (a) Create a modules/<module> directory in your Eggdrop tree and cd to it.
119 segfault 1.1
120 wcc 1.14 (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 segfault 1.1
123 wcc 1.14 (c) Next, you want to create a file called MODULE.c (MODULE is the module
124     name).
125 segfault 1.1
126 wcc 1.14 (1) Things you need to include in your source code:
127 segfault 1.1
128 wcc 1.14 (i) #define MODULE_NAME "module-name"
129 fabian 1.3
130 wcc 1.14 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 johoho 1.5
133 wcc 1.14 (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 fabian 1.3
137 wcc 1.14 (iii) #include "lib/eggdrop/module.h"
138 fabian 1.3
139 wcc 1.14 This provides all the accessible functions in Eggdrop. Examine
140     lib/eggdrop/module.h closely to find a list of functions available.
141 fabian 1.3
142 wcc 1.14 (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 fabian 1.3
146 wcc 1.14 (v) eggdrop_t *egg = NULL;
147 fabian 1.3
148 wcc 1.14 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 tothwolf 1.8
152 wcc 1.14 (2) CORE functions every module needs.
153 tothwolf 1.8
154 wcc 1.14 *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 tothwolf 1.8
160 fabian 1.3 (i) char *MODULE_start(Function *func_table)
161 wcc 1.14 - 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 tothwolf 1.8
187 fabian 1.3 (ii) static Function *MODULE_table = {
188 segfault 1.1 MODULE_start,
189 tothwolf 1.8 MODULE_close,
190     MODULE_expmem,
191     MODULE_report,
192     any_other_functions,
193     you_want_to_export
194     };
195 wcc 1.14 Ok, it's not a function. It's a list of functions which any
196 tothwolf 1.8 other module can call up, so you can provide services for other
197 wcc 1.14 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 tothwolf 1.8
201 fabian 1.3 (iii) static char *MODULE_close ()
202 wcc 1.14 - 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 fabian 1.4
220 wcc 1.14 (3) AVAILABLE FUNCTIONS
221 fabian 1.4
222 wcc 1.14 WRITE ME
223    
224    
225     VI. What to do with a module?
226 fabian 1.4
227 guppy 1.12 If you have written a module and feel that you wish to share it with the
228 wcc 1.14 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