perlsource

СОДЕРЖАНИЕ

• ИМЯ
• ОПИСАНИЕ
• НАВИГАЦИЯ
  • Код на C
  • Модули ядра
  • Тесты
  • Документация
  • Инструменты разработки и документация
  • Система сборки
  • АВТОРЫ
  • Файл MANIFEST

ИМЯ

perlsource - Руководство по дереву исходных кодов Perl

ОПИСАНИЕ

Этот документ описывает структуру дерева исходных кодов Perl. Если вы работаете над ядром Perl, это поможет вам найти то, что вам нужно.

НАВИГАЦИЯ

Дерево исходных кодов Perl большое. Вот что вы в нём найдёте:

Код на C

Исходные коды и заголовочные файлы на C в основном находятся в корне дерева исходных кодов. Есть несколько каталогов, специфичных для платформы, которые содержат код на C. Кроме того, некоторые модули, поставляемые с Perl, включают код на C или XS.

См. perlinterp для получения более подробной информации о файлах, составляющих интерпретатор Perl, а также о его работе.

Модули ядра

Модули, поставляемые в составе ядра Perl, находятся в четырёх подкаталогах. Два из этих каталогов содержат модули ядра, а два — модули, которые также можно выпускать отдельно на CPAN. Модули, которые можно выпускать на CPAN, называются «модулями двойного жизненного цикла».

• lib/

  Этот каталог содержит чисто перловые модули, которые выпускаются только в составе ядра. Этот каталог содержит все модули и их тесты, в отличие от других модулей ядра.

• ext/

  Как и lib/, этот каталог содержит модули, которые выпускаются только в составе ядра. Однако в отличие от lib/, модуль в ext/ обычно имеет структуру каталогов и файлов в стиле CPAN и свой собственный Makefile.PL. Не ожидается, что модуль в ext/ будет работать с более ранними версиями Perl 5. Поэтому такой модуль может в полной мере использовать синтаксические и другие улучшения в Perl 5 blead.

• dist/

  Этот каталог предназначен для модулей двойного жизненного цикла, где исходный код blead является каноническим. Обратите внимание, что некоторые модули в этом каталоге могут ещё не быть выпущены отдельно на CPAN. Модули в dist/ должны работать с более ранними версиями Perl 5.

• cpan/

  Этот каталог содержит модули двойного жизненного цикла, где модуль CPAN является каноническим. Не вносите правки в эти модули напрямую! Изменения в этих модулях должны быть отправлены на проверку основному разработчику модуля CPAN. После внесения и выпуска этих изменений новая версия модуля будет включена в ядро.

Для некоторых модулей двойного жизненного цикла ещё не определено, является ли версия CPAN или исходный код blead каноническим. До тех пор эти модули должны находиться в cpan/.

Тесты

Ядро Perl имеет обширную тестовую среду. Если вы добавляете новые тесты (или новые модули с тестами), вам может потребоваться обновить файл t/TEST, чтобы запустить тесты.

• Тесты модулей

  Тесты модулей ядра в каталоге lib/ находятся рядом с самим модулем. Например, у нас есть lib/strict.pm и lib/strict.t.

  Тесты для модулей в ext/ и модулей двойного жизненного цикла находятся в подкаталогах t/ для каждого модуля, как в стандартном распределении CPAN.

• t/base/

  Тесты абсолютной базовой функциональности Perl. Это включает if, базовые операции чтения и записи файлов, простые регулярные выражения и т. д. Они выполняются первыми в тестовом наборе, и если какой-либо из них завершается ошибкой, что-то действительно сломано.

• t/cmd/

  Тесты базовых управляющих структур, if/else, while, подпрограмм и т. д.

• t/comp/

  Тесты базовых аспектов того, как Perl парсит и компилирует себя.

• t/io/

  Тесты встроенных функций ввода-вывода, включая аргументы командной строки.

• t/mro/

  Тесты реализации порядка разрешения методов Perl (см. mro).

• t/op/

  Тесты встроенных функций Perl, которые не подходят ни в один из других каталогов.

• t/opbasic/

  Тесты встроенных функций Perl, которые, как и функции в t/op/, не подходят ни в один из других каталогов, но, кроме того, не могут использовать t/test.pl, поскольку эта программа зависит от функциональности, которую проверяет сам тестовый файл.

• t/re/

  Тесты функций или поведения, связанных с регулярными выражениями. (Раньше они находились в t/op).

• t/run/

  Тесты функций того, как Perl фактически выполняется, включая коды возврата и обработку переменных среды PERL*.

• t/uni/

  Тесты основной поддержки Unicode.

• t/win32/

  Тесты, специфичные для Windows.

• t/porting/

  Тестирует состояние дерева исходных кодов на наличие различных распространённых ошибок. Например, проверяет, что каждый, кто указан в журнале git, имеет соответствующую запись в файле AUTHORS.

• t/lib/

  Старое место для тестов модулей. Не следует добавлять сюда ничего нового. Здесь всё ещё есть некоторые фрагменты, которые нужно перенести. Возможно, вы сможете их перенести? Спасибо!

Документация

Вся документация ядра Perl для конечных пользователей находится в каталоге pod/. Отдельные модули в lib/, ext/, dist/ и cpan/ обычно имеют свою собственную документацию, либо в файле Module.pm, либо в сопроводительном файле Module.pod.

Наконец, документация, предназначенная для разработчиков ядра Perl, находится в каталоге Porting/.

Инструменты разработки и документация

Каталог Porting содержит набор кода и документации, предназначенных для помощи разработчикам в работе над Perl. Некоторые важные моменты включают:

• check*

  Это скрипты, которые проверяют исходный код на такие вещи, как нарушения ANSI C, проблемы с кодировкой POD и т. д.

• Maintainers, Maintainers.pl и Maintainers.pm

  Эти файлы содержат информацию о том, кто поддерживает какие модули. Запустите perl Porting/Maintainers -M Module::Name чтобы получить больше информации о модуле двойного жизненного цикла.

• podtidy

  Форматирует файл POD. Хорошая идея — запустить его на файле POD, который вы отлаживали.

Система сборки

Система сборки Perl начинается со скрипта Configure в корневом каталоге.

Платформенно-специфические части системы сборки также находятся в каталогах, специфичных для платформы, таких как win32/, vms/ и т. д.

Скрипт Configure в конечном итоге отвечает за создание Makefile.

Система сборки, используемая Perl, называется metaconfig. Эта система поддерживается отдельно от ядра Perl.

Система metaconfig имеет свой собственный репозиторий git. Пожалуйста, ознакомьтесь с файлом README в http://perl5.git.perl.org/metaconfig.git/ для получения дополнительной информации.

Каталог Cross содержит различные файлы, связанные с кросс-компиляцией Perl. Смотрите Cross/README для получения более подробной информации.

AUTHORS

Этот файл перечисляет всех, кто внес вклад в Perl. Если вы отправляете исправление, вам следует добавить своё имя в этот файл в качестве части исправления.

MANIFEST

Файл MANIFEST в корневом каталоге дерева исходных кодов содержит список всех файлов ядра Perl, а также краткое описание каждого файла.

Вы можете получить обзор всех файлов с помощью этой команды:

% perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST