rubbos/app/httpd-2.0.64/docs/man/apxs.8

   1 .\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   2 .\" DO NOT EDIT! Generated from XML source.
   3 .\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   4 .de Sh \" Subsection
   5 .br
   6 .if t .Sp
   7 .ne 5
   8 .PP
   9 \fB\\$1\fR
  10 .PP
  11 ..
  12 .de Sp \" Vertical space (when we can't use .PP)
  13 .if t .sp .5v
  14 .if n .sp
  15 ..
  16 .de Ip \" List item
  17 .br
  18 .ie \\n(.$>=3 .ne \\$3
  19 .el .ne 3
  20 .IP "\\$1" \\$2
  21 ..
  22 .TH "APXS" 8 "2004-11-20" "Apache HTTP Server" "apxs"
  23
  24 .SH NAME
  25 apxs \- APache eXtenSion tool
  26
  27 .SH "SYNOPSIS"
  28
  29 .PP
  30 \fBapxs\fR -\fBg\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] -\fBn\fR \fImodname\fR
  31
  32 .PP
  33 \fBapxs\fR -\fBq\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] \fIquery\fR \&.\&.\&.
  34
  35 .PP
  36 \fBapxs\fR -\fBc\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBo\fR \fIdsofile\fR ] [ -\fBI\fR \fIincdir\fR ] [ -\fBD\fR \fIname\fR=\fIvalue\fR ] [ -\fBL\fR \fIlibdir\fR ] [ -\fBl\fR \fIlibname\fR ] [ -\fBWc,\fR\fIcompiler-flags\fR ] [ -\fBWl,\fR\fIlinker-flags\fR ] \fIfiles\fR \&.\&.\&.
  37
  38 .PP
  39 \fBapxs\fR -\fBi\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBn\fR \fImodname\fR ] [ -\fBa\fR ] [ -\fBA\fR ] \fIdso-file\fR \&.\&.\&.
  40
  41 .PP
  42 \fBapxs\fR -\fBe\fR [ -\fBS\fR \fIname\fR=\fIvalue\fR ] [ -\fBn\fR \fImodname\fR ] [ -\fBa\fR ] [ -\fBA\fR ] \fIdso-file\fR \&.\&.\&.
  43
  44
  45 .SH "SUMMARY"
  46
  47 .PP
  48 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 \fIfiles\fR which then can be loaded into the Apache server under runtime via the LoadModule directive from mod_so\&.
  49
  50 .PP
  51 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 automatically complains if this is not the case\&. You can check this yourself by manually running the command
  52
  53 .nf
  54
  55       $ httpd -l
  56
  57 .fi
  58
  59 .PP
  60 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:
  61
  62 .nf
  63
  64       $ apxs -i -a -c mod_foo\&.c
  65       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo\&.c
  66       ld -Bshareable -o mod_foo\&.so mod_foo\&.o
  67       cp mod_foo\&.so /path/to/apache/modules/mod_foo\&.so
  68       chmod 755 /path/to/apache/modules/mod_foo\&.so
  69       [activating module `foo' in /path/to/apache/etc/httpd\&.conf]
  70       $ apachectl restart
  71       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
  72       [Tue Mar 31 11:27:55 1998] [debug] mod_so\&.c(303): loaded module foo_module
  73       /path/to/apache/sbin/apachectl restart: httpd started
  74       $ _
  75
  76 .fi
  77
  78 .PP
  79 The arguments \fIfiles\fR 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 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 independent 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\&.
  80
  81 .PP
  82 For more details about DSO support in Apache read the documentation of mod_so or perhaps even read the src/modules/standard/mod_so\&.c source file\&.
  83
  84
  85 .SH "OPTIONS"
  86
  87 .SS "Common Options"
  88
  89
  90 .TP
  91 -n \fImodname\fR
  92 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\&.
  93
  94 .SS "Query Options"
  95
  96
  97 .TP
  98 -q
  99 Performs a query for apxs's knowledge about certain settings\&. The \fIquery\fR parameters can be one or more of the following strings: CC, CFLAGS, CFLAGS_SHLIB, INCLUDEDIR, LD_SHLIB, LDFLAGS_SHLIB, LIBEXECDIR, LIBS_SHLIB, SBINDIR, SYSCONFDIR, TARGET\&. .PP Use this for manually determining settings\&. For instance use INC=-I`apxs -q INCLUDEDIR` .PP inside your own Makefiles if you need manual access to Apache's C header files\&.
 100
 101 .SS "Configuration Options"
 102
 103
 104 .TP
 105 -S \fIname\fR=\fIvalue\fR
 106 This option changes the apxs settings described above\&.
 107
 108 .SS "Template Generation Options"
 109
 110
 111 .TP
 112 -g
 113 This generates a subdirectory \fIname\fR (see option -n) and there two files: A sample module source file named mod_\fIname\fR\&.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 module\&.
 114
 115 .SS "DSO Compilation Options"
 116
 117
 118 .TP
 119 -c
 120 This indicates the compilation operation\&. It first compiles the C source files (\&.c) of \fIfiles\fR into corresponding object files (\&.o) and then builds a dynamically shared object in \fIdsofile\fR by linking these object files plus the remaining object files (\&.o and \&.a) of \fIfiles\fR\&. If no -o option is specified the output file is guessed from the first filename in \fIfiles\fR and thus usually defaults to mod_\fIname\fR\&.so\&.
 121 .TP
 122 -o \fIdsofile\fR
 123 Explicitly specifies the filename of the created dynamically shared object\&. If not specified and the name cannot be guessed from the \fIfiles\fR list, the fallback name mod_unknown\&.so is used\&.
 124 .TP
 125 -D \fIname\fR=\fIvalue\fR
 126 This option is directly passed through to the compilation command(s)\&. Use this to add your own defines to the build process\&.
 127 .TP
 128 -I \fIincdir\fR
 129 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\&.
 130 .TP
 131 -L \fIlibdir\fR
 132 This option is directly passed through to the linker command\&. Use this to add your own library directories to search to the build process\&.
 133 .TP
 134 -l \fIlibname\fR
 135 This option is directly passed through to the linker command\&. Use this to add your own libraries to search to the build process\&.
 136 .TP
 137 -Wc,\fIcompiler-flags\fR
 138 This option passes \fIcompiler-flags\fR as additional flags to the compiler command\&. Use this to add local compiler-specific options\&.
 139 .TP
 140 -Wl,\fIlinker-flags\fR
 141 This option passes \fIlinker-flags\fR as additional flags to the linker command\&. Use this to add local linker-specific options\&.
 142
 143 .SS "DSO Installation and Configuration Options"
 144
 145
 146 .TP
 147 -i
 148 This indicates the installation operation and installs one or more dynamically shared objects into the server's \fImodules\fR directory\&.
 149 .TP
 150 -a
 151 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\&.
 152 .TP
 153 -A
 154 Same as option -a but the created LoadModule directive is prefixed with a hash sign (#), \fIi\&.e\&.\fR, the module is just prepared for later activation but initially disabled\&.
 155 .TP
 156 -e
 157 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\&.
 158
 159 .SH "EXAMPLES"
 160
 161 .PP
 162 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:
 163
 164 .nf
 165
 166       $ apxs -c mod_foo\&.c
 167       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo\&.c
 168       ld -Bshareable -o mod_foo\&.so mod_foo\&.o
 169       $ _
 170
 171 .fi
 172
 173 .PP
 174 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 "modules" directory and updating the httpd\&.conf file accordingly\&. This can be achieved by running:
 175
 176 .nf
 177
 178       $ apxs -i -a mod_foo\&.c
 179       cp mod_foo\&.so /path/to/apache/modules/mod_foo\&.so
 180       chmod 755 /path/to/apache/modules/mod_foo\&.so
 181       [activating module `foo' in /path/to/apache/etc/httpd\&.conf]
 182       $ _
 183
 184 .fi
 185
 186 .PP
 187 This way a line named
 188
 189 .nf
 190
 191       LoadModule foo_module modules/mod_foo\&.so
 192
 193 .fi
 194
 195 .PP
 196 is added to the configuration file if still not present\&. If you want to have this disabled per default use the -A option, \fIi\&.e\&.\fR
 197
 198 .nf
 199
 200       $ apxs -i -A mod_foo\&.c
 201
 202 .fi
 203
 204 .PP
 205 For a quick test of the apxs mechanism you can create a sample Apache module template plus a corresponding Makefile via:
 206
 207 .nf
 208
 209       $ apxs -g -n foo
 210       Creating [DIR]  foo
 211       Creating [FILE] foo/Makefile
 212       Creating [FILE] foo/mod_foo\&.c
 213       $ _
 214
 215 .fi
 216
 217 .PP
 218 Then you can immediately compile this sample module into a shared object and load it into the Apache server:
 219
 220 .nf
 221
 222       $ cd foo
 223       $ make all reload
 224       apxs -c mod_foo\&.c
 225       gcc -fpic -DSHARED_MODULE -I/path/to/apache/include -c mod_foo\&.c
 226       ld -Bshareable -o mod_foo\&.so mod_foo\&.o
 227       apxs -i -a -n "foo" mod_foo\&.so
 228       cp mod_foo\&.so /path/to/apache/modules/mod_foo\&.so
 229       chmod 755 /path/to/apache/modules/mod_foo\&.so
 230       [activating module `foo' in /path/to/apache/etc/httpd\&.conf]
 231       apachectl restart
 232       /path/to/apache/sbin/apachectl restart: httpd not running, trying to start
 233       [Tue Mar 31 11:27:55 1998] [debug] mod_so\&.c(303): loaded module foo_module
 234       /path/to/apache/sbin/apachectl restart: httpd started
 235       $ _
 236
 237 .fi
 238
 239 .PP
 240 You can even use apxs to compile complex modules outside the Apache source tree, like PHP3:
 241
 242 .nf
 243
 244       $ cd php3
 245       $ \&./configure --with-shared-apache=\&.\&./apache-1\&.3
 246       $ apxs -c -o libphp3\&.so mod_php3\&.c libmodphp3-so\&.a
 247       gcc -fpic -DSHARED_MODULE -I/tmp/apache/include  -c mod_php3\&.c
 248       ld -Bshareable -o libphp3\&.so mod_php3\&.o libmodphp3-so\&.a
 249       $ _
 250
 251 .fi
 252
 253 .PP
 254 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\&.
 255