


apxs(8)                                                   apxs(8)


NAME
       apxs - APache eXtenSion tool

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

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

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

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

       apxs -e [ -S variable=value ] [ -n name ] [ -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  auto-
       matically uses the C source files for compilation while it
       just uses 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 DSO. For instance with GCC you
       always just have to use  -fpic.   For  other  C  compilers
       please consult its manual page or watch for the flags apxs
       uses to compile the object files.

       For more details about DSO support in Apache,  first  read
       the   background  information  about  DSO  in  htdocs/man-
       ual/dso.html, then read the documentation of mod_so.



OPTIONS
       Common options:

       -n name     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 variable names:
                     CC              TARGET
                     CFLAGS          SBINDIR
                     CFLAGS_SHLIB    INCLUDEDIR
                     LD_SHLIB        LIBEXECDIR
                     LDFLAGS_SHLIB   SYSCONFDIR
                     LIBS_SHLIB      PREFIX
                   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 variable=value
                   This  option   changes   the   apxs   settings
                   described above.

       Template Generation options:

       -g          This generates a subdirectory name (see option



                            April 1998                          2





apxs(8)                                                   apxs(8)


                   -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  building  and installing of this
                   module.

       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 DSO in dsofile by linking these
                   object files plus the remaining  object  files
                   (.o and .a) of files If no -o option is speci-
                   fied 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  DSO  file. If not specified and the name
                   cannot be guessed from  the  files  list,  the
                   fallback name mod_unknown.so is used.

       -D variable[=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.




                            April 1998                          3





apxs(8)                                                   apxs(8)


       DSO installation and configuration options:

       -i          This  indicates the installation operation and
                   installs one or more DSOs  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 DSO 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  DSO.
       To  simplify  this  step apxs provides an automatic way to
       install the DSO in the "libexec"  directory  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 operation to be disabled, use the
       -A option, i.e.



                            April 1998                          4





apxs(8)                                                   apxs(8)


         $ 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
       DSO 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, because apxs  automati-
       cally recognized C source files and object files.

         $ 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
         $ _

       Only  C  source  files are compiled while remaining object
       files are used for the linking phase.


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










                            April 1998                          5


