/[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.14 - (hide annotations) (download)
Sun Feb 23 09:52:46 2003 UTC (16 years, 3 months ago) by wcc
Branch: MAIN
Changes since 1.13: +167 -282 lines
* More docs.

1 wcc 1.14 Eggdrop Module Information
2     Last revised: February 23, 2003
3     _________________________________________________________________
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 segfault 1.1
86 wcc 1.14 notes This module provides support for storing of notes for users
87     from each other. Note sending between currently online users
88     is supported in the core, this is only for storing the notes
89     for later retrieval.
90 fabian 1.3
91 wcc 1.14 server This module provides the core server support. You have to load
92     this if you want your bot to come on IRC. Not loading this is
93     equivalent to the old NO_IRC define.
94 fabian 1.3
95 wcc 1.14 uptime This module reports uptime statistics to http://uptime.eggheads.org.
96     Go look and see what your uptime is! It takes about 9 hours to
97     show up, so if your bot isn't listed, try again later. See
98     doc/settings/mod.uptime for more information, including details
99     on what information is sent to the uptime server.
100 fabian 1.3
101    
102 wcc 1.14 V. Programming modules
103 segfault 1.1
104 wcc 1.14 WARNING:
105     This section is very likely to be out of date. It was not updated for
106     quite some time. The most reliable way to learn about module
107     programming is to take a deep look at the other available modules.
108 fabian 1.3
109 wcc 1.14 Note: This is for a simple module of 1 source file. If you're doing a
110     multiple source file module, you shouldn't need to read this anyway. ;)
111 tothwolf 1.8
112 wcc 1.14 (a) Create a modules/<module> directory in your Eggdrop tree and cd to it.
113 segfault 1.1
114 wcc 1.14 (b) Create a `Makefile' for your module (see the example module distributed
115     with the bot). This should ensure that your module gets compiled.
116 segfault 1.1
117 wcc 1.14 (c) Next, you want to create a file called MODULE.c (MODULE is the module
118     name).
119 segfault 1.1
120 wcc 1.14 (1) Things you need to include in your source code:
121 segfault 1.1
122 wcc 1.14 (i) #define MODULE_NAME "module-name"
123 fabian 1.3
124 wcc 1.14 You MUST use this. It's required by several short cuts in the
125     code, and it's got to be the name you will be using in .loadmod
126 johoho 1.5
127 wcc 1.14 (ii) #define MAKING_MODULENAME
128     You MUST also include this, or else the module won't work.
129     MODULENAME is the name of your module (MODULE_NAME), but in caps.
130 fabian 1.3
131 wcc 1.14 (iii) #include "lib/eggdrop/module.h"
132 fabian 1.3
133 wcc 1.14 This provides all the accessible functions in Eggdrop. Examine
134     lib/eggdrop/module.h closely to find a list of functions available.
135 fabian 1.3
136 wcc 1.14 (iv) #include any other standard C header files you might need
137     (Note stdio.h, string.h, stdlib.h, and sys/types.h are already
138     included).
139 fabian 1.3
140 wcc 1.14 (v) eggdrop_t *egg = NULL;
141 fabian 1.3
142 wcc 1.14 This variable provides access to all the Eggdrop functions; without
143     it, you can't call any Eggdrop functions (heck, the module won't
144     even load).
145 tothwolf 1.8
146 wcc 1.14 (2) CORE functions every module needs.
147 tothwolf 1.8
148 wcc 1.14 *SIDENOTE* I suggest that in a single source file module, you define all
149     functions/variables (except global and module_start) as static. This will
150     drastically reduce the size of modules on decent systems.
151    
152     In each of these cases, MODULE refers to the name of your module.
153 tothwolf 1.8
154 fabian 1.3 (i) char *MODULE_start(Function *func_table)
155 wcc 1.14 - This function is called when the module is first loaded.
156     You MUST do several things in this function:
157     (a) egg = func_table; (so you can make Eggdrop calls)
158    
159     (b) module_register(MODULE_NAME, MODULE_table, major, minor);
160     This records details about the module for other modules and
161     Eggdrop itself to access. Major is a major version number,
162     minor is a minor version number, and MODULE_table is a
163     function table (see below).
164    
165     (c) module_depend(MODULE_NAME, "another-module", major, minor);
166     This lets Eggdrop know that your module NEEDS "another-module"
167     of major version 'major' and at least minor version 'minor'
168     to run, and hence should try to load it if it's not already
169     here. This will return 1 on success, or 0 if it can't be done
170     (at which stage you should return an error).
171    
172     (d) Any other initialization stuff you desire should be included
173     in this function. See below for various things you can do.
174    
175     (e) a return value of some sort
176     Returning NULL implies the module loaded successfully,
177     therefor the bot can continue. Returning a non-NULL STRING
178     is an error message. The module (and any other dependant
179     modules) will stop loading and an error will be returned.
180 tothwolf 1.8
181 fabian 1.3 (ii) static Function *MODULE_table = {
182 segfault 1.1 MODULE_start,
183 tothwolf 1.8 MODULE_close,
184     MODULE_expmem,
185     MODULE_report,
186     any_other_functions,
187     you_want_to_export
188     };
189 wcc 1.14 Ok, it's not a function. It's a list of functions which any
190 tothwolf 1.8 other module can call up, so you can provide services for other
191 wcc 1.14 modules (e.g. transfer has raw_dcc_send in it's table to allow
192     the filesys to send files to others). The first 4 functions are
193     FIXED. You MUST have them; they provide important system info.
194 tothwolf 1.8
195 fabian 1.3 (iii) static char *MODULE_close ()
196 wcc 1.14 - This is called when the module is unloaded.
197     Apart from tidying any relevant data (I suggest you be thorough,
198     we don't want any trailing garbage from modules), you MUST do
199     the following:
200    
201     (a) module_undepend(MODULE_NAME);
202     This lets Eggdrop know your module no longer depends on any
203     other modules.
204    
205     (b) Return a value. NULL implies success; any non-NULL STRING
206     implies that the module cannot be unloaded for some reason,
207     and hence the bot should not unload it (see blowfish for
208     an example).
209    
210     (iv) static void MODULE_report (int idx)
211     This should provide a relatively short report of the module's
212     status (for .module/.status).
213 fabian 1.4
214 wcc 1.14 (3) AVAILABLE FUNCTIONS
215 fabian 1.4
216 wcc 1.14 WRITE ME
217    
218    
219     VI. What to do with a module?
220 fabian 1.4
221 guppy 1.12 If you have written a module and feel that you wish to share it with the
222 wcc 1.14 rest of the Eggdrop community, upload it to the incoming directory on
223     incoming.eggheads.org (/incoming/modules/1.7). Place a nice descriptive
224     text (modulename.desc) with it, and it'll make its way to the modules
225     directory on ftp.eggheads.org. Don't forget to mention in your text file
226     which version Eggdrop the module is written for.
227     _________________________________________________________________
228    
229     Copyright (C) 1999, 2000, 2001, 2002, 2003 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23