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-эквивалентны типам из таблиц преобразования. Не следует использовать без -x.

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

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

-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

Не использовать псевдоним strict.

--skip-warnings

Не использовать псевдоним warnings.

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

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

-x, --autogen-xsubs

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

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

Обратите внимание, что некоторые типы аргументов/значений возврата функций могут привести к XSUB-объявлениям/записям в таблице преобразования, которые требуют ручного редактирования. Это могут быть объекты, которые не могут быть преобразованы из/в указатель (например, 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 для получения дополнительной информации.