Manual Page: apxs - Apache HTTP Server

### Apache HTTP Server Version 1.3

# Manual Page: apxs

    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 ] dso-
         file ...

         apxs -e [ -S variable=value ] [ -n name ] [ -a ] [ -A ] dso-
         file ...

    DESCRIPTION
         apxs is a tool for building and installing extension modules
         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  LoadMo-
         dule 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  automati-
         cally 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  automatically
         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 Independent 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/manual/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 guess-
                     ing it from the filename.

         Query options:

         -q          Performs a query for apxs's knowledge about cer-
                     tain  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
                     -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 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 created
                     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  pro-
                     cess.

         -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  additional
                     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 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 similarly to
                     the -i operation  to  edit  Apache's  httpd.conf
                     configuration file without attempting to install
                     the module.

    EXAMPLES
         Assume you have an Apache module named  mod_foo.c  available
         which should extend Apache's server functionality. To accom-
         plish 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  run-
         ning:

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

           $ apxs -i -A mod_foo.c

         For a quick test of the apxs mechanism you can create a sam-
         ple  Apache  module  template  plus a corresponding Makefile
         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 automatically
         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(1), httpd(8).

### Apache HTTP Server Version 1.3