Groundwork provides an abstraction layer so the same code can be compiled as a CGI or Apache module. This layer consists of include files, defines and libraries. Apache 1.3 and 2.0 are supported.

To compile your application as a CGI, include cgimodule.h. To compile it as an Apache module, include apachemodule.h. These include files define the MAIN, APISTRUCT and RETURNVAL macros. You will use those macros later in your code. When including apachemodule.h, you must define the NAME macro. You will use NAME when configuring Apache to use your module.

At link time, you can generate a CGI by linking against libgroundwork and an Apache module by linking against libgroundwork-apache.

This is the code for sendpage.cgi; a very simple program which displays the associated html template.

#include <groundwork/groundwork.h>

extern "C" {

#ifdef APACHEMODULE
#define NAME sendpage
#include <groundwork/apachemodule.h>
#else
#include <groundwork/cgimodule.h>
#endif

MAIN {
        groundwork      gw(APISTRUCT);
        gw.execute();
        return RETURNVAL;
}

}

Note how NAME is defined before including apachemodule.h, how MAIN is used instead of int main(int argc, char **argv), how APISTRUCT as passed as an argument to gw and how RETURNVAL is returned.

Compiling like this:

c++ -static -s -pedantic -I/usr/local/firstworks/include -o sendpage.cgi sendpage.C -L/usr/local/firstworks/lib -lgroundwork

generates a CGI called sendpage.cgi.

Compiling like this:

c++ -I/usr/local/firstworks/include -DAPACHEMODULE -DEAPI -I/usr/include/apache -c sendpage.C
ld -G -o mod_sendpage.so sendpage.o -L/usr/local/firstworks/lib -lgroundwork-apache

generates an Apache 1.3 module called mod_sendpage.so.

Compiling like this:

c++ -I/usr/local/firstworks/include -DAPACHEMODULE -DAPACHE2 -DEAPI -I/usr/include/apache -c sendpage.C
ld -G -o mod_sendpage.so sendpage.o -L/usr/local/firstworks/lib -lgroundwork-apache

generates an Apache 2.0 module called mod_sendpage.so. (note the extra -DAPACHE2 directive)

Note that on some platforms you must use ld -shared instead of ld -G.

When configuring Apache to use your new module. The LoadModule directive uses NAME_module and the AddModule directive uses mod_NAME.c

In the example, NAME was defined as sendpage. So in the httpd.conf file, directives like the following are used to include the module:

LoadModule sendpage_module    lib/apache/mod_sendpage.so
AddModule mod_sendpage.c

These directives assume that mod_sendpage.so is installed below the ServerRoot in lib/apache. If it's installed somewhere else, you should substitute lib/apache with the appropriate pathname.

To configure apache to use a module instead of a CGI, use a combination of the Location and SetHandler directives. For example, to handle the URL /myapplication/modules/sendpage.cgi with mod_sendpage.so, use the following directives.

<Location /myapplication/modules/sendpage.cgi>
SetHandler sendpage
</Location>

In the example, NAME was defined as sendpage. So sendpage is used with the SetHandler directive.