Перейти к основному содержимому

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

примечание

Эта страница переведена при помощи нейросети GigaChat.

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

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

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

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

Последние три строки всегда должны быть одинаковыми. Выше в файле назначаются переменные или добавляются пользовательские правила создания.

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

  • MODULES – список объектов общих библиотек, которые будут построены из файлов с той же основой (не включайте суффиксы библиотеки в этот список).
  • MODULE_big – общая библиотека, которая будет построена из нескольких исходных файлов (перечислите объектные файлы в OBJS).
  • PROGRAM – исполняемая программа, которая должна быть собрана (список объектных файлов в OBJS).

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

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

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

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

  • DATA_built – произвольные файлы для установки в префикс/share/$MODULEDIR, которые сначала нужно собрать.

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

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

  • HEADERS и HEADERS_built – файлы, которые будут устанавливаться (и, возможно, собираться) в префикс/include/server/$MODULEDIR/$MODULE_big.

    В отличие от DATA_built, файлы в HEADERS_built не удаляются при выполнении цели clean; если необходимо их удалить, также добавьте их в EXTRA_CLEAN или добавьте свои собственные правила для этого.

  • HEADERS_$MODULE и HEADERS_built_$MODULE – файлы для установки (после сборки, если указано) под префикс/include/server/$MODULEDIR/$MODULE, где $MODULE должно быть именем модуля, используемым в MODULES или MODULE_big.

    В отличие от DATA_built, файлы в HEADERS_built_$MODULE не удаляются целью clean; если необходимо их удалить, также добавьте их в EXTRA_CLEAN или добавьте свои собственные правила для этого.

    Законно использовать обе переменные для одного и того же модуля или любую комбинацию, если нет двух имен модулей в списке MODULES, которые отличаются только наличием префикса built_, что вызвало бы двусмысленность. В этом (надеюсь, маловероятном) случае необходимо использовать только переменные HEADERS_built_$MODULE.

  • SCRIPTS – файлы сценариев (не двоичные файлы) для установки в префикс/bin.

  • SCRIPTS_built – файлы сценариев (не двоичные файлы) для установки в префикс/bin, которые сначала нужно собрать.

  • REGRESS – список тестов регрессий (без суффикса), см. ниже.

  • REGRESS_OPTS – дополнительные параметры для передачи pg_regress.

  • ISOLATION – список изоляционных тестов, см. ниже дополнительные сведения.

  • ISOLATION_OPTS – дополнительные переключатели для передачи pg_isolation_regress.

  • TAP_TESTS – переключатель, определяющий, нужно ли запускать тесты TAP, см. ниже.

  • NO_INSTALL – не определять цель install, полезно для тестовых модулей, которые не требуют установки их сборочных продуктов.

  • NO_INSTALLCHECK – не определять цель installcheck, полезно, например, если тесты требуют специальной настройки или не используют pg_regress.

  • EXTRA_CLEAN – дополнительные файлы, которые должны быть удалены при make clean.

  • PG_CPPFLAGS – флаги, добавляемые перед другими в CPPFLAGS.

  • PG_CFLAGS – флаги, добавляемые в CFLAGS.

  • PG_CXXFLAGS – флаги, добавляемые в CXXFLAGS.

  • PG_LDFLAGS – флаги, добавляемые перед другими в LDFLAGS.

  • PG_LIBS – будет добавлено в строку компоновки PROGRAM.

  • SHLIB_LINK – будет добавлено в строку компоновки MODULE_big.

  • PG_CONFIG – путь к программе pg_config для установки PostgreSQL, с которой будет выполняться сборка (обычно просто pg_config использовать первый в PATH).

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

Также можно запустить make в каталоге вне исходного дерева расширения, если хотите отделить каталог сборки. Эта процедура также называется VPATH сборкой. Вот как это делается:

mkdir build_dir
cd build_dir
make -f /path/to/extension/source/tree/Makefile
make -f /path/to/extension/source/tree/Makefile install

В качестве альтернативы можно настроить каталог для сборки VPATH аналогичным образом, как это делается для основного кода. Один из способов сделать это - использовать основной сценарий config/prep_buildtree. После этого соберите его, установив переменную make VPATH следующим образом:

make VPATH=/path/to/extension/source/tree
make VPATH=/path/to/extension/source/tree install

Эта процедура может работать с большим разнообразием компоновки каталогов.

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

Сценарии, перечисленные в переменной ISOLATION, используются для тестов, проверяющих поведение одновременных сеансов работы с модулем, которые могут быть вызваны с помощью make installcheck после выполнения make install. Для этого у вас должен быть запущен сервер PostgreSQL. Файлы сценариев, указанные в ISOLATION, должны находиться в подкаталоге с именем specs/ в каталоге расширения. Эти файлы должны иметь расширение .spec, которое не должно быть включено в список ISOLATION в файле makefile. Для каждого теста также должна существовать файл, содержащий ожидаемый вывод в подкаталоге с именем expected/, с тем же стволом и расширением .out. make installcheck выполняет каждый тестовый сценарий и сравнивает полученный результат с соответствующим ожидаемым файлом. Любые различия будут записаны в файл output_iso/regression.diffs в формате diff -c. Обратите внимание, что попытка запустить тест, которому не хватает ожидаемого файла, будет отмечена как «проблема», поэтому убедитесь, что у вас есть все ожидаемые файлы.

TAP_TESTS позволяет использовать тесты TAP. Данные из каждого запуска представлены в подкаталоге с именем tmp_check/. См. также раздел «Тесты TAP» для получения более подробной информации.

Совет

Самый простой способ создать ожидаемые файлы – это создать пустые файлы, а затем выполнить тестовый запуск (который, конечно же, сообщит о различиях). Проверьте фактические файлы результатов, найденные в каталоге results/ (для тестов в REGRESS), или в каталоге output_iso/results/ (для тестов в ISOLATION), затем скопируйте их в expected/, если они соответствуют тому, что ожидается от теста.