1README for Apache 1.2 Example Module
2[April, 1997]
3
4The files in the src/modules/example directory under the Apache
5distribution directory tree are provided as an example to those that
6wish to write modules that use the Apache API.
7
8The main file is mod_example.c, which illustrates all the different
9callback mechanisms and call syntaces.  By no means does an add-on
10module need to include routines for all of the callbacks - quite the
11contrary!
12
13The example module is an actual working module.  If you link it into
14your server, enable the "example-handler" handler for a location, and then
15browse to that location, you will see a display of some of the tracing
16the example module did as the various callbacks were made.
17
18To include the example module in your server, follow the steps below:
19
20    1. Uncomment the "Module example_module" line near the bottom of
21       the src/Configuration file.  If there isn't one, add it; it
22       should look like this:
23
24       Module example_module        modules/example/mod_example.o
25
26    2. Run the src/Configure script ("cd src; ./Configure").  This will
27       build the Makefile for the server itself, and update the
28       src/modules/Makefile for any additional modules you have
29       requested from beneath that subdirectory.
30
31    3. Make the server (run "make" in the src directory).
32
33To add another module of your own:
34
35    A. mkdir src/modules/mymodule
36    B. cp src/modules/example/* src/modules/mymodule
37    C. Modify the files in the new directory
38    D. Follow steps [1] through [3] above, with appropriate changes.
39
40To activate the example module, include a block similar to the
41following in your srm.conf file:
42
43    <Location /example-info>
44	SetHandler example-handler
45    </Location>
46
47As an alternative, you can put the following into a .htaccess file and
48then request the file "test.example" from that location:
49
50    AddHandler example-handler .example
51
52After reloading/restarting your server, you should be able to browse
53to this location and see the brief display mentioned earlier.
54