/[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.17 - (hide annotations) (download)
Thu Dec 11 00:49:10 2003 UTC (15 years, 6 months ago) by wcc
Branch: MAIN
Changes since 1.16: +1 -1 lines
* 2004 copyright.

1 wcc 1.14 Eggdrop Module Information
2 wcc 1.16 Last revised: March 04, 2003
3 wcc 1.14 _________________________________________________________________
4    
5     Eggdrop Module Information
6 segfault 1.1
7 fabian 1.3
8 wcc 1.16 The purpose of this document is to show you how to download, install, create,
9     and submit modules.
10 fabian 1.3
11 wcc 1.16 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 wcc 1.14
19    
20 wcc 1.16 1. What are modules?
21 wcc 1.14
22 wcc 1.16 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 wcc 1.14
26    
27 wcc 1.16 2. Why use modules?
28 wcc 1.14
29 wcc 1.16 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 wcc 1.14
33 fabian 1.3
34 wcc 1.16 3. How to install a module
35 fabian 1.3
36 wcc 1.16 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 fabian 1.3
40 wcc 1.16 1. Download and un-tar the Eggdrop source code.
41 fabian 1.3
42 wcc 1.16 2. Place the new module in its own directory (named 'modulename') in
43     modules/.
44 fabian 1.3
45 wcc 1.16 3. Run ./bootstrap (from eggdrop1.7.x/).
46 fabian 1.3
47 wcc 1.16 4. Run ./configure.
48 tothwolf 1.8
49 wcc 1.16 5. Type 'make'.
50 fabian 1.3
51 wcc 1.16 6. Copy the compiled module file (modulename.so) into your bot's modules
52     folder.
53 fabian 1.3
54 wcc 1.16 7. Add the module to the autoload section of the config file.
55 fabian 1.3
56 wcc 1.16 8. Rehash or restart your bot.
57 fabian 1.3
58 wcc 1.16 To view your currently loaded modules, type '.module'.
59 fabian 1.3
60    
61 wcc 1.16 4. Modules included with Eggdrop
62 fabian 1.3
63 wcc 1.16 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 fabian 1.3
69 wcc 1.16 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 tothwolf 1.8
73 wcc 1.16 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 tothwolf 1.8
77 wcc 1.16 console This module provides storage of console settings when you exit
78     the bot or type .store on the partyline.
79 fabian 1.3
80 wcc 1.16 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 segfault 1.1
84 wcc 1.16 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 segfault 1.1
87 wcc 1.16 javascript This module provides JaveScript scripting support.
88 fabian 1.3
89 wcc 1.16 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 wcc 1.15
94 wcc 1.16 perlscript This module provides Perl scripting support.
95 wcc 1.15
96 wcc 1.16 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 fabian 1.3
100 wcc 1.16 tclscript This module provides Tcl scripting support.
101 fabian 1.3
102 wcc 1.16 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 fabian 1.3
109 segfault 1.1
110 wcc 1.16 5. Programming modules
111 fabian 1.3
112 wcc 1.16 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 tothwolf 1.8
115 wcc 1.16 1. Create a modules/MODULE directory in your Eggdrop directory (where MODULE
116     is the module name) and cd to it.
117 segfault 1.1
118 wcc 1.16 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 segfault 1.1
121 wcc 1.16 3. Next, you want to create a file called MODULE.c (MODULE is the module
122     name again).
123 segfault 1.1
124 wcc 1.16 4. You must include the following in your source code:
125 segfault 1.1
126 wcc 1.16 a. #define MODULE_NAME "module-name"
127 fabian 1.3
128 wcc 1.16 This should be defined to the same name you will be using when you load
129     your module.
130 johoho 1.5
131 wcc 1.16 b. #include "lib/eggdrop/module.h"
132 fabian 1.3
133 wcc 1.16 This provides access to Eggdrop's global function table. Examine
134     src/mod/module.h closely to find a list of functions available.
135 fabian 1.3
136 wcc 1.16 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 fabian 1.3
139 wcc 1.16 d. eggdrop_t *egg = NULL;
140 fabian 1.3
141 wcc 1.16 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 fabian 1.3
144 wcc 1.16 5. Every module must also have the following functions:
145 tothwolf 1.8
146 wcc 1.16 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 tothwolf 1.8
150 wcc 1.16 Throughout step 5, MODULE refers to the module name. Note that
151     "MODULE_NAME" should literally be "MODULE_NAME".
152 wcc 1.14
153 wcc 1.16 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 tothwolf 1.8
161 wcc 1.16 module_register(MODULE_NAME, MODULE_table, MAJOR, MINOR);
162 wcc 1.14
163 wcc 1.16 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 wcc 1.14
168 wcc 1.16 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 wcc 1.14
175 wcc 1.16 Any other initialization stuff you desire should also be included in
176     this function. See below for various things you can do.
177 wcc 1.14
178 wcc 1.16 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 tothwolf 1.8
183 wcc 1.16 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 tothwolf 1.8
196 wcc 1.16 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 wcc 1.14
201 wcc 1.16 module_undepend(MODULE_NAME);
202     This lets Eggdrop know your module no longer depends on any other
203     modules.
204 wcc 1.14
205 wcc 1.16 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 wcc 1.14
209 wcc 1.16 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 fabian 1.4
213    
214 wcc 1.16 6. What to do with a module?
215 wcc 1.14
216 wcc 1.16 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 wcc 1.14 _________________________________________________________________
223    
224 wcc 1.17 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23