


apxs(8)                                                   apxs(8)


NAME
       apxs - APache eXtenSion tool

SYNOPSIS
       apxs -g [ -S name=value ] -n modname

       apxs -q [ -S name=value ] query ...

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

       apxs  -i  [  -S  name=value ] [ -n modname ] [ -a ] [ -A ]
       dsofile ...

       apxs -e [ -S name=value ] [ -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



                            April 1998                          1





apxs(8)                                                   apxs(8)


       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.

       Configuration options:

       -S name=value
                   This   option   changes   the   apxs  settings
                   described above.

       Template Generation options:




                            April 1998                          2





apxs(8)                                                   apxs(8)


       -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



                            April 1998                          3





apxs(8)                                                   apxs(8)


                   local linker-specific options.

       DSO installation and configuration options:

       -i          This  indicates the installation operation and
                   installs  one  or  more   dynamically   shared
                   objects into the server's libexec directory.

       -a          This  activates  the  module  by automatically
                   adding  a  corresponding  LoadModule  line  to
                   Apache's  httpd.conf configuration file, or by
                   enabling it if it already 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.

       -e          This  indicates  the  editing operation, which
                   can be used with the -a and -A  options  simi-
                   larly  to  the  -i  operation to edit Apache's
                   httpd.conf configuration file without attempt-
                   ing to install the module.

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.



                            April 1998                          4





apxs(8)                                                   apxs(8)


       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                          5


