2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_example.xml.meta">
25 <name>mod_example</name>
26 <description>Illustrates the Apache module API</description>
27 <status>Experimental</status>
28 <sourcefile>mod_example.c</sourcefile>
29 <identifier>example_module</identifier>
32 <p>Some files in the <code>modules/experimental</code> directory
33 under the Apache distribution directory tree are provided as an
34 example to those that wish to write modules that use the Apache
37 <p>The main file is <code>mod_example.c</code>, which
38 illustrates all the different callback mechanisms and call
39 syntaxes. By no means does an add-on module need to include
40 routines for all of the callbacks - quite the contrary!</p>
42 <p>The example module is an actual working module. If you link
43 it into your server, enable the "example-handler" handler for a
44 location, and then browse to that location, you will see a
45 display of some of the tracing the example module did as the
46 various callbacks were made.</p>
49 <section id="compiling"><title>Compiling the example module</title>
51 <p>To include the example module in your server, follow the
56 Run <program>configure</program> with <code>--enable-example</code>
59 <li>Make the server (run "<code>make</code>").</li>
62 <p>To add another module of your own:</p>
65 <li><code>cp modules/experimental/mod_example.c
66 modules/new_module/<em>mod_myexample.c</em></code></li>
68 <li>Modify the file.</li>
70 <li>Create <code>modules/new_module/config.m4</code>.
72 <li>Add <code>APACHE_MODPATH_INIT(new_module)</code>.</li>
73 <li>Copy APACHE_MODULE line with "example" from
74 <code>modules/experimental/config.m4</code>.</li>
75 <li>Replace the first argument "example" with <em>myexample</em>.</li>
76 <li>Replace the second argument with brief description of your module.
77 It will be used in <code>configure --help</code>.</li>
78 <li>If your module needs additional C compiler flags, linker flags or
79 libraries, add them to CFLAGS, LDFLAGS and LIBS accordingly.
80 See other <code>config.m4</code> files in modules directory for
82 <li>Add <code>APACHE_MODPATH_FINISH</code>.</li>
86 <li>Create <code>module/new_module/Makefile.in</code>.
87 If your module doesn't need special build instructions,
88 all you need to have in that file is
89 <code>include $(top_srcdir)/build/special.mk</code>.</li>
91 <li>Run ./buildconf from the top-level directory.</li>
93 <li>Build the server with --enable-myexample</li>
98 <section id="using"><title>Using the <code>mod_example</code> Module</title>
100 <p>To activate the example module, include a block similar to
101 the following in your <code>httpd.conf</code> file:</p>
103 <Location /example-info><br />
104 SetHandler example-handler<br />
108 <p>As an alternative, you can put the following into a <a
109 href="core.html#accessfilename"><code>.htaccess</code></a> file
110 and then request the file "test.example" from that location:</p>
112 AddHandler example-handler .example
115 <p>After reloading/restarting your server, you should be able
116 to browse to this location and see the brief display mentioned
122 <description>Demonstration directive to illustrate the Apache module
124 <syntax>Example</syntax>
125 <contextlist><context>server config</context>
126 <context>virtual host</context><context>directory</context>
127 <context>.htaccess</context></contextlist>
130 <p>The <directive>Example</directive> directive just sets a demonstration
131 flag which the example module's content handler displays. It
132 takes no arguments. If you browse to an URL to which the
133 example content-handler applies, you will get a display of the
134 routines within the module and how and in what order they were
135 called to service the document request. The effect of this
136 directive one can observe under the point "<code>Example
137 directive declared here: YES/NO</code>".</p>