h2xs

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• СИНТАКСИС
• ОПИСАНИЕ
• ПАРАМЕТРЫ
• ПРИМЕРЫ
  • Расширение, основанное на файлах .h и .c
• ОКРУЖЕНИЕ
• АВТОР
• СМОТРИТЕ ТАКЖЕ
• ДИАГНОСТИКА
• ОГРАНИЧЕНИЯ параметра -x

НАЗВАНИЕ

h2xs - конвертировать заголовочные файлы C (.h) в расширения Perl

СИНТАКСИС

h2xs [ПАРАМЕТРЫ ...] [файл_заголовка ... [дополнительные_библиотеки]]

h2xs -h|-?|--help

ОПИСАНИЕ

h2xs создаёт расширение Perl из файлов заголовков C. Расширение будет включать функции, которые могут быть использованы для получения значения любого оператора #define, присутствующего в файлах заголовков C.

Имя_модуля будет использоваться для имени расширения. Если имя_модуля не указано, то будет использоваться имя первого файла заголовка с заглавной первой буквой.

Если расширение может потребовать дополнительные библиотеки, они должны быть указаны здесь. Файл Makefile.PL расширения позаботится о проверке фактического существования библиотек и способе их загрузки. Дополнительные библиотеки должны быть указаны в формате -lm -lposix и т.п., точно так же, как и в командной строке cc. По умолчанию Makefile.PL будет искать библиотеки в пути, определённом в Configure. Этот путь можно дополнить, включив аргументы в формате -L/another/library/path в аргументе дополнительных библиотек.

Несмотря на своё имя, h2xs также может использоваться для создания каркаса чисто Perl-модуля. См. параметр -X.

ПАРАМЕТРЫ

-A, --omit-autoload

Исключить все средства автозагрузки. Это то же самое, что -c, но также удаляет оператор use AutoLoader из файла .pm.

-B, --beta-version

Использовать номер версии в стиле альфа/бета. Приводит к номеру версии "0.00_01", если не указан параметр -v.

-C, --omit-changes

Исключает создание файла Changes и добавляет раздел HISTORY в шаблон POD.

-F, --cpp-flags=addflags

Дополнительные параметры для указания препроцессору C при сканировании заголовка в поисках объявлений функций. Также записывает эти параметры в сгенерированный Makefile.PL.

-M, --func-mask=регулярное выражение

выбирает функции/макросы для обработки.

-O, --overwrite-ok

Разрешает перезапись существующего каталога расширений.

-P, --omit-pod

Исключить автоматически сгенерированный раздел POD.

-X, --omit-XS

Исключить часть XS. Используется для генерации каркаса чисто Perl-модуля. -c и -f неявно включены.

-a, --gen-accessors

Создать метод доступа для каждого элемента структур и объединений. Сгенерированные методы названы по имени элемента; возвращают текущее значение элемента, если вызваны без дополнительных аргументов; и устанавливают элемент в заданное значение (и возвращают новое значение), если вызваны с дополнительным аргументом. Вложенные структуры и объединения возвращаются как указатель, а не как полная структура, для облегчения цепочечных вызовов.

Эти методы все применяются к типу Ptr для структуры; дополнительно две функции созданы для типа структуры, _to_ptr которая возвращает тип Ptr, указывающий на ту же структуру, и new метод для создания и возвращения новой структуры, инициализированной нулями.

-b, --compat-version=версия

Генерирует файл .pm, который обратно совместим с указанной версией Perl.

Для версий < 5.6.0 изменения: - без использования 'our' (используется 'use vars' вместо него) - без 'use warnings'

Указание версии совместимости, большей, чем версия Perl, которую вы используете для запуска h2xs, не повлияет. Если не указано, h2xs будет использовать совместимость с версией Perl, которую вы используете для запуска h2xs.

-c, --omit-constant

Исключить constant() из файла .xs и соответствующий специализированный AUTOLOAD из файла .pm.

-d, --debugging

Включить сообщения отладки.

-e, --omit-enums=[регулярное выражение]

Если регулярное выражение не указано, пропустить все константы, определённые в C-перечислении. В противном случае пропустить только те константы, которые определены в перечислении, имя которого соответствует регулярному выражению.

Поскольку регулярное выражение необязательно, убедитесь, что после этого переключателя есть как минимум один другой переключатель, если вы опускаете регулярное выражение и у вас есть какие-либо ожидающие аргументы, такие как имена файлов заголовков. Это правильно:

h2xs -e -n Module::Foo foo.h

Это не правильно:

h2xs -n Module::Foo -e foo.h

В последнем случае foo.h воспринимается как регулярное выражение.

-f, --force

Разрешает создание расширения для заголовка даже если этот заголовок не найден в стандартных каталогах включения.

-g, --global

Включить код для безопасного хранения статических данных в файле .xs. Расширения, которые не используют статические данные, могут игнорировать этот параметр.

-h, -?, --help

Вывести использование, справку и версию для этого h2xs и выйти.

-k, --omit-const-func

Для аргументов функции, объявленных как const, исключить атрибут const в сгенерированном коде XS.

-m, --gen-tied-var

Экспериментально: для каждой переменной, объявленной в файле(ах) заголовка, объявить переменную Perl с тем же именем, магически привязанную к переменной C.

-n, --name=имя_модуля

Указывает имя, которое будет использоваться для расширения, например, -n RPC::DCE

-o, --opaque-re=регулярное выражение

Использовать тип данных "opaque" для типов C, соответствующих регулярному выражению, даже если эти типы являются typedef-эквивалентными типам из typemap. Не следует использовать без -x.

Это может быть полезно, например, для типов, которые являются typedef-эквивалентными целым числам, но представляют собой системные дескрипторы, и для них может потребоваться работать с ними в объектно-ориентированном стиле, например, $handle->do_something(). Используйте -o . если хотите обрабатывать все typedef-типы как opaque-типы.

Тип, на который необходимо сопоставить, очищен (кроме запятых, у которых нет пробелов перед ними, и нескольких * у которых нет пробелов между ними).

-p, --remove-prefix=префикс

Укажите префикс, который должен быть удалён из имён функций Perl, например, -p sec_rgy_ Это задаёт ключевое слово XS PREFIX и удаляет префикс из функций, которые загружаются автоматически с помощью механизма constant().

-s, --const-subs=sub1,sub2

Создать Perl-подпрограмму для указанных макросов вместо автозагрузки с помощью подпрограммы constant(). Эти макросы предполагаются с типом возвращаемого значения char *, например, -s sec_rgy_wildcard_name,sec_rgy_wildcard_sid.

-t, --default-type=тип

Укажите внутренний тип, который используется механизмом constant() для макросов. По умолчанию IV (целое число со знаком). В настоящее время все макросы, обнаруженные во время сканирования заголовка, будут считаться имеющими этот тип. Будущие версии h2xs могут получить возможность делать более точные догадки.

--use-new-tests

Когда присутствует --compat-version (-b), сгенерированные тесты будут использовать Test::More вместо Test, что является значением по умолчанию для версий до 5.6.2. Test::More будет добавлен в PREREQ_PM сгенерированного Makefile.PL.

--use-old-tests

Принудительно сгенерирует код тестирования, использующий старый модуль Test.

--skip-exporter

Не использовать Exporter и/или экспортировать любые символы.

--skip-ppport

Не использовать Devel::PPPort: нет переноса на более старую версию.

--skip-autoloader

Не использовать модуль AutoLoader, но сохранить функцию constant() и sub AUTOLOAD для констант.

--skip-strict

Не использовать pragma strict.

--skip-warnings

Не использовать pragma warnings.

-v, --version=версия

Указать номер версии для этого расширения. Этот номер версии добавляется в шаблоны. По умолчанию 0.01 или 0.00_01, если указан -B . Указанная версия должна быть числовой.

-x, --autogen-xsubs

Автоматически генерировать XSUB-функции на основе объявлений функций в файле заголовка. Должен быть установлен пакет C::Scan . Если этот параметр указан, имя файла заголовка может иметь вид NAME1,NAME2. В этом случае NAME1 используется вместо указанной строки, но XSUB-функции генерируются только для объявлений, включённых из файла NAME2.

Обратите внимание, что некоторые типы аргументов/значений возвращаемых функций могут привести к XSUB-объявлениям/записям typemap, которые требуют ручной правки. Это могут быть объекты, которые не могут быть преобразованы в/из указателя (например, long long), указатели на функции или массивы. См. также раздел "ОГРАНИЧЕНИЯ параметра -x".

ПРИМЕРЫ

# Default behavior, extension is Rusers
h2xs rpcsvc/rusers

# Same, but extension is RUSERS
h2xs -n RUSERS rpcsvc/rusers

# Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h>
h2xs rpcsvc::rusers

# Extension is ONC::RPC.  Still finds <rpcsvc/rusers.h>
h2xs -n ONC::RPC rpcsvc/rusers

# Without constant() or AUTOLOAD
h2xs -c rpcsvc/rusers

# Creates templates for an extension named RPC
h2xs -cfn RPC

# Extension is ONC::RPC.
h2xs -cfn ONC::RPC

# Extension is a pure Perl module with no XS code.
h2xs -X My::Module

# Extension is Lib::Foo which works at least with Perl5.005_03.
# Constants are created for all #defines and enums h2xs can find
# in foo.h.
h2xs -b 5.5.3 -n Lib::Foo foo.h

# Extension is Lib::Foo which works at least with Perl5.005_03.
# Constants are created for all #defines but only for enums
# whose names do not start with 'bar_'.
h2xs -b 5.5.3 -e '^bar_' -n Lib::Foo foo.h

# Makefile.PL will look for library -lrpc in
# additional directory /opt/net/lib
h2xs rpcsvc/rusers -L/opt/net/lib -lrpc

# Extension is DCE::rgynbase
# prefix "sec_rgy_" is dropped from perl function names
h2xs -n DCE::rgynbase -p sec_rgy_ dce/rgynbase

# Extension is DCE::rgynbase
# prefix "sec_rgy_" is dropped from perl function names
# subroutines are created for sec_rgy_wildcard_name and
# sec_rgy_wildcard_sid
h2xs -n DCE::rgynbase -p sec_rgy_ \
-s sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase

# Make XS without defines in perl.h, but with function declarations
# visible from perl.h. Name of the extension is perl1.
# When scanning perl.h, define -DEXT=extern -DdEXT= -DINIT(x)=
# Extra backslashes below because the string is passed to shell.
# Note that a directory with perl header files would
#  be added automatically to include path.
h2xs -xAn perl1 -F "-DEXT=extern -DdEXT= -DINIT\(x\)=" perl.h

# Same with function declaration in proto.h as visible from perl.h.
h2xs -xAn perl2 perl.h,proto.h

# Same but select only functions which match /^av_/
h2xs -M '^av_' -xAn perl2 perl.h,proto.h

# Same but treat SV* etc as "opaque" types
h2xs -o '^[S]V \*$' -M '^av_' -xAn perl2 perl.h,proto.h

Расширение, основанное на файлах .h и .c

Предположим, у вас есть некоторые файлы C, реализующие определённую функциональность, и соответствующие заголовочные файлы. Как создать расширение, которое делает эту функциональность доступной в Perl? Пример ниже предполагает, что заголовочные файлы имеют имена interface_simple.h и interface_hairy.h, а Perl-модуль должен называться Ext::Ension. Если вам понадобятся препроцессорные директивы и/или компоновка с внешними библиотеками, обратитесь к флагам -F, -L и -l в "OPTIONS".

Нахождение имени директории

Начните с пробного запуска h2xs:

h2xs -Afn Ext::Ension

Единственная цель этого шага — создание необходимых каталогов и ознакомление вас с их именами. Из вывода вы можете увидеть, что каталог для расширения — Ext/Ension.

Копирование файлов C

Скопируйте ваши заголовочные файлы и файлы C в этот каталог Ext/Ension.

Создание расширения

Запустите h2xs, перезаписывая старые автоматически сгенерированные файлы:

h2xs -Oxan Ext::Ension interface_simple.h interface_hairy.h

h2xs ищет заголовочные файлы после перехода в каталог расширения, поэтому найдёт ваши заголовочные файлы без проблем.

Архивация и тестирование

Как обычно, запустите

cd Ext/Ension
perl Makefile.PL
make dist
make
make test

Рекомендации

Важно выполнить make dist как можно раньше. Таким образом, вы легко сможете объединить (1) свои изменения в автоматически сгенерированные файлы, если решите отредактировать ваши .h файлы и повторно запустить h2xs.

Не забудьте отредактировать документацию в сгенерированном файле .pm.

Рассматривайте автоматически сгенерированные файлы только как заготовки; вы можете придумать лучшие интерфейсы, чем те, которые h2xs смог бы угадать.

Рассматривайте этот раздел только как руководство; некоторые другие варианты h2xs могут лучше соответствовать вашим потребностям.

СРЕДА

Переменные среды не используются.

АВТОР

Larry Wall и другие

СМОТРИТЕ ТАКЖЕ

perl, perlxstut, ExtUtils::MakeMaker и AutoLoader.

ДИАГНОСТИКА

Обычные предупреждения, если не удаётся прочитать или записать вовлечённые файлы.

ОГРАНИЧЕНИЯ параметра -x

h2xs не будет различать, является ли аргумент функции C, например, int *, параметром ввода, вывода или ввода/вывода. В частности, объявления аргументов вида

int
foo(n)
    int *n

следует переписать как

int
foo(n)
    int &n

если n является параметром ввода.

Кроме того, h2xs не имеет возможностей угадывать, что функция

int
foo(addr,l)
     char *addr
     int   l

принимает пару адреса и длины данных по этому адресу, поэтому лучше переписать эту функцию как

int
foo(sv)
        SV *addr
    PREINIT:
        STRLEN len;
        char *s;
    CODE:
        s = SvPV(sv,len);
        RETVAL = foo(s, len);
    OUTPUT:
        RETVAL

или, альтернативно,

static int
my_foo(SV *sv)
{
    STRLEN len;
    char *s = SvPV(sv,len);

    return foo(s, len);
}

MODULE = foo        PACKAGE = foo   PREFIX = my_

int
foo(sv)
    SV *sv

См. perlxs и perlxstut для получения дополнительной информации.