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

Использовать номер версии в стиле alpha/beta. Приводит к номеру версии "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, используемой для его запуска.

-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=регулярное выражение

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

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

Не использовать 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 для получения дополнительной информации.