perlXStut - XSUB を書くためのチュートリアル
このチュートリアルは読者にPerlのエクステンションを作るのに必要な ステップを教えるものです。 読者が perlguts, perlapi, perlxs にアクセスできるということを 仮定しています。
このチュートリアルは非常に単純な例から始めて、新しい例に進むごとに 新たな機能を付加えたより複雑なものへとなります。 幾つかのコンセプトは、読者がエクステンションを作成するのが徐々に 簡単になるように、チュートリアルの後のほうまで完全には説明されません。
このチュートリアルは Unix の観点から書かれています。 (Win32 のように)ほかのプラットフォームでは異なることになると知っている 場所では、それを記しています。 何か見落としを発見したら、ぜひ教えてください。
このチュートリアルでは、Perl が使用するように設定されている
make プログラムが make という名前であると想定しています。
以下の例で "make" を実行する代わりに、Perl が使うように設定された他の
make プログラムを代用する必要があるかもしれません。
perl -V:make とすると、それが何かがわかります。
一般向けに Perl エクステンションを書くとき、あなたのマシンで 利用可能なバージョンと異なるバージョンの Perl でエクステンションが 使われることを想定するべきです。 この文書を読んでいるということは、あなたのマシンの Perl のバージョンは おそらく 5.005 以降でしょうが、エクステンションのユーザーはもっと古い バージョンかもしれません。
どのような非互換性が想定されるかを理解するために、また珍しい場合として、 マシンに入っている Perl のバージョンがこのドキュメントより古い場合、 さらなる情報は "Troubleshooting these Examples" の章を参照してください。
もしエクステンションが、Perl の古いリリースでは利用できないような Perl の 機能を使っているなら、ユーザーは早期の意味のある警告で理解します。 おそらくこの情報を README ファイルに追加するべきでしょうが、最近の エクステンションのインストールは、CPAN.pm モジュールやその他の ツールによって自動的に行われるかもしれません。
MakeMaker ベースのインストールでは、Makefile.PL が、プラットフォームの バージョンチェックの最も早い機会を提供します。 この目的のために、以下のようなものを Makefile.PL に書けます:
eval { require 5.007 }
or die <<EOD;
############
### This module uses frobnication framework which is not available before
### version 5.007 of Perl. Upgrade your Perl before installing Kara::Mba.
############
EOD
一般的には、システムがライブラリを動的にロードする機能を持っていなければ XSUB を作成することはできないと考えられています。 これは正しくありません。 あなたは XSUB を作ることが できます。 ただし、あなたはその XSUB のサブルーチンと、Perl とをリンクして新たな 実行ファイルを作らなければなりません。 この状況は perl4 と同じです。
このチュートリアルはまだそういったシステムを使っていても大丈夫です。 XSUB の作成機能は、システムをチェックして可能であれば動的ロード可能 ライブラリを作成し、できなければスタティックライブラリを作成してから そのスタティックライブラリをリンクしてスタティックリンクされた 実行ファイルを作成します(最後の部分はオプション)。
これからの例を使って、動的ロード可能ライブラリが使えるシステムで
あってもスタティックリンクされた実行ファイルを作成したいという場合、
"make"という引数なしのコマンドを実行する代わりに、
"make perl" というコマンドを実行してください。
もしスタティックリンクされた実行ファイルを作成することを選んだのなら、
"make test" の代わりに "make test_static" を使ってください。
動的ロード可能ライブラリが作成できないシステムの場合には単に
"make test" とするだけで OK です。
では、見ていきましょう!
最初のエクステンションは非常に単純です。 エクステンションの中でルーチンを呼び出すときに、良く知られたメッセージを 出力してリターンします。
"h2xs -A -n Mytest" を実行します。
これは Mytest という名前のディレクトリを作成しますが、カレントの
作業ディレクトリに ext/ というディレクトリがあればその下に作成します。
MANIFEST, Makefile.PL, Mytest.pm, Mytest.xs, test.pl, Changes を含めた
幾つかのファイルがディレクトリ Mytest の下に作成されます。
MANIFEST というファイルには Mytest ディレクトリに生成されたファイル すべてのファイル名があります。
Makefile.PL というファイルは以下のような形式であるべきです。
use ExtUtils::MakeMaker;
# See lib/ExtUtils/MakeMaker.pm for details of how to influence
# the contents of the Makefile that is written.
WriteMakefile(
NAME => 'Mytest',
VERSION_FROM => 'Mytest.pm', # finds $VERSION
LIBS => [''], # e.g., '-lm'
DEFINE => '', # e.g., '-DHAVE_SOMETHING'
INC => '', # e.g., '-I/usr/include/other'
);
Mytest.pm は以下のような内容で始まります。
package Mytest;
use strict;
use warnings;
require Exporter;
require DynaLoader;
our @ISA = qw(Exporter DynaLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
our @EXPORT = qw(
);
our $VERSION = '0.01';
bootstrap Mytest $VERSION;
# Preloaded methods go here.
# Autoload methods go after __END__, and are processed by the autosplit program.
1;
__END__
# Below is the stub of documentation for your module. You better edit it!
.pm ファイルの残りはエクステンションのためのドキュメントをを提供するための サンプルコードからなります。
最後に、Mytest.xs の内容は以下のようになります。
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
MODULE = Mytest PACKAGE = Mytest
.xs ファイルの終わりに以下の行を追加します。
void
hello()
CODE:
printf("Hello, world!\n");
"CODE:" で始まる行がインデントされていないのは問題ありません。 しかし、読みやすさの観点から、CODE: を 1 レベルインデントして、 引き続く行をさらに 1 レベルインデントすることを勧めます。
ここで、"perl Makefile.PL" を実行します。
これで make が必要とする本当の Makefile が生成されます。
この出力は以下のようになります:
% perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for Mytest
%
ここでmakeを実行すれば、以下のような出力が生成されます (一部の長い行は明快さを保つために短くし、一部の余分な行は削除しています):
% make
umask 0 && cp Mytest.pm ./blib/Mytest.pm
perl xsubpp -typemap typemap Mytest.xs >Mytest.tc && mv Mytest.tc Mytest.c
Please specify prototyping behavior for Mytest.xs (see perlxs manual)
cc -c Mytest.c
Running Mkbootstrap for Mytest ()
chmod 644 Mytest.bs
LD_RUN_PATH="" ld -o ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl -b Mytest.o
chmod 755 ./blib/PA-RISC1.1/auto/Mytest/Mytest.sl
cp Mytest.bs ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs
chmod 644 ./blib/PA-RISC1.1/auto/Mytest/Mytest.bs
Manifying ./blib/man3/Mytest.3
%
"prototyping behavior" に関する行は安全に無視できます - これは perlxs の "The PROTOTYPES: Keyword" の章で説明されています。
Win32 システムの場合で、C ライブラリ中の関数に関するリンカのエラーで ビルド処理が失敗する場合、Perl が PerlCRT を使うように設定されているかを 調べて見てください (この場合、perl -V:libc を実行すればわかるはずです)。 もし Perl が PerlCRT を使うように設定されているなら、PerlCRT.lib を msvcrt.lib と同じ位置にコピーして、コンパイラがこれを見つけられるように する必要があります。 msvcrt.lib は普通 Visual C コンパイラの lib ディレクトリ (例えば C:/DevStudio/VC/lib) にあります。
Perl にはテストスクリプトを簡単に書くための独自の特別な方法がありますが、 この例のためだけに、自分でテストスクリプトを作ります。 hello という名前の、以下のような内容のファイルを作ります。
#! /opt/perl5/bin/perl
use ExtUtils::testlib;
use Mytest;
Mytest::hello();
ここでスクリプトを実行可能にして(chmod +x hello)から実行すれば、
以下のような出力になるはずです。
% ./hello
Hello, world!
%
今度は、数値引数を入力として一つ取り、その数値が偶数なら 1 を、奇数なら 0 を返すようなサブルーチンを追加しましょう。
Mytest.xsの最後に以下の行を追加します。
int
is_even(input)
int input
CODE:
RETVAL = (input % 2 == 0);
OUTPUT:
RETVAL
“int input”の行の始めにある空白は必須ではありませんが、これがあると
読みやすさが増します。
同様に、行末のセミコロンも省略可能です。
任意の空白を “int” と “input”の間に置くことができます。
make を再度実行して、新たな共有ライブラリを作ります。
前のステップと同じように、Makefile.PL から Makefile を作って make を実行します。
作成したエクステンションが動作するかを確認するために、 test.pl の ようなファイルが必要となります。 このファイルは Perl 自身が持っている構造をチェックするのと同様のものを 模倣して作ります。 テストスクリプトの中では、エクステンションの動作を確認するたくさんの テストを置き、正しい動作をしたら“ok”を正しくなければ“not ok”を 出力するようにします。 BEGIN ブロックにある文を print "1..4" に変え、ファイルの末尾に以下の行を 追加します。
print &Mytest::is_even(0) == 1 ? "ok 2" : "not ok 2", "\n";
print &Mytest::is_even(1) == 0 ? "ok 3" : "not ok 3", "\n";
print &Mytest::is_even(2) == 1 ? "ok 4" : "not ok 4", "\n";
“make test”というコマンドでテストスクリプトを呼び出します。
以下のような出力が出るはずです。
% make test
PERL_DL_NONLAZY=1 /opt/perl5.004/bin/perl (lots of -I arguments) test.pl
1..4
ok 1
ok 2
ok 3
ok 4
%
プログラム h2xs はエクステンションを作成する出発点となります。 後の例では、h2xs をヘッダーファイルを読み込んで C のルーチンに対する 接点のテンプレートを生成するのにどのように使うかを示します。
h2xs はエクステンションのディレクトリに数多くのファイルを作成します。 Makefile.PL というファイルはエクステンションを作成するための 本当の Makefile を生成する perl スクリプトです。 詳細は後述します。
.pm と .xs といったファイルはエクステンションの要点からなります。 .xs ファイルにはエクステンションを作るための C のルーチンがあります。 .pm ファイルには Perl がどのようにあなたの作ったエクステンションを ロードするかを指示するルーチンがあります。
Makefile を生成し、make を実行することでカレントの作業ディレクトリの
下に blib (“build library”を意味します)と呼ばれるディレクトリが
作られます。
このディレクトリには、私たちが作成する共有ライブラリが置かれます。
一度それをテストすれば、最終的な場所にインストールすることができます。
“make test”経由でテストスクリプトを実行することによって、非常に重要な
幾つかのことを行います。
これは perl に -I 引数を付けて起動し、これによりエクステンションの
一部である様々なファイルを見つけることができるようにします。
エクステンションをテストするのに “make test”を使うのは 非常に
重要です。
もし、テストスクリプトをそのまま実行してしまったら、致命的なエラーが
発生するでしょう。
テストスクリプトを実行するのに“make test”を使うもう一つの重大な
理由は、既にあるエクステンションをアップグレードしたものを
テストしようとしたときに、“make test”を使っていれば、既に
あるものではなく、新しいものをテストすることが保証されるためです。
Perl が use extension; という行を見つけたとき、use する
エクステンションと同じ名前で .pm という拡張を持つファイルを検索します。
もしそういったファイルが見つからなければ、Perl は致命的エラーにより
終了します。
デフォルトの検索パスは @INC という配列に置かれます。
Mytest.pm は perl に Exporter エクステンション と Dynamic Loader
エクステンションが必要であるいうことを教えます。
この後配列 @ISA, @EXPORT とスカラー $VERSION に値を設定し、最後に
モジュールをブートストラップするように perl に指示します。
perl はそのダイナミックローダールーチンを(あれば)呼び出し、共有ライブラリを
ロードします。
@ISA と @EXPORT の二つの配列は非常に重要です。
配列 @ISA には、メソッド(もしくはサブルーチン)がカレントパッケージに
なかったときに探しに行く他のパッケージのリストがあります。
これは普通オブジェクト指向エクステンション(これについてはずっと後の方で
議論します)でのみ重要なので、普通は修正する必要はありません。
配列 @EXPORT は Perl に対して、呼び出されたときにパッケージの名前空間に
置くべきエクステンションの変数とサブルーチンを指示します。
ユーザーが既にあなたの変数名やサブルーチン名を使っているかどうかは
わからないので、何をエクスポートするかを慎重に選択することは極めて
重要です。
何かそうするべき理由がない限りは、メソッド名や変数名を
デフォルトでは エクスポート しない ようにしてください。
一般的な規則として、モジュールがオブジェクト指向しようとした場合には 何もエクスポートしません。 モジュールが単なる関数と変数の集まりであれば、別の配列 @EXPORT_OK を 通じてそれらをエクスポートできます。 この配列は、ユーザーがそうしてほしと明示的に指定しない限り、 自動的にはサブルーチン名と変数名を名前空間に置きません。
詳細は perlmod を参照してください。
変数 $VERSION は .pm ファイルと共有ライブラリがそれぞれ
「同期している」ことを保証します。
.pm ファイルや .xs ファイルを変更したとき、この変数の値を
増加させるべきです。
良いテストスクリプトを書くことの重要性は、いくら強調しても足りません。 Perl 自身が使っている“ok/not ok”の形式を忠実に守り、テストケースで どうなったかを簡単に、曖昧なことなくわかるようにします。 バグを発見して修正したら、テストケースにそれを追加しましょう。
"make test" を実行することにより、正しいスクリプト test.pl を実行して
適切なバージョンのエクステンションを使うことが保証されます。
たくさんのテストケースがあるのなら、Perl のテストの形式を
真似たくなるかもしれません。
エクステンションのディレクトリに“t”という名前のディレクトリを作成して、
テストのためのファイルの名前に ".t" の拡張子をつけます。
"make test" を実行すると、これらのテストファイル全てが実行されます。
三番目の例は、入力として引数を一つとってその値を丸めてからその結果を 引数にセットするというものです。
以下の行を Mytest.xs の末尾に追加してください:
void
round(arg)
double arg
CODE:
if (arg > 0.0) {
arg = floor(arg + 0.5);
} else if (arg < 0.0) {
arg = ceil(arg - 0.5);
} else {
arg = 0.0;
}
OUTPUT:
arg
Makefile.pl というファイルを編集し、対応する行を以下に示すように してください。
'LIBS' => ['-lm'], # e.g., '-lm'
Makefile を生成してから make を実行します。 test.pl の BEGIN ブロックで“1..9”を出力するように変更し、さらに以下の 行を追加します。
$i = -1.5; &Mytest::round($i); print $i == -2.0 ? "ok 5" : "not ok 5", "\n";
$i = -1.1; &Mytest::round($i); print $i == -1.0 ? "ok 6" : "not ok 6", "\n";
$i = 0.0; &Mytest::round($i); print $i == 0.0 ? "ok 7" : "not ok 7", "\n";
$i = 0.5; &Mytest::round($i); print $i == 1.0 ? "ok 8" : "not ok 8", "\n";
$i = 1.2; &Mytest::round($i); print $i == 1.0 ? "ok 9" : "not ok 9", "\n";
“make test”を実行します。
ここで、九つのテストすべてで ok と出力されるはずです。
これらの新しいテストケースでは、丸めるために渡される引数が スカラ変数であることに注目してください。 定数やリテラルを丸めたらどうなるだろうか、という疑問を持ったかもしれません。 何が起きるかを確かめるために、以下の行を test.pl に一時的に 追加してください。
&Mytest::round(3);
"make test" を実行すると、Perl は致命的エラーを起こして
終了してしまいます。
Perl は、定数値を変更させないのです!
Makefile.pl に対する変更をしました。 この場合、エクステンションの共有ライブラリとリンクすべき追加のライブラリ (今回の場合は数学ライブラリ libm)を指定します。 後で、ライブラリにあるすべてのルーチンを呼び出すことのできる XSUB の 書き方について説明します。
関数の値が関数の戻り値として返されるのではなく、関数に渡された 変数の値を変更することで返されます。 round の返り値の型は "void" であると推測したかもしれません。
関数の戻り値と名前を宣言した後の行に XSUB に渡すパラメータを指定できます。 各パラメータ行は(省略可能な)空白で始まり、(省略可能な)終端する セミコロンがあります。
出力パラメータは関数の最後、OUTPUT: 指示子の直後に置きます。 RETVAL を使うことで、Perl に XSUB 関数の戻り値を返したいという意志を 伝えます。 例 3 では、「返り値」を私たちが渡した元の変数に入れてほしいので、 (RETVAL でなく) その変数を OUTPUT: セクションに並べたのです。
xsubpp プログラムは .xs ファイルにある XS コードを取り、それを C に 翻訳しその結果を .c という拡張子のファイルに出力します。 変換された C コードは Perl の中にある C の関数を使うように作られます。
xsubpp プログラムは Perl のデータ型(スカラー、配列、など)から C のデータ型(int, char, など)に変換する規則を使います。 これらのルールは typemap ファイル ($PERLLIB/ExtUtils/typemap)に 格納されます。 このファイルは三つの部分に分けられます。
最初のセクションは様々な C のデータ型を、様々な Perl の型にいくらか対応する 名前にマッピングするものです。 二番目のセクションは入力パラメータを扱うために xsubpp が使用する C コードからなります。 三番目のセクションは出力パラメータに対して xsubpp が使用する C コードからなります。
さあ、私たちのエクステンションのために作られた .c ファイルの一部を 見てみましょう。 ファイル名は Mytest.c です:
XS(XS_Mytest_round)
{
dXSARGS;
if (items != 1)
croak("Usage: Mytest::round(arg)");
{
double arg = (double)SvNV(ST(0)); /* XXXXX */
if (arg > 0.0) {
arg = floor(arg + 0.5);
} else if (arg < 0.0) {
arg = ceil(arg - 0.5);
} else {
arg = 0.0;
}
sv_setnv(ST(0), (double)arg); /* XXXXX */
}
XSRETURN(1);
}
“XXXXX”というコメントが付けられた二つの行に注意してください。 typemap ファイルの最初のセクションを確かめれば、doublesT_DOUBLE という型で あることがわかるでしょう。 INPUT セクションでは T_DOUBLE である引数は、SvNv というルーチンを 呼び出すことによって変数が割り当てられ、その後で double に キャストされてから引数である変数に代入されます。 同様に、OUTPUT セクションでは一度引数が最終的な値を持てば、それは 呼び出された関数に返すために関数 sv_setnv に渡されます。 これら二つの関数は perlguts で説明されています。 引数スタックにあるセクションの“ST(0)”の意味は後で説明します。
一般的にいって、例 3 にあるように入力引数を書き換えるような エクステンションを作ることはよくありません。 代わりに、おそらくは複数の値を配列で返して、呼び出し元にそれを扱わせるように するべきです(これは後の例で行います)。 しかしながら、すでにある入力パラメータを書き換えるような C のルーチンの 呼び出しにより良く適応するために、この振る舞いが許されているのです。 次の例では、これをどう行うかを説明します。
この例で、すでにある C ライブラリとやりとりするような XSUB の記述を 始めます。 これを始めるために、独自の小さなライブラリを作ります。 それから .pm と .xs のための h2xs を記述します。
ディレクトリ Mytest と同じレベルに、Mytest2 ディレクトリを新たに 作ります。 Mytest2 ディレクトリで、mylib という別のディレクトリを作成し、そこに cd します。
ここで、テスト用のライブラリを生成するための幾つかのファイルを作ります。 こういったファイルには、C ソースファイルとヘッダーファイルが含まれます。 また、このディレクトリで Makefile.PL も作ります。 その後で、Mytest2 のレベルで make を実行することにより自動的に Makefile.PL が実行され、その結果 Makefile が作成されます。
ディレクトリ mylib で、以下のような内容の mylib.h というファイルを 作成します。
#define TESTVAL 4
extern double foo(int, long, const char*);
また、mylib.c というファイルを以下のような内容で作成します。
#include <stdlib.h>
#include "./mylib.h"
double
foo(int a, long b, const char *c)
{
return (a + b + atof(c) + TESTVAL);
}
最後に以下のような内容の Makefile.PL を作成します。
use ExtUtils::MakeMaker;
$Verbose = 1;
WriteMakefile(
NAME => 'Mytest2::mylib',
SKIP => [qw(all static static_lib dynamic dynamic_lib)],
clean => {'FILES' => 'libmylib$(LIB_EXT)'},
);
sub MY::top_targets {
'
all :: static
pure_all :: static
static :: libmylib$(LIB_EXT)
libmylib$(LIB_EXT): $(O_FILES)
$(AR) cr libmylib$(LIB_EXT) $(O_FILES)
$(RANLIB) libmylib$(LIB_EXT)
';
}
"$(AR)" と "$(RANLIB)" で始まる行では空白ではなくタブを使っていることを 確認してください。 また、Win32 システムでは、$(AR) の "cr" 引数は不要であることが 報告されています。
ここでトップレベルの Mytest2 というファイルを作成します。 Mytest2 ディレクトリ に変更して、以下のコマンドを実行します。
% h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h
これにより、Mytest2 を上書きするという警告が出ますが、気にすることは ありません。 私たちのファイルは Mytest2/mylib にありますが、さわりません。
h2xs が生成した通常の Makefile.PL は mylib ディレクトリに関してなにも 知りません。 私たちはそういったサブディレクトリがあり、そこにライブラリを作成すると いうことを教えなければなりません。 引数 MYEXTLIB を WriteMakefile 呼び出しに追加して、次のような感じに しましょう:
WriteMakefile(
'NAME' => 'Mytest2',
'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
'LIBS' => [''], # e.g., '-lm'
'DEFINE' => '', # e.g., '-DHAVE_SOMETHING'
'INC' => '', # e.g., '-I/usr/include/other'
'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
);
それから、末尾にサブルーチンを付け加えます(これは既に存在するサブルーチンを 上書きします)。 "cd" で始まる行のインデントにタブ文字を使うことを忘れないでください!
sub MY::postamble {
'
$(MYEXTLIB): mylib/Makefile
cd mylib && $(MAKE) $(PASSTHRU)
';
}
また、ファイル MANIFEST を私たちのエクステンションの内容を反映するように 修正しましょう。 “mylib”という単一の行を以下の三行で置き換えます。
mylib/Makefile.PL
mylib/mylib.c
mylib/mylib.h
私たちの名前空間を奇麗で、汚染されていない状態に保つために .pm ファイルを
編集して、@EXPORT を設定している行を @EXPORT_OK に変更します。
最後に .xs ファイルで、#include の行を編集します。
#include "mylib/mylib.h"
さらに、以下の関数定義を .xs ファイルの末尾に追加します。
double
foo(a,b,c)
int a
long b
const char * c
OUTPUT:
RETVAL
ここで、デフォルトの Perl は今のところ const char * という型をサポートして いないので、typemap ファイルを作成する必要があります。 Mytest2 ディレクトリに typemap と呼ばれるファイルを作成し、それを以下の 内容にします:
const char * T_PV
次にトップレベルの Makefile.PL で perl を実行します。 mylib ディレクトリにある Makefile も作られるということに注意してください。 make を実行し、それにより mylib ディレクトリに cd し、そこで make が 実行されるのを確認します。
test.pl スクリプトを編集して、BEGIN ブロックを print "1..4" に変更して、 スクリプトの末尾に以下の行を追加します。
print &Mytest2::foo(1, 2, "Hello, world!") == 7 ? "ok 2\n" : "not ok 2\n";
print &Mytest2::foo(1, 2, "0.0") == 7 ? "ok 3\n" : "not ok 3\n";
print abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 ? "ok 4\n" : "not ok 4\n";
(浮動小数点数の比較を行うとき、等しいということをチェックしないことが 最良なのですが、代わりに予想される値と実際の結果の差がある値 (εと呼ばれます)、この場合では 0.01 以内かを調べています)
“make test”を実行すれば、すべてがうまくいくはずです。
先の例とは違って、今回は実際のインクルードファイルに対して h2xs を 実行しました。 これは .pm ファイルと .xs ファイルの両方に対して幾つかの追加されるものを もたらします。
.xs ファイルには、現在のところ絶対パスで mylib.h ヘッダーファイルを 指定する #include 指示子があります。 これを相対パスに変更することで、もし望むならエクステンションの ディレクトリを移動できるようにします。
.xs ファイルに追加された C のコードがあります。
constant ルーチンの目的は、ヘッダーファイルで #define されている値を
Perl スクリプト(この場合は、&Mytest2::TESTVAL の呼び出しによります)に
よってアクセスできるようにすることです。
同様に constant ルーチンを呼び出すための XS コードがあります。
.pm ファイルは元々は配列 @EXPORT にある TESTVAL の名前を
エクスポートします。
これは名前を壊す可能性があります。
よい経験則は #define が C のルーチンでのみ使われてユーザーからは
使われないのであれば、それを配列 @EXPORT から取り除いたほうが
良いというものです。
もう一つは、変数の完全修飾名を使うことを使うのが気にならないのであれば、
配列 @EXPORT にある要素のほとんどすべてを配列 @EXPORT_OK に
移すことができます。
インクルードファイルに #include 指示子あるのであれば、それらは h2xs によって処理されません。 現時点ではこれを正しく処理するのに良い解決策はありません。
私たちはすでにサブディレクトリ mylib で作成したライブラリについての
指示を Perl にしています。
ここで要求されているのは、変数 MYEXTLIB を WriteMakefile の呼び出しに
追加し、postamble サブルーチンを目的のディレクトリへ cd して make を
実行するようにすることだけです。
ライブラリのための Makefile.PL は多少複雑にはなりますが、
それほどでもありません。
このコードは単純に作成すべきライブラリが静的ライブラリ(動的ロード可能
ライブラリと反対のもの)であることを指定し、ライブラリを作成するための
コマンドを提供します。
例 4 の .xs ファイルにはいくつか新しい要素を含んでいます。 これらの要素の意味を理解するために、以下の行に注目してください
MODULE = Mytest2 PACKAGE = Mytest2
この行以前の全てはインクルードするヘッダおよび便利な関数を定義した プレーンな C コードです。 この部分では、組み込みの POD 文書が読み飛ばされる(perlpod を 参照してください)ことを除いては何の変換は行われず、そのまま出力 C ファイルが 出力されます。
この行以降の全ては XSUB 関数の記述です。 これらの記述は、関数を Perl 呼び出し規則を使って実装し、関数が Perl インタプリタから見えるように、xsubpp が C コードに変換します。
constant 関数には特別な注意を払ってください。
この名前は生成された .xs ファイルに 2 回現れます:
1 回目は最初の部分に static C 関数として、2 回目は 2 番目の部分に、
この static C 関数への XSUB インターフェースが定義されたときです。
これは .xs ファイルではかなり典型的です: 普通 .xs ファイルは既にある C 関数へのインターフェースを提供します。 それからこの C 関数はどこか(外部ライブラリか、.xs ファイルの最初の部分)で 定義され、この関数への Perl インターフェース(つまり「Perl の糊」)が .xs ファイルの 2 番目の部分に記述されます。 例 1, 例 2, 例 3 の状況、 つまり全ての動作が「Perl の糊」の内側で行われるときは、 規則ではなく何らかの例外があります。
例 4 で、.xs ファイルの 2 番目の部分には、以下の XSUB の 記述を含んでいます:
double
foo(a,b,c)
int a
long b
const char * c
OUTPUT:
RETVAL
例 1, 例 2, 例 3 と比較して、この記述は
Perl 関数 foo() の呼び出しに何が起きているのかの実際の コード は
含んでいません。
ここで何が起きているのかを理解するために、この XSUB に CODE セクションを
追加できます:
double
foo(a,b,c)
int a
long b
const char * c
CODE:
RETVAL = foo(a,b,c);
OUTPUT:
RETVAL
しかし、これら 2 つの XSUB はほとんど同じ C コードを生成します:
xsubpp コンパイラは、XSUB の記述の最初の 2 行から
CODE: セクションを見つけ出すことができるぐらい賢いです。
OUTPUT: セクションについてはどうでしょう?
実際、これは全く同じです!
CODE: セクションや PPCODE: セクションが指定されない限り、
OUTPUT: セクションも同様に削除でき、同様に OUTPUT セクションを
自動生成します。
従って、XSUB を以下のように省略できます:
double
foo(a,b,c)
int a
long b
const char * c
同じことを 例 2 の XSUB:
int
is_even(input)
int input
CODE:
RETVAL = (input % 2 == 0);
OUTPUT:
RETVAL
で出来るでしょうか?
これをするためには、C 関数 int is_even(int input) を定義する
必要があります。
.xs ファイルの解剖 で見たように、この定義に適切な場所は .xs ファイルの
最初の部分です。
実際、C 関数
int
is_even(int arg)
{
return (arg % 2 == 0);
}
というのはおそらくここではやりすぎです。
#define と同じぐらい単純なこともできます:
#define is_even(arg) ((arg) % 2 == 0)
.xs ファイルの最初の部分にこれを入れた後、 「Perl の糊」の部分は以下のように単純です
int
is_even(input)
int input
実際の動作の部分から糊の部分を分離する技術は明らかなトレードオフです: もし Perl インターフェースをしようとすると、コードの 2 箇所を変更する 必要があります。 しかし、これは多くの乱雑なものを取り除き、実際の動作の部分を Perl 呼び出し 規則の特異性から独立させます。 (実際のところ、上述の記述には Perl 固有のものはなく、異なるバージョンの xsubpp はこれを TCL の糊や Python の糊にも変換できるかもしれません。)
例 4 を補完するために、私たちは世界で最もクリーンというわけではないであろう 現実のライブラリのシミュレートをするための簡単な方法があります。 私たちは xsubpp コンパイラに渡す引数についての議論を 続けなければなりません。
.xs ファイルでルーチンへの引数を指定したとき、あなたはそれぞれの 引数がリストアップされた三つの情報ブロックを渡しているでしょう。 最初のブロックは、引数の相対的な順序(一番目、二番目、…)です。 二番目のブロックは引数の型で、引数の型宣言からなります。 三番目のブロックは、引数がライブラリ関数を呼び出すときに使われる引数の 呼び出し規約です。
Perl は関数に引数を参照渡ししますが、C は引数を値渡しします; 「引数」の 一つのデータを修正する C 関数を実装するには、この C 関数の実際の引数は そのデータへのポインタになります。 従って、2 つの C 関数宣言:
int string_length(char *s);
int upper_case_char(char *cp);
may have completely different semantics: the first one may inspect an array
of chars pointed by s, and the second one may immediately dereference cp
and manipulate *cp only (using the return value as, say, a success
indicator). From Perl one would use these functions in
a completely different manner.
(TBT)
& による引数の前に * を置き換えることで、この情報を xsubpp に
伝えられます。
& は、引数がアドレスでライブラリ関数に渡されることを意味します。
上記の 2 つの関数は以下のように XSUB 化できます
int
string_length(s)
char * s
int
upper_case_char(cp)
char &cp
例として、次のものを考えます:
int
foo(a,b)
char &a
char * b
最初の Perl の引数はこの関数では char として扱われ、変数 a に代入され、 そしてそのアドレスは関数 foo に渡されます。 二番目の Perl の引数は文字列へのポインターとして扱われ、変数 b へ 代入されます。 b の 値 も関数 foo へ渡されます。 xsubpp が生成する関数 foo への実際の呼び出しは次のようになります。
foo(&a, b);
xsubpp は以下の関数引数リストを同じものと解析します:
char &a
char&a
char & a
しかしながらわかりやすくするために、“&”に変数名を続けて変数の型からは 離しておくことと、“*”を型名に近づけるが変数名からは離す(前述した foo の 呼び出しのように)ということをお勧めします。 これを行うことで、実際に C の関数に渡されるがなんなのかを簡単に 理解できます -- これは“last column”にあるものでしょう。
可能ならば、関数に(自分が望む)変数の型を渡すことに挑戦して苦労したほうが 良いでしょう。 長い目で見ればそれによって多くのトラブルを避けることになります。
例 1 以外の このチュートリアルで作成した C コードを見たのならば、
たくさんのST(n) (n は通常は 0)に対する参照に気がついたことでしょう。
“ST”は実際には引数スタック上の n 番目の引数を指し示すマクロです。
従って ST(0) はスタック上の最初の引数なので、XSUB に渡される最初の
引数であり、ST(1) は二番目の引数となります。
.xs ファイル中で XSUB に対する引数をリストアップしたとき、それは引数 スタックの対応する引数を xsubpp に指定するということです(例えば、 リストの最初にあれば第一引数、二番目なら第二引数ということ)。 関数が期待するのと同じ順番でリストアップしなければ、思いがけない 災害を招くことになります。
引数スタックの実際の値は渡された値へのポインタです。
When an argument is listed as being an OUTPUT value, its corresponding
value on the stack (i.e., ST(0) if it was the first argument) is changed.
You can verify this by looking at the C code generated for Example 3.
The code for the round() XSUB routine contains lines that look like this:
(TBT)
double arg = (double)SvNV(ST(0));
/* Round the contents of the variable arg */
sv_setnv(ST(0), (double)arg);
引数変数は、まず ST(0) の値から取られるものにセットされ、その後ルーチンの
最後に ST(0) に書き戻されます。
XSUB は単なるスカラではなく、リストを返すこともできます。
これはスタック値 ST(0), ST(1) などを微妙に違う方法で操作することによって
行う必要があります。
詳しくは perlxs を参照してください。
XSUBs are also allowed to avoid automatic conversion of Perl function arguments
to C function arguments. See perlxs for details. Some people prefer
manual conversion by inspecting ST(i) even in the cases when automatic
conversion will do, arguing that this makes the logic of an XSUB call clearer.
Compare with 太った部分を XSUB の外に出す for a similar tradeoff of
a complete separation of "Perl glue" and "workhorse" parts of an XSUB.
(TBT)
While experts may argue about these idioms, a novice to Perl guts may prefer a way which is as little Perl-guts-specific as possible, meaning automatic conversion and automatic call generation, as in 太った部分を XSUB の外に出す. This approach has the additional benefit of protecting the XSUB writer from future changes to the Perl API. (TBT)
Perlとあなたのエクステンションとの間のインターフェースをより簡単に、 より理解しやすくするのを助けるためにメソッドやサブルーチンを 作りたいと思う事があるかもしれません。 こういったルーチンは .pm ファイルに置くのが良いです。 これがエクステンション自身がロードされたときロードされるにしろ、 サブルーチン定義が置かれている. pm ファイルに依存する呼び出しのときのみ ロードするにしろ、自動的にロードが行われます。 追加のサブルーチンを保管して読み込むもう一つの方法としては AutoLoader を参考にすることもできます。
あなたのエクステンションに関するドキュメントがないということについて、 あなたは何の言い訳もできません。 ドキュメントは .pm ファイルに属します。 このファイルは pod2man に送り込まれ、埋め込まれたドキュメントが マニュアルページフォーマットに変換されます。 その後で blib ディレクトリに置かれます。 このドキュメントは、エクステンションがインストールされるときに Perl の マニュアルページディレクトリにもコピーされます。
あなたは .pm ファイルにあるドキュメントと Perl コードをまき散らすことが あるかもしれません。 事実、あなたがメソッドを autoload しようとするならば、.pm ファイルの中に あるコメントで説明されているようにこれを行わねばなりません。
pod フォーマットについてのより詳しい情報は perlpod を参照してください。
あなたの作ったエクステンションが完成し、かつすべてのテストに合格すれば、 それを実に単純なやりかたでインストールします。 ただ単に“make install”と実行するだけです。 Perl がインストールされたディレクトリに対する書き込み権限が持っている 必要がありますが、あるいは、あなたのシステム管理者にあなたの make を 実行するようお願いする必要があるでしょう。
Alternately, you can specify the exact directory to place the extension's files by placing a "PREFIX=/destination/directory" after the make install. (or in between the make and install if you have a brain-dead version of make). This can be very useful if you are building an extension that will eventually be distributed to multiple systems. You can then just archive the files in the destination directory and distribute them to your destination systems. (TBT)
この例では、引数スタックにさらなる作業をします。 前の例では全て、単一の値を返すものだけです。 ここでは、配列を返すエクステンションを作ります。
このエクステンションはとても Unix 指向です(struct statfs と statfs システムコール)。 もし Unix システム以外で実行するなら、statfs を複数の値を返す別の関数に 置き換えるか、呼び出し元に返す値をハードコーディングする(しかしこれは エラーの場合をテストするのが少し難しくなります)か、あるいは単に この例を実行しないということもできます。 もし XSUB を変更したなら、テストケースも変更にあわせて確実に 修正してください。
Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します:
void
statfs(path)
char * path
INIT:
int i;
struct statfs buf;
PPCODE:
i = statfs(path, &buf);
if (i == 0) {
XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[0])));
XPUSHs(sv_2mortal(newSVnv(buf.f_fsid[1])));
} else {
XPUSHs(sv_2mortal(newSVnv(errno)));
}
また、.xs ファイルの先頭、"XSUB.h" をインクルードした直後に、以下のコードを 追加する必要があります:
#include <sys/vfs.h>
また、以下のコードを test.pl に追加する一方、BEGIN ブロックの "1..9" という 文字列を "1..11" に増やします:
@a = &Mytest::statfs("/blech");
print ((scalar(@a) == 1 && $a[0] == 2) ? "ok 10\n" : "not ok 10\n");
@a = &Mytest::statfs("/");
print scalar(@a) == 9 ? "ok 11\n" : "not ok 11\n";
この例はいくつかの全く新しい概念を追加します。 一回に一つずつやります。
The INIT: directive contains code that will be placed immediately after
the argument stack is decoded. C does not allow variable declarations at
arbitrary locations inside a function,
so this is usually the best way to declare local variables needed by the XSUB.
(Alternatively, one could put the whole PPCODE: section into braces, and
put these declarations on top.)
(TBT)
This routine also returns a different number of arguments depending on the success or failure of the call to statfs. If there is an error, the error number is returned as a single-element array. If the call is successful, then a 9-element array is returned. Since only one argument is passed into this function, we need room on the stack to hold the 9 values which may be returned. (TBT)
We do this by using the PPCODE: directive, rather than the CODE: directive. This tells xsubpp that we will be managing the return values that will be put on the argument stack by ourselves. (TBT)
When we want to place values to be returned to the caller onto the stack, we use the series of macros that begin with "XPUSH". There are five different versions, for placing integers, unsigned integers, doubles, strings, and Perl scalars on the stack. In our example, we placed a Perl scalar onto the stack. (In fact this is the only macro which can be used to return multiple values.) (TBT)
The XPUSH* macros will automatically extend the return stack to prevent it from being overrun. You push values onto the stack in the order you want them seen by the calling program. (TBT)
The values pushed onto the return stack of the XSUB are actually mortal SV's. They are made mortal so that once the values are copied by the calling program, the SV's that held the returned values can be deallocated. If they were not mortal, then they would continue to exist after the XSUB routine returned, but would not be accessible. This is a memory leak. (TBT)
If we were interested in performance, not in code compactness, in the success
branch we would not use XPUSHs macros, but PUSHs macros, and would
pre-extend the stack before pushing the return values:
(TBT)
EXTEND(SP, 9);
The tradeoff is that one needs to calculate the number of return values in advance (though overextending the stack will not typically hurt anything but memory consumption). (TBT)
Similarly, in the failure branch we could use PUSHs without extending
the stack: the Perl function reference comes to an XSUB on the stack, thus
the stack is always large enough to take one return value.
(TBT)
In this example, we will accept a reference to an array as an input parameter, and return a reference to an array of hashes. This will demonstrate manipulation of complex Perl data types from an XSUB. (TBT)
This extension is somewhat contrived. It is based on the code in the previous example. It calls the statfs function multiple times, accepting a reference to an array of filenames as input, and returning a reference to an array of hashes containing the data for each of the filesystems. (TBT)
Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します:
SV *
multi_statfs(paths)
SV * paths
INIT:
AV * results;
I32 numpaths = 0;
int i, n;
struct statfs buf;
if ((!SvROK(paths))
|| (SvTYPE(SvRV(paths)) != SVt_PVAV)
|| ((numpaths = av_len((AV *)SvRV(paths))) < 0))
{
XSRETURN_UNDEF;
}
results = (AV *)sv_2mortal((SV *)newAV());
CODE:
for (n = 0; n <= numpaths; n++) {
HV * rh;
STRLEN l;
char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);
i = statfs(fn, &buf);
if (i != 0) {
av_push(results, newSVnv(errno));
continue;
}
rh = (HV *)sv_2mortal((SV *)newHV());
hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
hv_store(rh, "f_bfree", 7, newSVnv(buf.f_bfree), 0);
hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
hv_store(rh, "f_bsize", 7, newSVnv(buf.f_bsize), 0);
hv_store(rh, "f_ffree", 7, newSVnv(buf.f_ffree), 0);
hv_store(rh, "f_files", 7, newSVnv(buf.f_files), 0);
hv_store(rh, "f_type", 6, newSVnv(buf.f_type), 0);
av_push(results, newRV((SV *)rh));
}
RETVAL = newRV((SV *)results);
OUTPUT:
RETVAL
また、以下のコードを test.pl に追加する一方、BEGIN ブロックの "1..11" という 文字列を "1..13" に増やします:
$results = Mytest::multi_statfs([ '/', '/blech' ]);
print ((ref $results->[0]) ? "ok 12\n" : "not ok 12\n");
print ((! ref $results->[1]) ? "ok 13\n" : "not ok 13\n");
ここでは後述するいくつかの新しい概念があります:
This function does not use a typemap. Instead, we declare it as accepting
one SV* (scalar) parameter, and returning an SV* value, and we take care of
populating these scalars within the code. Because we are only returning
one value, we don't need a PPCODE: directive - instead, we use CODE:
and OUTPUT: directives.
(TBT)
When dealing with references, it is important to handle them with caution.
The INIT: block first checks that
SvROK returns true, which indicates that paths is a valid reference. It
then verifies that the object referenced by paths is an array, using SvRV
to dereference paths, and SvTYPE to discover its type. As an added test,
it checks that the array referenced by paths is non-empty, using the av_len
function (which returns -1 if the array is empty). The XSRETURN_UNDEF macro
is used to abort the XSUB and return the undefined value whenever all three of
these conditions are not met.
(TBT)
We manipulate several arrays in this XSUB. Note that an array is represented
internally by an AV* pointer. The functions and macros for manipulating
arrays are similar to the functions in Perl: av_len returns the highest
index in an AV*, much like $#array; av_fetch fetches a single scalar value
from an array, given its index; av_push pushes a scalar value onto the
end of the array, automatically extending the array as necessary.
(TBT)
Specifically, we read pathnames one at a time from the input array, and store the results in an output array (results) in the same order. If statfs fails, the element pushed onto the return array is the value of errno after the failure. If statfs succeeds, though, the value pushed onto the return array is a reference to a hash containing some of the information in the statfs structure. (TBT)
As with the return stack, it would be possible (and a small performance win) to pre-extend the return array before pushing data into it, since we know how many elements we will return: (TBT)
av_extend(results, numpaths);
We are performing only one hash operation in this function, which is storing
a new scalar under a key using hv_store. A hash is represented by an HV*
pointer. Like arrays, the functions for manipulating hashes from an XSUB
mirror the functionality available from Perl. See perlguts and perlapi
for details.
(TBT)
To create a reference, we use the newRV function. Note that you can
cast an AV* or an HV* to type SV* in this case (and many others). This
allows you to take references to arrays, hashes and scalars with the same
function. Conversely, the SvRV function always returns an SV*, which may
need to be cast to the appropriate type if it is something other than a
scalar (check with SvTYPE).
(TBT)
この時点で、xsubpp はほとんど何もしていません - Mytest.xs と Mytest.c との 差は最小限です。
引数の XPUSH と RETVAL のセットと返り値の配列への代入
$! をセットする
型グロブなどで、XS にファイルを渡すのは難しいと考えるかもしれません。 えっと、そうではありません。
標準 C ライブラリ関数 fputs() のラッパーが必要、という不思議な
理由があるとしましょう。
必要なものは以下のものだけです:
#define PERLIO_NOT_STDIO 0
#include "EXTERN.h"
#include "perl.h"
#include "XSUB.h"
#include <stdio.h>
int
fputs(s, stream)
char * s
FILE * stream
実際の作業は標準の typemap で行われます。
しかし、perlio 層で行われる素晴らしい機能全てを手放すことになります。
これは stdio 関数 fputs() を呼び出すので、それらについては何もしません。
The standard typemap offers three variants of PerlIO *:
InputStream (T_IN), InOutStream (T_INOUT) and OutputStream
(T_OUT). A bare PerlIO * is considered a T_INOUT. If it matters
in your code (see below for why it might) #define or typedef
one of the specific names and use that as the argument or result
type in your XS file.
(TBT)
The standard typemap does not contain PerlIO * before perl 5.7, but it has the three stream variants. Using a PerlIO * directly is not backwards compatible unless you provide your own typemap. (TBT)
For streams coming from perl the main difference is that
OutputStream will get the output PerlIO * - which may make
a difference on a socket. Like in our example...
(TBT)
For streams being handed to perl a new file handle is created
(i.e. a reference to a new glob) and associated with the PerlIO *
provided. If the read/write state of the PerlIO * is not correct then you
may get errors or warnings from when the file handle is used.
So if you opened the PerlIO * as "w" it should really be an
OutputStream if open as "r" it should be an InputStream.
(TBT)
ここで、XS で perlio 層を使いたいとしましょう。
例のように、perlio の PerlIO_puts() 関数を使います。
XS ファイルの C の部分 (最初の MODULE 行の上) に以下のようにします
#define OutputStream PerlIO *
or
typedef PerlIO * OutputStream;
そして XS コードはこれです:
int
perlioputs(s, stream)
char * s
OutputStream stream
CODE:
RETVAL = PerlIO_puts(stream, s);
OUTPUT:
RETVAL
PerlIO_puts() は fputs() と比較する予約された引数を持っていて、
引数は同じままにしたいので、CODE セクションを使う必要があります。
これを完全に探索するために、PerlIO * に stdio の fputs() を使いたいです。
これは、perlio システムに stdio の FILE * を問い合わせる必要があります:
int
perliofputs(s, stream)
char * s
OutputStream stream
PREINIT:
FILE *fp = PerlIO_findFILE(stream);
CODE:
if (fp != (FILE*) 0) {
RETVAL = fputs(s, fp);
} else {
RETVAL = -1;
}
OUTPUT:
RETVAL
Note: PerlIO_findFILE() will search the layers for a stdio
layer. If it can't find one, it will call PerlIO_exportFILE() to
generate a new stdio FILE. Please only call PerlIO_exportFILE() if
you want a new FILE. It will generate one on each call and push a
new stdio layer. So don't call it repeatedly on the same
file. PerlIO()_findFILE will retrieve the stdio layer once it has been
generated by PerlIO_exportFILE().
(TBT)
これは perlio システムにのみ適用されます。
5.7 以前のバージョンでは、PerlIO_exportFILE() は PerlIO_findFILE() と
等価です。
この文書の最初に触れたように、もしこれらの例のエクステンションで問題が あった場合、以下が参考になるかもしれません。
γバージョン以前のバージョン 5.002 では、Example 1 にあるテスト スクリプトは正しく動作しません。 "use lib" という行を以下の様に変更する必要があります。
use lib './blib';
バージョン 5.002b1h 以前のバージョン 5.002 では、test.pl というファイルが h2xs によって自動生成されません。 これはテストスクリプトを実行するために、"make test" とすることが できないということです。 "use extension" という文の前に以下の行を追加する必要があります:
use lib './blib';
バージョン 5.000 および 5.001 では、上で示した行ではなく、以下に示した行を 使う必要があるでしょう。
BEGIN { unshift(@INC, "./blib") }
このドキュメントでは、"perl" という名前の実行ファイルが Perl のバージョン 5 であることを仮定しています。 Perl のバージョン 5 は "perl5" としてインストールされているシステムも あるかもしれません。
より詳しい情報は、perlguts, perlapi, perlxs, perlmod, perlpod を参照してください。
Jeff Okamoto <okamoto@corp.hp.com>
Dean Roehrich, Ilya Zakharevich, Andreas Koenig, Tim Bunce によるレビューと 助力を受けました。
PerlIO の素材は Lupe Christoph によって提供され、Nick Ing-Simmons によって 明確化されたものです。
2002/05/08