apxs(8)                                                   apxs(8)

NAME
       apxs - APache eXtenSion tool

SYNOPSIS
       apxs -g -n modname

       apxs -q query ...

       apxs  -c  [ -o dsofile ] [ -I incdir ] [ -D name=value ] [
       -L libdir ] [  -l  libname  ]  [  -Wc,compiler-flags  ]  [
       -Wl,linker-flags ] files ...

       apxs -i [ -n modname ] [ -a ] [ -A ] dsofile ...

DESCRIPTION
       apxs  is a tool for building and installing extension mod-
       ules for the Apache  HyperText  Transfer  Protocol  (HTTP)
       server.  This  is  achieved  by  building a dynamic shared
       object (DSO) from one or more source or object files which
       then  can  be  loaded into the Apache server under runtime
       via the LoadModule directive from mod_so.

       So to use this extension mechanism your  platform  has  to
       support  the  DSO feature and your Apache httpd binary has
       to be built with the mod_so module.  The apxs  tool  auto-
       matically  complains  if  this  is  not the case.  You can
       check this yourself by manually running the command

         $ httpd -l

       The module mod_so should be part of  the  displayed  list.
       If  these requirements are fulfilled you can easily extend
       your Apache server's functionality by installing your  own
       modules  with  the  DSO mechanism by the help of this apxs
       tool:

         $ apxs -i -a -c mod_foo.c
         gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
         ld -Bshareable -o mod_foo.so mod_foo.o
         cp mod_foo.so /path/to/apache/libexec/mod_foo.so
         chmod 755 /path/to/apache/libexec/mod_foo.so
         [activating module `foo' in /path/to/apache/etc/httpd.conf]
         $ apachectl restart
         /path/to/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
         /path/to/apache/sbin/apachectl restart: httpd started
         $ _

       The arguments files can be  any  C  source  file  (.c),  a
       object  file (.o) or even a library archive (.a). The apxs
       tool automatically recognizes these extensions and  autom-
       taically  used  the  C  source files for compilation while
       just using the object and archive files  for  the  linking
       phase.  But when using such pre-compiled objects make sure
       they are compiled for position independend code  (PIC)  to
       be  able  to  use  them  for  a  dynamically loaded shared
       object.  For instance with GCC you always just have to use
       -fpic.   For  other C compilers consult its manual page or
       at watch for the flags apxs uses  to  compile  the  object
       files.

       For more details about DSO support in Apache read the doc-
       umentation of mod_so or perhaps  even  read  the  src/mod-
       ules/standard/mod_so.c source file.

OPTIONS
       Common options:

       -n modname  This  explicitly  sets the module name for the
                   -i  (install)  and  -g  (template  generation)
                   option.  Use  this  to  explicitly specify the
                   module name.  For option -g this is  required,
                   for option -i the apxs tool tries to determine
                   the name from the source or (as a fallback) at
                   least by guessing it from the filename.

       Query options:

       -q          Performs  a  query  for apxs's knowledge about
                   certain settings. The query parameters can  be
                   one or more of the following strings:
                     CC              TARGET
                     CFLAGS          SBINDIR
                     CFLAGS_SHLIB    INCLUDEDIR
                     LD_SHLIB        LIBEXECDIR
                     LDFLAGS_SHLIB   SYSCONFDIR
                     LIBS_SHLIB
                   Use  this  for  manually determining settings.
                   For instance use
                     INC=-I`apxs -q INCLUDEDIR`
                   inside your own Makefiles if you  need  manual
                   access to Apache's C header files.

       Template Generation options:

       -g          This generates a subdirectory name (see option
                   -n) and  there  two  files:  A  sample  module
                   source file named mod_name.c which can be used
                   as a template for creating your own modules or
                   as  a  quick  start  for playing with the APXS
                   mechanism.  And a corresponding  Makefile  for
                   even  easier build and installing of this mod-
                   ule.

       DSO compilation options:

       -c          This indicates the compilation  operation.  It
                   first  compiles  the  C  source  files (.c) of
                   files into corresponding object files (.o) and
                   then  builds  a  dynamically  shared object in
                   dsofile by linking these object files plus the
                   remaining object files (.o and .a) of files If
                   no -o option is specified the output  file  is
                   guessed  from  the first filename in files and
                   thus usually defaults to mod_name.so

       -o dsofile  Explicitly specifies the filename of the  cre-
                   ated  dynamically shared object. If not speci-
                   fied and the name cannot be guessed  from  the
                   files  list,  the fallback name mod_unknown.so
                   is used.

       -D name=value
                   This option is directly passed through to  the
                   compilation  command(s).  Use this to add your
                   own defines to the build process.

       -I incdir   This option is directly passed through to  the
                   compilation  command(s).  Use this to add your
                   own include directories to search to the build
                   process.

       -L libdir   This  option is directly passed through to the
                   linker command.  Use  this  to  add  your  own
                   library  directories  to  search  to the build
                   process.

       -l libname  This option is directly passed through to  the
                   linker  command.   Use  this  to  add your own
                   libraries to search to the build process.

       -Wc,compiler-flags
                   This option  passes  compiler-flags  as  addi-
                   tional  flags  to  the  compiler command.  Use
                   this to add local compiler-specific options.

       -Wl,linker-flags
                   This option passes linker-flags as  additional
                   flags  to the linker command.  Use this to add
                   local linker-specific options.

       DSO installation options:

       -i          This indicates the installation operartion and
                   installs   one   or  more  dynamically  shared
                   objects into the servers libexec directory.

       -a          This  additionally  activates  the  module  by
                   automatically  adding a corresponding LoadMod-
                   ule line to Apache's httpd.conf  configuration
                   file (only if still no such entry exists).

       -A          Same  as  option -a but the created LoadModule
                   directive is prefixed with a  hash  sign  (#),
                   i.e.  the  module  is  just prepared for later
                   activation but initially disabled.

EXAMPLES
       Assume you have an Apache module named mod_foo.c available
       which  should  extend  Apache's  server  functionality. To
       accomplish this you first have to  compile  the  C  source
       into  a shared object suitable for loading into the Apache
       server under runtime via the following command:

         $ apxs -c mod_foo.c
         gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo.c
         ld -Bshareable -o mod_foo.so mod_foo.o
         $ _

       Then you have to update the Apache configuration by making
       sure a LoadModule directive is present to load this shared
       object. To simplify this step apxs provides  an  automatic
       way  to  install the shared object in its "libexec" direc-
       tory and updating the httpd.conf  file  accordingly.  This
       can be achieved by running:

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

       This way a line named

         LoadModule foo_module libexec/mod_foo.so

       is  added  to the configuration file if still not present.
       If you want to have this this disabled per default use the
       -A option, i.e.

         $ apxs -i -A mod_foo.c

       For  a  quick  test of the APXS mechanism you can create a
       sample Apache module template plus a  corresponding  Make-
       file via:

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

       Then you can immediately compile this sample module into a
       shared object and load it into the Apache server:

         $ cd foo
         $ make all reload
         apxs -c mod_foo.c
         gcc -fpic -DSHARED_MODULE -I/path/to/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 /path/to/apache/libexec/mod_foo.so
         chmod 755 /path/to/apache/libexec/mod_foo.so
         [activating module `foo' in /path/to/apache/etc/httpd.conf]
         apachectl restart
         /path/to/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
         /path/to/apache/sbin/apachectl restart: httpd started
         $ _

       You can even use apxs to compile complex  modules  outside
       the Apache source tree, like PHP3:

         $ cd php3
         $ ./configure --with-shared-apache=../apache-1.3
         $ apxs -c -o libphp3.so mod_php3.c libmodphp3-so.a
         gcc -fpic -DSHARED_MODULE -I/tmp/apache/include  -c mod_php3.c
         ld -Bshareable -o libphp3.so mod_php3.o libmodphp3-so.a
         $ _

       because  apxs  automatically recognized C source files and
       object files.  Only C  source  files  are  compiled  while
       remaining object files are used for the linking phase.

SEE ALSO
       apachectl(1), httpd(8).

                            April 1998                          1