Perl パッケージガイドライン

パッケージ作成ガイドライン

32ビット – CLR – クロス – Eclipse – Electron – Free Pascal – GNOME – Go – Haskell – Java – KDE – カーネル – Lisp – MinGW – Node.js – ノンフリー – OCaml – Perl – PHP – Python – R – Ruby – Rust – VCS – ウェブ – Wine

このドキュメントでは CPAN (Comprehensive Perl Authors Network) で配布されている perl モジュールの PKGBUILD の作成を扱っています。このドキュメントの対象読者は perl モジュールのパッケージ作成者です。

Arch Linux のパッケージの慣習

以下の決まり事は perl のモジュールパッケージを一貫性のあるものにするためのものです。このセクションは perl のパッケージングのイントロダクションです。Arch Linux のパッケージ管理・システム管理の観点から記述しています。TL;DR な人のために、一番簡単かつ重要な文章を上に配置しています。

パッケージの名前

モジュールの場合、パッケージの名前は perl- から始まるようにして、後はモジュールの名前を小文字に変換してコロンをハイフンに置き換えたものを付けてください。例えば HTML::Parser のパッケージ名は perl-html-parser となります。Perl アプリケーションの名前はアプリケーション自体の名前と同じにしてください (同じく小文字で)。

パッケージのファイルの置き場所

Perl パッケージはモジュールファイルを /usr/lib/perl5/$version/vendor_perl/ (スクリプトの中では perl -V:vendorarch) または /usr/share/perl5/vendor_perl/ にインストールしてください。下の例にあるように INSTALLDIRS コマンドラインパラメータを vendor に設定することでインストールできます。/usr/lib/perl5/$version/site_perl/ にファイルを保存してはいけません。システム管理者がパッケージ管理システムの管理外となる Perl パッケージをインストールするため用に予約されたディレクトリです。ユーザーが cpan シェルを使ってシステム全体にモジュールをインストールすると、モジュールは site-perl サブディレクトリに保存されます。

perllocal.pod と .packlist ファイルも存在するべきではありません。

アーキテクチャ

ほとんどの Perl パッケージはアーキテクチャに依存しないため arch 配列には 'any' を指定する場合がほとんどです。XS モジュールは動的にロードされるライブラリとしてコンパイルされるため (.so ファイル)、アーキテクチャを ('x86_64') と明示的に設定する必要があります。XS モジュールには大抵 .c ファイルを動的に生成する .xs ファイルが含まれています。

自動化

第2世代の CPAN シェルである CPANPLUS のプラグインが perl-cpanplus-dist-arch パッケージでインストールできます。CPANPLUS によってインストールされたファイルを即座にパッケージ化します。オンラインドキュメントが https://metacpan.org/release/CPANPLUS-Dist-Arch から確認できます。

PKGBUILD サンプル

サンプル PKGBUILD は [1] で確認できます。

次の 2 つの PKGBUILD の例では、PKGBUILD のより高度な問題に対する回復力を高めることを目的とした、このページで紹介した手法を使用しています。ビルドスクリプトには 2 つのスタイルがあるため、PKGBUILDS の例が 2 つあります。最初の PKGBUILD は、Makefile.PL を使用するディストリビューションをパッケージ化する方法の例です。2 番目の PKGBUILD は、Build.PL を使用するディストリビューションの開始点として使用できます。

PKGBUILD

# Contributor: Your Name <youremail@domain.com>
pkgname=perl-foo-bar
pkgver=1.0
pkgrel=1
pkgdesc='This packages the Foo-Bar distribution, containing the Foo::Bar module!'
_dist=Foo-Bar
arch=('any')
url="https://metacpan.org/release/$_dist"
license=('GPL' 'PerlArtistic')
depends=(perl)
options=('!emptydirs' purge)
source=("http://search.cpan.org/CPAN/authors/id/BAZ/$_dist-$pkgver.tar.gz")
md5sums=(...)

build() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1 PERL_AUTOINSTALL=--skipdeps
  /usr/bin/perl Makefile.PL
  make
}

check() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1
  make test
}

package() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_LOCAL_LIB_ROOT
  make install INSTALLDIRS=vendor DESTDIR="$pkgdir"
}

PKGBUILD

# Contributor: Your Name <youremail@domain.com>
pkgname=perl-foo-bar
pkgver=1.0
pkgrel=1
pkgdesc='This packages the Foo-Bar distribution, containing the Foo::Bar module!'
_dist=Foo-Bar
arch=('any')
url="https://metacpan.org/release/$_dist"
license=('GPL' 'PerlArtistic')
depends=(perl)
options=('!emptydirs' purge)
source=("http://search.cpan.org/CPAN/authors/id/BAZ/$_dist-$pkgver.tar.gz")
md5sums=(...)

build() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_MB_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1 MODULEBUILDRC=/dev/null
  /usr/bin/perl Build.PL
  ./Build
}

check() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_MB_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1
  ./Build test
}

package() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_MB_OPT PERL_LOCAL_LIB_ROOT
  ./Build install --installdirs=vendor --destdir="$pkgdir"
}

これらの PKGBUILD の追加の複雑さの正当化は、後のセクションで試みられます。

CPAN モジュールの仕組み

モジュールシステムを作成するために連携して動作する、慎重に設計されたメカニズムと、それほど慎重に設計されていないメカニズムが多数あります。CPAN を使用する場合は、モジュールのソースコードをフェッチし、フェッチしたモジュールをビルドし、後で実行するためにシステムソフトウェアに挿入する手順に従う必要があります。モジュールがどのようにパッケージ化されるべきかを理解するためには、pacman や ArchLinux パッケージを一切関与させずにモジュールがどのように機能するかを理解すると非常に役立ちます。私たちの最終的な目標は、最終製品の構成と一貫性を向上させながら、できるだけ目立たないようにすることです。

モジュール

モジュールは、perl では package キーワードを使用して宣言されます。モジュールは、.pm (dot-pee-em) ファイル内に含まれています。ただし、ファイル内に複数のモジュール (package) が含まれている可能性があります。モジュールには、Archlinux::Module のように、:: (二重コロン) で区切られた名前空間があります。モジュールをロードするとき、:: はディレクトリ区切り文字に置き換えられます。例: Archlinux/Module.pm はモジュール Archlinux::Module に対してロードされます。

コアモジュールは Perl のインストールに含まれています。一部のコアモジュールは、perl にバンドルされた物のみ利用可能です。他のモジュールは引き続き CPAN とは別にダウンロードしてインストールできます。

ディストリビューション

(別名 dist、package) これは、CPAN-lingo の Archlinux パッケージに相当します。ディストリビューションは、ファイルが詰まった .tar.gz アーカイブです。これらのアーカイブには主に .pm モジュールファイル、含まれているモジュールのテスト、モジュールのドキュメント、その他必要と思われるものがすべて含まれています。

通常、ディストリビューションには同じ名前のプライマリモジュールが含まれています。Template-Toolkit ディストリビューションのように、これが当てはまらない場合もあります。Template-Toolkit dist の最新パッケージ Template-Toolkit-2.22.tar.gz には、Template::Toolkit モジュールが含まれていません。

場合によっては、ディストリビューションの名前がメインモジュールにちなんで付けられているため、それらの名前が同じ意味で使用され、混同されてしまうことがあります。ただし、(Template-Toolkit の場合のように) それらを別個のエンティティとみなすと便利な場合があります。

CPAN

各 CPAN ミラーには、CPAN 上のディストリビューション、dist 内のモジュール、dist をアップロードした作成者の名前をリストするインデックスが含まれています。これらは単なるテキストファイルです。最も役立つインデックスは、各 CPAN ミラーから入手できる /modules/02packages.details.txt.gz ファイルにあります。ここでの package という用語は、pacman パッケージに似たものではなく、Perl 言語自体の package キーワードを指します。CPAN シェルは、小文字で斜体の cpan と呼ばれ、インデックスをナビゲートしてインストールするモジュールを見つける単純な由緒ある Perl スクリプトです。

モジュールは 02packages.details.txt.gz リストにあります。モジュール/パッケージ名と同じ行には、モジュールを含むディストリビューション tarball へのパスがあります。cpan にモジュールのインストールを依頼すると、モジュールを検索して関連するディストリビューションをインストールします。ディストリビューションのインストール中に、モジュールの依存関係のリストが生成されます。Cpan は、各モジュールの依存関係を Perl インタープリターにロードしようとします。指定されたバージョンのモジュールをロードできない場合は、プロセスが繰り返されます。

cpan シェルは、インストールする必要なモジュールのバージョンを気にする必要はありません。cpan は、モジュールの最新バージョンが最初にインストールを開始した元のモジュールの要件を満たしている必要があるという事実に依存できます。モジュールの最新バージョンのみがパッケージ詳細ファイルにリストされます。Perl パッケージ作成者にとって残念なことに、私たちのパッケージが最新バージョンの Perl ディストリビューションとそれに含まれるモジュールを提供するという事実に常に依存することはできません。Pacman の依存関係チェックはより静的であり、強力に適用されます。

モジュールの依存関係

Perl は、Python Egg や Ruby gem などの同様のシステムと比較して、依存関係を定義する独自の方法を持っています。エッグは他のエッグへの依存関係を定義します。Gems は Gems に依存します。Perl の dist はモジュールに依存します。モジュールは CPAN ディストリビューションからのみ入手できるため、ある意味、Perl ディストリビューションはディストリビューションに間接的にのみ依存します。モジュールは、モジュールのソースコード内のディストリビューションから独立して独自のバージョンを定義できます。これは、$VERSION という名前の package 変数を定義することによって行われます。strict および warnings を使用する場合、これは our キーワードで定義されます。例えば:

package Foo::Module;
use warnings;
use strict;
our $VERSION = '1.00';

モジュールはバージョンを自由に変更でき、配布バージョンとは異なるバージョンを持つこともできます。これの有用性には疑問がありますが、覚えておくことが重要です。モジュールのバージョンを Perl インタプリタの外部から判断するのはさらに難しく、Perl コード自体を解析し、場合によってはモジュールを Perl にロードする必要もあります。利点は、Perl インタープリターモジュールのバージョンを内部から簡単に判断できることです。例えば:

use Foo::Module;
print $Foo::Module::VERSION, "\n";

依存関係の定義

Perl ディストリビューションでは依存関係はどこに定義されていますか? これらは、Makefile.PL または Build.PL スクリプト内で定義されています。たとえば、Makefile.PL スクリプト内で WriteMakeFile 関数が呼び出され、次のように Makefile が生成されます。

use ExtUtils::MakeMaker;
WriteMakeFile(
    'NAME' => 'ArchLinux::Module',
    'VERSION' => '0.01',
    'PREREQ_PM' => { 'POSIX' => '0.01' },
);

これは不自然な例ですが、依存関係は Makefile.PL または Build.PL スクリプトが実行されるまで最終的なものではないことを理解することが重要です。依存関係は実行時に指定されます。つまり、perl の全機能を使用して依存関係を変更または修正できます。これは、モジュール作成者がディストリビューションをインストールする直前に、依存関係のバージョンを追加、削除、または変更できることを意味します。一部のモジュール作成者は、これを使用して、モジュールがインストールされている場合にのみモジュールに依存するなど、あまりにも賢いことを実行します。一部のマルチプラットフォーム dist は、異なるオペレーティングシステムにインストールされている場合、システム固有のモジュールに依存します。

例として、CPANPLUS ディストリビューションは、現在インストールされている CPANPLUS::Dist プラグインを検索します。現在インストールされているバージョンの CPANPLUS にプラグインがインストールされている場合、それらは新しい CPANPLUS の前提条件に追加されます。理由はよくわかりません。幸いなことに、perl パッケージャーの場合、ほとんどの依存関係は上記の例のように静的であり、最小バージョン 0.01 の POSIX モジュールが必要です。

メタ情報

メタファイルは、名前、作成者、要約説明、モジュール要件などのディストリビューションに関するメタ情報を含む、最近のディストリビューションに含まれています。以前は YAML 形式の META.yml ファイルがありましたが、最近では JSON 形式の META.json ファイルに切り替えられました。これらのファイルは、手動で編集することもできますが、多くの場合、リリース用にディストリビューションをパッケージ化するときに、Makefile.PL または Build.PL スクリプトによって自動的に生成されます。最新の仕様は CPAN::Meta::Spec のオンラインドキュメントで説明されています。

依存関係は実行時に変更できることに注意してください。このため、ビルドスクリプトの実行後に別のメタファイルが生成されます。この 2 番目のメタファイルは MYMETA.json と呼ばれ、実行時にスクリプトが行った変更を反映しており、ディストリビューションが CPAN 用にパッケージ化されたときに生成されたメタファイルとは異なる場合があります。

CPAN の古いディストリビューションにはメタファイルがまったくありません。これらの古いリリースは META.yml ファイルの考え方よりも前のものであり、その前提条件については Makefile.PL でのみ説明されています。

インストールモジュール

Perl の最大の強みは非常に多くのモジュールが CPAN に存在することです。当然のことながら、モジュールをインストールするためのモジュールも複数存在します。やり方はひとつではありません。ここではモジュールをインストールするためのモジュールを「インストールモジュール」と呼称しています。

These modules are concerned with building the distribution and installing module files wherever the user prefers. This seems straightforward, but considering the number of different systems perl runs on, this can get complex. Installation modules all place a perl code file inside the dist tarball. Running this perl script will initiate the build and install process. The script always ends with the .PL suffix and is termed the "Build script" in the below list.

ExtUtils::MakeMaker

ビルドスクリプト: Makefile.PL
CPAN リンク: http://search.cpan.org/dist/ExtUtils-MakeMaker

モジュールをインストールための元祖・最古のモジュールが ExtUtils::MakeMaker です。大きな欠点として何かをビルド・インストールするのに make プログラムを必要とします。Linux ユーザーにとっては大きな問題ではありませんが Windows ユーザーには面倒です。

Module::Build

ビルドスクリプト: Build.PL
CPAN リンク: http://search.cpan.org/dist/Module-Build

Module::Build の利点は perl だけで書かれていることです。モジュールをビルド・インストールするのに make プログラムをインストールする必要がありません。Module::Build がインストールされていないと、同梱されている Build.PL スクリプトも実行できません。最近のバージョンの Perl では Module::Build はコアモジュールとなっているためそのような問題はありません。

ノート: perl 5.22 現在、Module::Build はコアモジュールではありません。

Module::Build::Tiny

ビルドスクリプト: Build.PL
CPAN リンク: http://search.cpan.org/dist/Module-Build-Tiny

This is another pure-perl build tool. As an interface it implements a subset of Module::Build's interface, in particular it requires dashes before its arguments (Module::Build accepts with and without) and doesn't support .modulebuildrc.

Module::Install

ビルドスクリプト: Makefile.PL
CPAN リンク: http://search.cpan.org/dist/Module-Install

Another modern build/installation module, Module::Install still requires the make program be installed to function. MI was designed as a drop-in replacement for MakeMaker, to address some of MakeMaker's shortcomings. Ironically, it depends on MakeMaker in order to operate. The Makefile.PL files that are generated by MI look much different and are implemented using a simple domain specific language.

One very interesting feature is that Module::Install bundles a complete copy of itself into the distribution file. Because of this, unlike MakeMaker or M::B, you do not need Module::Install to be installed on your system.

Another very unique feature is auto-install. Though not recommended by Module::Install's authors this feature is used quite often. When the module author enables auto-install for his distribution, Module::Install will search for and install any pre-requisite modules that are not installed when Makefile.PL is executed. This feature is skipped when Module::Install detects it is being run by CPAN or CPANPLUS. However, this feature is not skipped when run inside... oh I don't know... a PKGBUILD! I hope you can see how a rogue perl program downloading and installing modules willy-nilly inside a PKGBUILD can be a problem. See the #PERL_AUTOINSTALL environment variable to see how to fix this.

環境変数

様々な環境変数がモジュールのビルドやインストールに影響を与えます。一部の変数は劇的な効果をもたらし、間違って使うと問題が発生します。上級ユーザーは以下の環境変数を使用することができます。

PERL_MM_USE_DEFAULT

When this variable is set to a true value, the installation module will pretend the default answer was given to any question it would normally ask. This does not always work, but all of the installation modules honour it. That doesn't mean the module author will!

PERL_AUTOINSTALL

You can pass additional command-line arguments to Module::Install's Makefile.PL with this variable. In order to turn off auto-install (highly recommended), assign --skipdeps to this.

export PERL_AUTOINSTALL='--skipdeps'

PERL_MM_OPT

You can pass additional command-line arguments to Makefile.PL and/or Build.PL with this variable. For example, you can install modules into your home-dir by using:

export PERL_MM_OPT=INSTALLBASE=~/perl5

PERL_MB_OPT

This is the same thing as PERL_MM_OPT except it is only for Module::Build. For example, you could install modules into your home-dir by using:

export PERL_MB_OPT=--install_base=~/perl5

MODULEBUILDRC

Module::Build allows you to override its command-line-arguments with an rcfile. This defaults to ~/.modulebuildrc. This is considered deprecated within the perl toolchain. You can override which file it uses by setting the path to the rcfile in MODULEBUILDRC. The paranoid might set MODULEBUILDRC to /dev/null... just in case.

PERL5LIB

The directories searched for libraries can be set by the user (particularly if they are using Local::Lib) by setting PERL5LIB. That should be cleared before building.

PERL_LOCAL_LIB_ROOT

If the user is using Local::Lib it will set PERL_LOCAL_LIB_ROOT. That should be cleared before building.

ユーザーがインストールした perl の問題

A subtle problem is that advanced perl programmers may like to have multiple versions of perl installed. This is useful for testing backwards-compatibility in created programs. There are also speed benefits to compiling your own custom perl interpreter (i.e. without threads). Another reason for a custom perl is simply because the official perl Arch Linux package sometimes lags behind perl releases. The user may be trying out the latest perl... who knows?

If the user has the custom perl executable in their $PATH, the custom perl will be run when the user types the perl command on the shell. In fact the custom perl will run inside the PKGBUILD as well! This can lead to insidious problems that are difficult to understand.

The problem lies in compiled XS modules. These modules bridge perl and C. As such they must use perl's internal C API to accomplish this bridge. Perl's C API changes slightly with different versions of perl. If the user has a different version of perl than the system perl (/usr/bin/perl) then any XS module compiled with the user's perl will be incompatible with the system-wide perl. When trying to use the compiled XS module with the system perl, the module will fail to load with a link error.

A simple solution is to always use the absolute path of the system-wide perl interpreter (/usr/bin/perl) when running perl in the PKGBUILD.