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/

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

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

Вся документация ядра 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