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/

  Тесты для основной поддержки Юникода.

• 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 в https://github.com/Perl/metaconfig для получения более подробной информации.

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

AUTHORS

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

MANIFEST

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

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

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