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