35.16. Инфрастуртура сборки расширений

Если вы думаете о распространении ваших модулей расширений для PostgreSQL, установка переносимой системы сборки расширений может оказаться достаточно трудным делом. Поэтому установленный PostgreSQL предоставляет инфраструктуру для сборки расширений, которая называется PGXS, так что простые модули расширений могут быть просто собраны на уже установленном сервере. PGXS в основном задумывался для расширений, которые включают код на языке Си, хотя он может быть также использован и для чисто SQL расширений. Обратите внимание, что PGXS не задумывался как универсальная система сборки расширений, которая может быть использована для построение любого программного обеспечения, взаимодействующего с PostgreSQL; он просто автоматизирует общие правила сборки для простых модулей серверных расширений. Для более сложных пакетов, вам может понадобится написание собственной системы сборки расширений.

Для использования инфраструктуруы PGXS в ваших расширениях, вы должны написать простой makefile. В этом makefile, вам необходимо установить некоторые переменные и наконец подключить глобальный makefile PGXS. Вот пример того, как собрать модуль расширения с именем isbn_issn, включающий динамическую библиотеку, содержащую некоторый Си код, управляющий файл расширения, SQL скрипт и текстовый файл документации:

MODULES = isbn_issn
EXTENSION = isbn_issn
DATA = isbn_issn--1.0.sql
DOCS = README.isbn_issn

PG_CONFIG = pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

Последние три строки всегда должны быть такими же. До них, назначаются переменные или добавляются специальные правила для make.

Устаноите одну из этих переменных, чтобы указать что будет строится:

MODULES

сборка списка объектов динамической библиотеки, которые будут собраны из файлов с исходными текстами с такими же именами (не включая суффиксы библиотеки в этом списке)

MODULE_big

сборка динамической библиотеки из нескольких файлов с исходными текстами (список объектных файлов в OBJS)

PROGRAM

сборка исполняемой программы (список объектных файлов в OBJS)

Можно установить следующие переменные:

EXTENSION

имя(имена) расширения; для каждого имени вы должны предоставить файл extension.control, который будет установлен в prefix/share/extension

MODULEDIR

подкаталог prefix/share, внтурь которого должны быть установлены файлы DATA и DOCS (если не установлен, по умолчанию будет использован подкаталог extension, если переменная EXTENSION установлена или contrib, если нет)

DATA

произвольные файлы для установки в prefix/share/$MODULEDIR

DATA_built

произвольные файлы для установки в prefix/share/$MODULEDIR, которые необходимо собрать в первую очередь

DATA_TSEARCH

произвольные файлы для установки в prefix/share/tsearch_data

DOCS

произвольные файлы для установки в prefix/doc/$MODULEDIR

SCRIPTS

файлы скриптов (не двоичные) для установки в prefix/bin

SCRIPTS_built

файлы скриптов (не двоичные) для установки в prefix/bin, которые необходимо собрать в первую очередь

REGRESS

перечень регрессионных тестов (без суффиксов), см. ниже

REGRESS_OPTS

дополнительные ключи для передачи в pg_regress

EXTRA_CLEAN

дополнительные файлы для удаления в make clean

PG_CPPFLAGS

будет добавлена к CPPFLAGS

PG_LIBS

будет добавлена к строке компановки (линковки) PROGRAM

SHLIB_LINK

будет добавлена к строке комановки (линковки) MODULE_big

PG_CONFIG

путь к программе pg_config установленного PostgreSQL, которая будет использована при операциях сборки расширения (обычно используется только pg_config, путь к которой есть в системной переменной окружения PATH)

Разместите этот makefile как Makefile в каталог, содержащий ваше расширение. Затем вы можете выполнить команду make для компиляции и затем make install для установки вашего модуля. По умолчанию, расширение компилируется и устанавливается для установленного PostgreSQL, которому соответствует первая программа pg_config, найденная в пути системной переменной окружения PATH. Вы можете использовать другую установку, указав в переменной PG_CONFIG путь к другой программе pg_config либо внутри makefile, либо в командной строке при вызовае команды make.

Caution

Изменение PG_CONFIG работает только, когда сборка осуществляется для PostgreSQL 8.3 и выше. В более старых версиях, за исключением самого pg_config такое работать не будет; чтобы выбрать сборку для нужной установки PostgreSQL, вы должны изменить системную переменную окружения PATH.

Скрипты перечисленные в переменной REGRESS используются для регрессионных тестов вашего модуля, которые могут быть вызваны командой make installcheck после выполнения make install. Чтобы это сработало, у вас должен быть запущен сервер PostgreSQL. Файлы скриптов перечисленные в REGRESS должны появиться в подкаталоге с именем sql/ в каталоге вашего расширения. Эти файлы должны иметь расширение .sql, которое не должно указываться в списке, указанном в REGRESS в makefile. Для каждого теста, также должен быть файл, содержащий ожидаемые результаты выполнения теста в подкаталоге с именем expected/ и этот файл должен иметь то же название, что и у теста и расширение .out. Команда make installcheck запускает каждый тестовый скрипт с помощью команды psql и сравнивает полученные результаты с теми, которые указанны в файле ожидаемых результатов. Любые отличия будут записаны в файл regression.diffs в формате команды diff -c. Обратите внимание. что попытка запустить тест, у которого отсутствует файл с ожидаемыми результатами, будет отмечена как "проблема", так что убедитесь, что у вас есть все файлы с ожидаемыми результатами.

Tip: Наиболее лёгкий способ создать файлы с ожидаемыми результатами состоит в том, чтобы создать пустые файлы, затем выполнить тестовый запуск (который разумеется приведёт к тому, что появятся отличия). Найдите файлы с результатами тестов в подкаталоге results/ и скопируйте их в подкаталог expected/, если они совпадают с тем, что вы хотели бы увидеть в результате выполнения теста.