perlsource

СОДЕРЖАНИЕ

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

ИМЯ

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

ОПИСАНИЕ

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

НАВИГАЦИЯ

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

Код на C

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

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

Модули ядра

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

• lib/

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

• 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 имеет обширную тестовую suite. Если вы добавляете новые тесты (или новые модули с тестами), вам может потребоваться обновить файл 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/

  Тесты для встроенных функций 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 на *nix-подобных системах начинается со скрипта Configure в корневом каталоге.

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

Скрипт Configure (или аналогичный платформ-специфичный скрипт) в конечном итоге отвечает за генерацию файла Makefile из Makefile.SH.

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

Система metaconfig имеет свой собственный репозиторий git. Более подробную информацию см. в файле README в https://github.com/Perl/metaconfig.

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

AUTHORS

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

MANIFEST

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

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

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