apxs — инструмент расширений Apache

apxs — это инструмент для сборки и установки модулей расширения для сервера Apache HyperText Transfer Protocol (HTTP). Для этого из одного или нескольких исходных файлов или объектных files создаётся динамический общий объект (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
$ _

В качестве аргументов files можно указать любые исходные файлы 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`

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

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

-S name=value

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

Параметры создания шаблонов

-g

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

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

-c

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

-o dsofile

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

-D name=value

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

-I incdir

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

-L libdir

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

-l libname

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

-Wc,compiler-flags

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

-Wl,linker-flags

Этот параметр передаёт 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 позволяет автоматически установить общий объект в каталог "modules" и соответствующим образом обновить файл 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
$ _