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

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

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

Вся документация ядра, предназначенная для конечных пользователей, находится в каталоге 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