APXS: Information

["Ralf S. Engelschall" <rs...@engelschall.com>]

[I'm an idiot, I prepared this information as the respository commit message
yesterday but today I've forgot it to use when comitting, so here it to give a
an impression for what "apxs" is good for]

APache eXtenSion tool (APXS) 
============================

Now that we have major-platform shared object support and an installation
system (APACI) for the complete package, we the first time can really think
about an _OFF-SOURCE_ extension mechanism for Apache like Perl's DynaLoader
mechanism.

For the impatient:

  $ apxs -c -i -a -c mod_foo.c
  gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_foo.c
  ld -Bshareable -o mod_foo.so mod_foo.o
  cp mod_foo.so /tmp/apache/libexec/mod_foo.so
  chmod 755 /tmp/apache/libexec/mod_foo.so
  [activating module `foo' in /tmp/apache/etc/httpd.conf]
  $ apachectl restart
  /tmp/apache/sbin/apachectl restart: httpd not running, trying to start
  [Tue Mar 31 11:27:55 1998] [debug] mod_so.c(303): loaded module foo_module
  /tmp/apache/sbin/apachectl restart: httpd started
  $ _

The idea in detail is the following:

  1. Apache is installed as usual but mod_so is enabled, even if no modules
     are actually enabled for shared object support (you can additionally
     enable one, of course).

       $ gunzip <apache-1.3.tar.gz
       $ cd apache-1.3
       $ ./configure --prefix=/tmp/apache --enable-module=so
       $ make install

  2. Now after installation under /tmp/apache/include all Apache C header
     files stay and in /tmp/apache/sbin/apxs the new APXS tool exists.

  3. Some time later you have a mod_foo.c at hand somewhere (especially:
     _OUTSIDE_ the Apache source tree) which you want to bring into your
     Apache installation to extend its functionality. So, you use "apxs" to
     compile it into a DSO file mod_foo.so without fiddling around with the
     compiler flags yourself by running
     
       $ apxs -c mod_foo.c
       gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_foo.c
       ld -Bshareable -o mod_foo.so mod_foo.o
       $ _
     
     and then install it into /tmp/apache/libexec/mod_foo.so plus an
     activating LoadModule entry for /tmp/apache/etc/httpd.conf via

       $ apxs -i -a mod_foo.so
       cp mod_foo.so /tmp/apache/libexec/mod_foo.so
       chmod 755 /tmp/apache/libexec/mod_foo.so
       [activating Module `foo' in /tmp/apache/etc/httpd.conf]
       $ _

     Of course you can do both steps with a single command by just combining
     the -c and -i options:

     $ apxs -c -i -a mod_foo.c
     gcc -fpic -DSHARED_MODULE -I/tmp/apache/include -c mod_foo.c
     ld -Bshareable -o mod_foo.so mod_foo.o
     cp mod_foo.so /tmp/apache/libexec/mod_foo.so
     chmod 755 /tmp/apache/libexec/mod_foo.so
     [activating Module `foo' in /tmp/apache/etc/httpd.conf]
     $ _

  4. Now you can immediately fire up Apache with the new module:

     $ /tmp/apache/sbin/apachectl start
     [Mon Mar 30 15:34:08 1998] [debug] mod_so.c(303): loaded module foo_module
     /tmp/apache/sbin/apachectl start: httpd started
     $_

The "apxs" tool also supports complex extensions like PHP3 which have
pre-build objects:

   $ apxs -o libphp3.so mod_php3.o libmodphp3-so.a
   $ apxs -i libphp3.so

To bring this useful extension into Apache just minimal changes are required
to APACI and src/Configure to be able to create the "apxs" tool, install it
and additionally make sure the Apache C header files are present under
runtime.

Oh, and one more interesting idea stolen from Perl's xsubpp for those users
who work with Apache the first time and needs some initial help:

  $ apxs -g -n foo
  Creating [DIR]  foo
  Creating [FILE] foo/Makefile
  Creating [FILE] foo/mod_foo.c
  $ _

Then in the created subdir foo/ you find a template module and a corresponding
Makefile which immediately can be used to play with the APXS mechanism:

  $ cd foo
  $ make reload
  apxs -c   mod_foo.c
  gcc -funsigned-char -DHIDE -fpic -DSHARED_MODULE -I/tmp/apache/include  -c
  mod_foo.c
  ld -Bshareable -o mod_foo.so mod_foo.o
  apxs -i -a -n 'foo' mod_foo.so
  cp mod_foo.so /tmp/apache/libexec/mod_foo.so
  chmod 755 /tmp/apache/libexec/mod_foo.so
  apachectl restart
  [Mon Mar 30 15:34:08 1998] [debug] mod_so.c(303): loaded module foo_module
  /tmp/apache/sbin/apachectl restart: httpd restarted
  $ _

Greetings,
                                       Ralf S. Engelschall
                                       rse@engelschall.com
                                       www.engelschall.com