apxs - Инструмент для создания и установки расширений Apache

apxs — инструмент для создания и установки модулей расширений для сервера Apache HyperText Transfer Protocol (HTTP). Это достигается путём построения динамической общей библиотеки (DSO) из одного или нескольких исходных или объектных файлов, которые затем могут быть загружены в сервер Apache во время выполнения с помощью директивы LoadModule из mod_so.

Таким образом, для использования этой механизма расширения ваша платформа должна поддерживать функцию DSO, а ваш бинарник Apache httpd должен быть скомпилирован с модулем mod_so. Инструмент apxs автоматически сообщает об этом, если это не так. Вы можете проверить это самостоятельно, выполнив команду

$ httpd -l

Модуль mod_so должен быть частью отображаемого списка. Если эти требования выполнены, вы можете легко расширить функциональность вашего сервера Apache, установив свои собственные модули с помощью механизма DSO с помощью этого инструмента apxs:

$ 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/modules/mod_foo.so
chmod 755 /path/to/apache/modules/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
$ _

Аргументы файлы могут быть любыми исходными файлами C (.c), объектным файлом (.o) или даже архивной библиотекой (.a). Инструмент apxs автоматически распознаёт эти расширения и автоматически использует файлы исходного кода C для компиляции, а файлы объектных и архивных файлов — только для стадии компоновки. Но при использовании предварительно скомпилированных объектов убедитесь, что они скомпилированы для кода, независимого от позиции (PIC), чтобы иметь возможность использовать их для динамически загружаемой общей библиотеки. Например, с GCC вам всегда нужно использовать только -fpic. Для других компиляторов C см. руководство или обратите внимание на флаги, которые использует apxs для компиляции объектных файлов.

Для получения более подробной информации о поддержке DSO в Apache обратитесь к документации mod_so или, возможно, прочитайте файл исходного кода src/modules/standard/mod_so.c.

Синопсис

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

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

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

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

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

Параметры

Общие параметры

-n modname

Это явно задаёт имя модуля для параметра -i (установка) и -g (генерация шаблона). Используйте это для явного указания имени модуля. Для параметра -g это необходимо, для параметра -i инструмент apxs пытается определить имя из исходного кода или (в качестве резервного варианта) по крайней мере, угадать его по имени файла.

Параметры запроса

-q

Выполняет запрос переменных и параметров окружения, используемых для построения httpd. При вызове без параметров query он выводит все известные переменные и их значения. Необязательный параметр -v форматирует вывод списка.

Используйте это для ручного определения параметров, используемых для построения httpd, который загрузит ваш модуль. Например, используйте

INC=-I`apxs -q INCLUDEDIR`

в файлах Make, если вам нужен прямой доступ к заголовочным файлам Apache на языке C.

Параметры конфигурации

-S name=value

Этот параметр изменяет параметры apxs, описанные выше.

Параметры генерации шаблонов

-g

Это создаёт подкаталог name (см. параметр -n) и два файла в нём: образец исходного файла модуля с именем mod_name.c, который можно использовать в качестве шаблона для создания собственных модулей или для быстрого начала работы с механизмом apxs. И соответствующий файл Makefile для ещё более лёгкого компиляции и установки этого модуля.

Параметры компиляции DSO

-c

Это указывает на операцию компиляции. Сначала компилирует исходные файлы C (.c) из файлов в соответствующие объектные файлы (.o), а затем строит динамическую общую библиотеку в dsofile, связывая эти объектные файлы с оставшимися объектные файлы (.o и .a) из файлов. Если не указан параметр -o, имя выходного файла угадывается по первому имени файла в файлах, поэтому обычно по умолчанию он устанавливается на mod_name.so.

-o dsofile

Явно указывает имя создаваемой динамической общей библиотеки. Если не указано и имя нельзя угадать из списка файлов, используется резервное имя mod_unknown.so.

-D name=value

Этот параметр напрямую передаётся команде(ам) компиляции. Используйте это, чтобы добавить свои собственные определения в процесс сборки.

-I incdir

Этот параметр напрямую передаётся команде(ам) компиляции. Используйте это, чтобы добавить свои собственные каталоги включения в процесс сборки.

-L libdir

Этот параметр напрямую передаётся команде компоновщика. Используйте это, чтобы добавить свои собственные каталоги библиотек в процесс сборки.

-l libname

Этот параметр напрямую передаётся команде компоновщика. Используйте это, чтобы добавить свои собственные библиотеки в процесс сборки.

-Wc,compiler-flags

Этот параметр передаёт флаги-компилятора в качестве дополнительных флагов команде libtool --mode=compile. Используйте это для добавления локальных параметров, специфичных для компилятора.

-Wl,linker-flags

Этот параметр передаёт флаги-компоновщика в качестве дополнительных флагов команде libtool --mode=link. Используйте это для добавления локальных параметров, специфичных для компоновщика.

-p

Этот параметр заставляет apxs скомпоноваться с библиотеками apr/apr-util. Это полезно при компиляции вспомогательных программ, использующих библиотеки apr/apr-util.

Параметры установки и конфигурации DSO

-i

Это указывает на операцию установки и устанавливает одну или несколько динамических общих библиотек в каталог модулей сервера modules.

-a

Это активирует модуль, автоматически добавляя соответствующую строку LoadModule в файл конфигурации Apache httpd.conf, или включает его, если он уже существует.

-A

То же, что и параметр -a, но создаваемая директива LoadModule имеет префикс # (#), то есть модуль просто подготавливается для последующей активации, но по умолчанию отключён.

-e

Это указывает на операцию редактирования, которая может быть использована с параметрами -a и -A аналогично операции -i для редактирования файла конфигурации Apache httpd.conf без попытки установить модуль.

Примеры

Предположим, у вас есть модуль Apache под названием mod_foo.c, который должен расширять функциональность сервера Apache. Для этого сначала необходимо скомпилировать исходный код C в общую библиотеку, подходящую для загрузки в сервер Apache во время выполнения, выполнив следующую команду:

$ apxs -c mod_foo.c
/path/to/libtool --mode=compile gcc ... -c mod_foo.c
/path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
$ _

Затем необходимо обновить конфигурацию Apache, убедившись, что присутствует директива LoadModule для загрузки этой общей библиотеки. Для упрощения этой задачи apxs предоставляет автоматический способ установки общей библиотеки в каталог «модули» и соответствующего обновления файла httpd.conf. Это можно сделать, выполнив:

$ apxs -i -a mod_foo.la
/path/to/instdso.sh mod_foo.la /path/to/apache/modules
/path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules ... chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/conf/httpd.conf]
$ _

Таким образом, строка с названием

LoadModule foo_module modules/mod_foo.so

добавляется в конфигурационный файл, если она ещё не присутствует. Если вы хотите, чтобы это было отключено по умолчанию, используйте параметр -A, то есть

$ apxs -i -A mod_foo.c

Для быстрого тестирования механизма apxs можно создать шаблон модуля Apache и соответствующий Makefile с помощью:

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

Затем вы можете немедленно скомпилировать этот образец модуля в общую библиотеку и загрузить его в сервер Apache:

$ cd foo
$ make all reload
apxs -c mod_foo.c
/path/to/libtool --mode=compile gcc ... -c mod_foo.c
/path/to/libtool --mode=link gcc ... -o mod_foo.la mod_foo.slo
apxs -i -a -n "foo" mod_foo.la
/path/to/instdso.sh mod_foo.la /path/to/apache/modules
/path/to/libtool --mode=install cp mod_foo.la /path/to/apache/modules ... chmod 755 /path/to/apache/modules/mod_foo.so
[activating module `foo' in /path/to/apache/conf/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
$ _