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

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