perlXStut - XSUB を書くためのチュートリアル This tutorial will educate the reader on the steps involved in creating a Perl extension. The reader is assumed to have access to perlguts, perlapi and perlxs. このチュートリアルは読者にPerlのエクステンションを作るのに必要な ステップを教えるものです。 読者が perlguts, perlapi, perlxs にアクセスできるということを 仮定しています。 This tutorial starts with very simple examples and becomes more complex, with each new example adding new features. Certain concepts may not be completely explained until later in the tutorial in order to slowly ease the reader into building extensions. このチュートリアルは非常に単純な例から始めて、新しい例に進むごとに 新たな機能を付加えたより複雑なものへとなります。 幾つかのコンセプトは、読者がエクステンションを作成するのが徐々に 簡単になるように、チュートリアルの後のほうまで完全には説明されません。 This tutorial was written from a Unix point of view. Where I know them to be otherwise different for other platforms (e.g. Win32), I will list them. If you find something that was missed, please let me know. このチュートリアルは Unix の観点から書かれています。 (Win32 のように)ほかのプラットフォームでは異なることになると知っている 場所では、それを記しています。 何か見落としを発見したら、ぜひ教えてください。 (特別な注意) This tutorial assumes that the make program that Perl is configured to use is called make. Instead of running "make" in the examples that follow, you may have to substitute whatever make program Perl has been configured to use. Running perl -V:make should tell you what it is. このチュートリアルでは、Perl が使用するように設定されている make プログラムが make という名前であると想定しています。 以下の例で "make" を実行する代わりに、Perl が使うように設定された他の make プログラムを代用する必要があるかもしれません。 perl -V:make とすると、それが何かがわかります。 (バージョンに関する警告) When writing a Perl extension for general consumption, one should expect that the extension will be used with versions of Perl different from the version available on your machine. Since you are reading this document, the version of Perl on your machine is probably 5.005 or later, but the users of your extension may have more ancient versions. 一般向けに Perl エクステンションを書くとき、あなたのマシンで 利用可能なバージョンと異なるバージョンの Perl でエクステンションが 使われることを想定するべきです。 この文書を読んでいるということは、あなたのマシンの Perl のバージョンは おそらく 5.005 以降でしょうが、エクステンションのユーザーはもっと古い バージョンかもしれません。 To understand what kinds of incompatibilities one may expect, and in the rare case that the version of Perl on your machine is older than this document, see the section on "Troubleshooting these Examples" for more information. どのような非互換性が想定されるかを理解するために、また珍しい場合として、 マシンに入っている Perl のバージョンがこのドキュメントより古い場合、 さらなる情報は "Troubleshooting these Examples" の章を参照してください。 If your extension uses some features of Perl which are not available on older releases of Perl, your users would appreciate an early meaningful warning. You would probably put this information into the README file, but nowadays installation of extensions may be performed automatically, guided by CPAN.pm module or other tools. もしエクステンションが、Perl の古いリリースでは利用できないような Perl の 機能を使っているなら、ユーザーは早期の意味のある警告で理解します。 おそらくこの情報を README ファイルに追加するべきでしょうが、最近の エクステンションのインストールは、CPAN.pm モジュールやその他の ツールによって自動的に行われるかもしれません。 In MakeMaker-based installations, Makefile.PL provides the earliest opportunity to perform version checks. One can put something like this in Makefile.PL for this purpose: MakeMaker ベースのインストールでは、Makefile.PL が、プラットフォームの バージョンチェックの最も早い機会を提供します。 この目的のために、以下のようなものを Makefile.PL に書けます: (動的読み込み対静的読み込み) It is commonly thought that if a system does not have the capability to dynamically load a library, you cannot build XSUBs. This is incorrect. You can build them, but you must link the XSUBs subroutines with the rest of Perl, creating a new executable. This situation is similar to Perl 4. 一般的には、システムがライブラリを動的にロードする機能を持っていなければ XSUB を作成することはできないと考えられています。 これは正しくありません。 あなたは XSUB を作ることが できます。 ただし、あなたはその XSUB のサブルーチンと、Perl とをリンクして新たな 実行ファイルを作らなければなりません。 この状況は perl4 と同じです。 This tutorial can still be used on such a system. The XSUB build mechanism will check the system and build a dynamically-loadable library if possible, or else a static library and then, optionally, a new statically-linked executable with that static library linked in. このチュートリアルはまだそういったシステムを使っていても大丈夫です。 XSUB の作成機能は、システムをチェックして可能であれば動的ロード可能 ライブラリを作成し、できなければスタティックライブラリを作成してから そのスタティックライブラリをリンクしてスタティックリンクされた 実行ファイルを作成します(最後の部分はオプション)。 Should you wish to build a statically-linked executable on a system which can dynamically load libraries, you may, in all the following examples, where the command "make" with no arguments is executed, run the command "make perl" instead. これからの例を使って、動的ロード可能ライブラリが使えるシステムで あってもスタティックリンクされた実行ファイルを作成したいという場合、 "make"という引数なしのコマンドを実行する代わりに、 "make perl" というコマンドを実行してください。 If you have generated such a statically-linked executable by choice, then instead of saying "make test", you should say "make test_static". On systems that cannot build dynamically-loadable libraries at all, simply saying "make test" is sufficient. もしスタティックリンクされた実行ファイルを作成することを選んだのなら、 "make test" の代わりに "make test_static" を使ってください。 動的ロード可能ライブラリが作成できないシステムの場合には単に "make test" とするだけで OK です。 (チュートリアル) Now let's go on with the show! では、見ていきましょう! (例 1) Our first extension will be very simple. When we call the routine in the extension, it will print out a well-known message and return. 最初のエクステンションは非常に単純です。 エクステンションの中でルーチンを呼び出すときに、良く知られたメッセージを 出力してリターンします。 Run "h2xs -A -n Mytest". This creates a directory named Mytest, possibly under ext/ if that directory exists in the current working directory. Several files will be created in the Mytest dir, including MANIFEST, Makefile.PL, Mytest.pm, Mytest.xs, Mytest.t, and Changes. "h2xs -A -n Mytest" を実行します。 これは Mytest という名前のディレクトリを作成しますが、カレントの 作業ディレクトリに ext/ というディレクトリがあればその下に作成します。 MANIFEST, Makefile.PL, Mytest.pm, Mytest.xs, Mytest.t, Changes を含めた 幾つかのファイルがディレクトリ Mytest の下に作成されます。 The MANIFEST file contains the names of all the files just created in the Mytest directory. MANIFEST というファイルには Mytest ディレクトリに生成されたファイル すべてのファイル名があります。 The file Makefile.PL should look something like this: Makefile.PL というファイルは以下のような形式であるべきです。 'Mytest', VERSION_FROM => 'Mytest.pm', # finds $VERSION LIBS => [''], # e.g., '-lm' DEFINE => '', # e.g., '-DHAVE_SOMETHING' INC => '', # e.g., '-I/usr/include/other' ); ]]> The file Mytest.pm should start with something like this: Mytest.pm は以下のような内容で始まります。 [ qw( ]]> The rest of the .pm file contains sample code for providing documentation for the extension. .pm ファイルの残りはエクステンションのためのドキュメントをを提供するための サンプルコードからなります。 Finally, the Mytest.xs file should look something like this: 最後に、Mytest.xs の内容は以下のようになります。 Let's edit the .xs file by adding this to the end of the file: .xs ファイルの終わりに以下の行を追加します。 It is okay for the lines starting at the "CODE:" line to not be indented. However, for readability purposes, it is suggested that you indent CODE: one level and the lines following one more level. "CODE:" で始まる行がインデントされていないのは問題ありません。 しかし、読みやすさの観点から、CODE: を 1 レベルインデントして、 引き続く行をさらに 1 レベルインデントすることを勧めます。 Now we'll run "perl Makefile.PL". This will create a real Makefile, which make needs. Its output looks something like: ここで、"perl Makefile.PL" を実行します。 これで make が必要とする本当の Makefile が生成されます。 この出力は以下のようになります: Now, running make will produce output that looks something like this (some long lines have been shortened for clarity and some extraneous lines have been deleted): ここでmakeを実行すれば、以下のような出力が生成されます (一部の長い行は明快さを保つために短くし、一部の余分な行は削除しています): Mytest.xsc && mv Mytest.xsc Mytest.c Please specify prototyping behavior for Mytest.xs (see perlxs manual) cc -c Mytest.c Running Mkbootstrap for Mytest () chmod 644 Mytest.bs rm -f blib/arch/auto/Mytest/Mytest.so cc -shared -L/usr/local/lib Mytest.o -o blib/arch/auto/Mytest/Mytest.so \ \ ]]> You can safely ignore the line about "prototyping behavior" - it is explained in the section "The PROTOTYPES: Keyword" in perlxs. "prototyping behavior" に関する行は安全に無視できます - これは perlxs の "The PROTOTYPES: Keyword" の章で説明されています。 If you are on a Win32 system, and the build process fails with linker errors for functions in the C library, check if your Perl is configured to use PerlCRT (running perl -V:libc should show you if this is the case). If Perl is configured to use PerlCRT, you have to make sure PerlCRT.lib is copied to the same location that msvcrt.lib lives in, so that the compiler can find it on its own. msvcrt.lib is usually found in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib). Win32 システムの場合で、C ライブラリ中の関数に関するリンカのエラーで ビルド処理が失敗する場合、Perl が PerlCRT を使うように設定されているかを 調べて見てください (この場合、perl -V:libc を実行すればわかるはずです)。 もし Perl が PerlCRT を使うように設定されているなら、PerlCRT.lib を msvcrt.lib と同じ位置にコピーして、コンパイラがこれを見つけられるように する必要があります。 msvcrt.lib は普通 Visual C コンパイラの lib ディレクトリ (例えば C:/DevStudio/VC/lib) にあります。 Perl has its own special way of easily writing test scripts, but for this example only, we'll create our own test script. Create a file called hello that looks like this: Perl にはテストスクリプトを簡単に書くための独自の特別な方法がありますが、 この例のためだけに、自分でテストスクリプトを作ります。 hello という名前の、以下のような内容のファイルを作ります。 Now we make the script executable (chmod +x hello), run the script and we should see the following output: ここでスクリプトを実行可能にして(chmod +x hello)から実行すれば、 以下のような出力になるはずです。 (例 2) Now let's add to our extension a subroutine that will take a single numeric argument as input and return 0 if the number is even or 1 if the number is odd. 今度は、数値引数を入力として一つ取り、その数値が偶数なら 1 を、奇数なら 0 を返すようなサブルーチンを追加しましょう。 Add the following to the end of Mytest.xs: Mytest.xs の最後に以下の行を追加します。 There does not need to be whitespace at the start of the "int input" line, but it is useful for improving readability. Placing a semi-colon at the end of that line is also optional. Any amount and kind of whitespace may be placed between the "int" and "input". "int input" の行の始めにある空白は必須ではありませんが、これがあると 読みやすさが増します。 同様に、行末のセミコロンも省略可能です。 任意の空白を "int" と "input" の間に置くことができます。 Now re-run make to rebuild our new shared library. make を再度実行して、新たな共有ライブラリを作ります。 Now perform the same steps as before, generating a Makefile from the Makefile.PL file, and running make. 前のステップと同じように、Makefile.PL から Makefile を作って make を実行します。 In order to test that our extension works, we now need to look at the file Mytest.t. This file is set up to imitate the same kind of testing structure that Perl itself has. Within the test script, you perform a number of tests to confirm the behavior of the extension, printing "ok" when the test is correct, "not ok" when it is not. 作成したエクステンションが動作するかを確認するために、Mytest.t の ようなファイルが必要となります。 このファイルは Perl 自身が持っている構造をチェックするのと同様のものを 模倣して作ります。 テストスクリプトの中では、エクステンションの動作を確認するたくさんの テストを置き、正しい動作をしたら "ok" を正しくなければ "not ok" を 出力するようにします。 BEGIN ブロックにある文を print "1..4" に変え、ファイルの末尾に以下の行を 追加します。 4; BEGIN { use_ok('Mytest') }; ]]> We will be calling the test script through the command "make test". You should see output that looks something like this: "make test" というコマンドでテストスクリプトを呼び出します。 以下のような出力が出るはずです。 (何をしたの?) The program h2xs is the starting point for creating extensions. In later examples we'll see how we can use h2xs to read header files and generate templates to connect to C routines. プログラム h2xs はエクステンションを作成する出発点となります。 後の例では、ヘッダファイルを読み込んで C のルーチンに対する 接点のテンプレートを生成するのに h2xs をどのように使うかを示します。 h2xs creates a number of files in the extension directory. The file Makefile.PL is a perl script which will generate a true Makefile to build the extension. We'll take a closer look at it later. h2xs はエクステンションのディレクトリに数多くのファイルを作成します。 Makefile.PL というファイルはエクステンションを作成するための 本当の Makefile を生成する perl スクリプトです。 詳細は後述します。 The .pm and .xs files contain the meat of the extension. The .xs file holds the C routines that make up the extension. The .pm file contains routines that tell Perl how to load your extension. .pm と .xs といったファイルはエクステンションの本体を含みます。 .xs ファイルにはエクステンションを作るための C のルーチンがあります。 .pm ファイルには Perl がどのようにあなたの作ったエクステンションを ロードするかを指示するルーチンがあります。 Generating the Makefile and running make created a directory called blib (which stands for "build library") in the current working directory. This directory will contain the shared library that we will build. Once we have tested it, we can install it into its final location. Makefile を生成し、make を実行することでカレントの作業ディレクトリの 下に blib ( "build library" を意味します)と呼ばれるディレクトリが 作られます。 このディレクトリには、私たちが作成する共有ライブラリが置かれます。 一度それをテストすれば、最終的な場所にインストールすることができます。 Invoking the test script via "make test" did something very important. It invoked perl with all those -I arguments so that it could find the various files that are part of the extension. It is very important that while you are still testing extensions that you use "make test". If you try to run the test script all by itself, you will get a fatal error. Another reason it is important to use "make test" to run your test script is that if you are testing an upgrade to an already-existing version, using "make test" ensures that you will test your new extension, not the already-existing version. "make test" 経由でテストスクリプトを実行することによって、非常に重要な 幾つかのことを行います。 これは perl に -I 引数を付けて起動し、これによりエクステンションの 一部である様々なファイルを見つけることができるようにします。 エクステンションをテストするのに "make test" を使うのは 非常に 重要です。 もし、テストスクリプトをそのまま実行してしまったら、致命的なエラーが 発生するでしょう。 テストスクリプトを実行するのに "make test" を使うもう一つの重大な 理由は、既にあるエクステンションをアップグレードしたものを テストしようとしたときに、"make test" を使っていれば、既に あるものではなく、新しいものをテストすることが保証されるためです。 When Perl sees a use extension;, it searches for a file with the same name as the use'd extension that has a .pm suffix. If that file cannot be found, Perl dies with a fatal error. The default search path is contained in the @INC array. Perl が use extension; という行を見つけたとき、use する エクステンションと同じ名前で .pm という拡張を持つファイルを検索します。 もしそういったファイルが見つからなければ、Perl は致命的エラーにより 終了します。 デフォルトの検索パスは @INC という配列に置かれます。 In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic Loader extensions. It then sets the @ISA and @EXPORT arrays and the $VERSION scalar; finally it tells perl to bootstrap the module. Perl will call its dynamic loader routine (if there is one) and load the shared library. Mytest.pm は perl に Exporter エクステンション と Dynamic Loader エクステンションが必要であるいうことを教えます。 この後配列 @ISA, @EXPORT とスカラー $VERSION に値を設定し、最後に モジュールをブートストラップするように perl に指示します。 perl はそのダイナミックローダールーチンを(あれば)呼び出し、共有ライブラリを ロードします。 The two arrays @ISA and @EXPORT are very important. The @ISA array contains a list of other packages in which to search for methods (or subroutines) that do not exist in the current package. This is usually only important for object-oriented extensions (which we will talk about much later), and so usually doesn't need to be modified. @ISA と @EXPORT の二つの配列は非常に重要です。 配列 @ISA には、メソッド(もしくはサブルーチン)がカレントパッケージに なかったときに探しに行く他のパッケージのリストがあります。 これは普通オブジェクト指向エクステンション(これについてはずっと後の方で 議論します)でのみ重要なので、普通は修正する必要はありません。 The @EXPORT array tells Perl which of the extension's variables and subroutines should be placed into the calling package's namespace. Because you don't know if the user has already used your variable and subroutine names, it's vitally important to carefully select what to export. Do not export method or variable names by default without a good reason. 配列 @EXPORT は Perl に対して、呼び出されたときにパッケージの名前空間に 置くべきエクステンションの変数とサブルーチンを指示します。 ユーザーが既にあなたの変数名やサブルーチン名を使っているかどうかは わからないので、何をエクスポートするかを慎重に選択することは極めて 重要です。 何かそうするべき理由がない限りは、メソッド名や変数名を デフォルトでは エクスポート しない ようにしてください。 As a general rule, if the module is trying to be object-oriented then don't export anything. If it's just a collection of functions and variables, then you can export them via another array, called @EXPORT_OK. This array does not automatically place its subroutine and variable names into the namespace unless the user specifically requests that this be done. 一般的な規則として、モジュールがオブジェクト指向しようとした場合には 何もエクスポートしません。 モジュールが単なる関数と変数の集まりであれば、別の配列 @EXPORT_OK を 通じてそれらをエクスポートできます。 この配列は、ユーザーがそうしてほしと明示的に指定しない限り、 自動的にはサブルーチン名と変数名を名前空間に置きません。 See perlmod for more information. 詳細は perlmod を参照してください。 The $VERSION variable is used to ensure that the .pm file and the shared library are "in sync" with each other. Any time you make changes to the .pm or .xs files, you should increment the value of this variable. 変数 $VERSION は .pm ファイルと共有ライブラリがそれぞれ 「同期している」ことを保証します。 .pm ファイルや .xs ファイルを変更したとき、この変数の値を 増加させるべきです。 (良いテストスクリプトを書く) The importance of writing good test scripts cannot be over-emphasized. You should closely follow the "ok/not ok" style that Perl itself uses, so that it is very easy and unambiguous to determine the outcome of each test case. When you find and fix a bug, make sure you add a test case for it. 良いテストスクリプトを書くことの重要性は、いくら強調しても足りません。 Perl 自身が使っている "ok/not ok" の形式を忠実に守り、テストケースで どうなったかを簡単に、曖昧なことなくわかるようにします。 バグを発見して修正したら、テストケースにそれを追加しましょう。 By running "make test", you ensure that your Mytest.t script runs and uses the correct version of your extension. If you have many test cases, save your test files in the "t" directory and use the suffix ".t". When you run "make test", all of these test files will be executed. "make test" を実行することにより、正しいスクリプト Mytest.t を実行して 適切なバージョンのエクステンションを使うことが保証されます。 たくさんのテストケースがあるのなら、 "t" という名前のディレクトリに、".t" の拡張子でテストファイルを保存します。 "make test" を実行すると、これらのテストファイル全てが実行されます。 (例 3) Our third extension will take one argument as its input, round off that value, and set the argument to the rounded value. 三番目の例は、入力として引数を一つとってその値を丸めてからその結果を 引数にセットするというものです。 Add the following to the end of Mytest.xs: 以下の行を Mytest.xs の末尾に追加してください: 0.0) { arg = floor(arg + 0.5); } else if (arg < 0.0) { arg = ceil(arg - 0.5); } else { arg = 0.0; } OUTPUT: arg ]]> Edit the Makefile.PL file so that the corresponding line looks like this: Makefile.pl というファイルを編集し、対応する行を以下に示すように してください。 ['-lm'], # e.g., '-lm' ]]> Generate the Makefile and run make. Change the test number in Mytest.t to "9" and add the following tests: Makefile を生成してから make を実行します。 Mytest.t のテスト番号を "9" に変更し、さらに以下のテストを追加します。 Running "make test" should now print out that all nine tests are okay. "make test" を実行します。 ここで、九つのテストすべてで ok と出力されるはずです。 Notice that in these new test cases, the argument passed to round was a scalar variable. You might be wondering if you can round a constant or literal. To see what happens, temporarily add the following line to Mytest.t: これらの新しいテストケースでは、丸めるために渡される引数が スカラ変数であることに注目してください。 定数やリテラルを丸めたらどうなるだろうか、という疑問を持ったかもしれません。 何が起きるかを確かめるために、以下の行を Mytest.t に一時的に 追加してください。 Run "make test" and notice that Perl dies with a fatal error. Perl won't let you change the value of constants! "make test" を実行すると、Perl は致命的エラーを起こして 終了してしまいます。 Perl は、定数値を変更させないのです! (何が新しいの?) We've made some changes to Makefile.PL. In this case, we've specified an extra library to be linked into the extension's shared library, the math library libm in this case. We'll talk later about how to write XSUBs that can call every routine in a library. Makefile.pl に対する変更をしました。 この場合、エクステンションの共有ライブラリとリンクすべき追加のライブラリ (今回の場合は数学ライブラリ libm)を指定します。 後で、ライブラリにあるすべてのルーチンを呼び出すことのできる XSUB の 書き方について説明します。 The value of the function is not being passed back as the function's return value, but by changing the value of the variable that was passed into the function. You might have guessed that when you saw that the return value of round is of type "void". 関数の値が関数の戻り値として返されるのではなく、関数に渡された 変数の値を変更することで返されます。 round の返り値の型は "void" であると推測したかもしれません。 (入力パラメータと出力パラメータ) You specify the parameters that will be passed into the XSUB on the line(s) after you declare the function's return value and name. Each input parameter line starts with optional whitespace, and may have an optional terminating semicolon. 関数の戻り値と名前を宣言した後の行に XSUB に渡すパラメータを指定できます。 各パラメータ行は(省略可能な)空白で始まり、(省略可能な)終端する セミコロンがあります。 The list of output parameters occurs at the very end of the function, just before after the OUTPUT: directive. The use of RETVAL tells Perl that you wish to send this value back as the return value of the XSUB function. In Example 3, we wanted the "return value" placed in the original variable which we passed in, so we listed it (and not RETVAL) in the OUTPUT: section. 出力パラメータは関数の最後、OUTPUT: 指示子の直後に置きます。 RETVAL を使うことで、Perl に XSUB 関数の戻り値を返したいという意志を 伝えます。 例 3 では、「返り値」を私たちが渡した元の変数に入れてほしいので、 (RETVAL でなく) その変数を OUTPUT: セクションに並べたのです。 (XSUBPP プログラム) The xsubpp program takes the XS code in the .xs file and translates it into C code, placing it in a file whose suffix is .c. The C code created makes heavy use of the C functions within Perl. xsubpp プログラムは .xs ファイルにある XS コードを取り、それを C に 翻訳しその結果を .c という拡張子のファイルに出力します。 変換された C コードは Perl の中にある C の関数を使うように作られます。 (TYPEMAP ファイル) The xsubpp program uses rules to convert from Perl's data types (scalar, array, etc.) to C's data types (int, char, etc.). These rules are stored in the typemap file ($PERLLIB/ExtUtils/typemap). This file is split into three parts. xsubpp プログラムは Perl のデータ型(スカラー、配列、など)から C のデータ型(int, char, など)に変換する規則を使います。 これらのルールは typemap ファイル ($PERLLIB/ExtUtils/typemap)に 格納されます。 このファイルは三つの部分に分けられます。 The first section maps various C data types to a name, which corresponds somewhat with the various Perl types. The second section contains C code which xsubpp uses to handle input parameters. The third section contains C code which xsubpp uses to handle output parameters. 最初のセクションは様々な C のデータ型を、様々な Perl の型にいくらか対応する 名前にマッピングするものです。 二番目のセクションは入力パラメータを扱うために xsubpp が使用する C コードからなります。 三番目のセクションは出力パラメータに対して xsubpp が使用する C コードからなります。 Let's take a look at a portion of the .c file created for our extension. The file name is Mytest.c: さあ、私たちのエクステンションのために作られた .c ファイルの一部を 見てみましょう。 ファイル名は Mytest.c です: 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 */ SvSETMAGIC(ST(0)); } XSRETURN_EMPTY; } ]]> Notice the two lines commented with "XXXXX". If you check the first section of the typemap file, you'll see that doubles are of type T_DOUBLE. In the INPUT section, an argument that is T_DOUBLE is assigned to the variable arg by calling the routine SvNV on something, then casting it to double, then assigned to the variable arg. Similarly, in the OUTPUT section, once arg has its final value, it is passed to the sv_setnv function to be passed back to the calling subroutine. These two functions are explained in perlguts; we'll talk more later about what that "ST(0)" means in the section on the argument stack. "XXXXX" というコメントが付けられた二つの行に注意してください。 typemap ファイルの最初のセクションを確かめれば、doublesT_DOUBLE という型で あることがわかるでしょう。 INPUT セクションでは T_DOUBLE である引数は、SvNv というルーチンを 呼び出すことによって変数が割り当てられ、その後で double に キャストされてから引数である変数に代入されます。 同様に、OUTPUT セクションでは一度引数が最終的な値を持てば、それは 呼び出された関数に返すために関数 sv_setnv に渡されます。 これら二つの関数は perlguts で説明されています。 引数スタックにあるセクションの "ST(0)" の意味は後で説明します。 (出力引数に関する警告) In general, it's not a good idea to write extensions that modify their input parameters, as in Example 3. Instead, you should probably return multiple values in an array and let the caller handle them (we'll do this in a later example). However, in order to better accommodate calling pre-existing C routines, which often do modify their input parameters, this behavior is tolerated. 一般的にいって、例 3 にあるように入力引数を書き換えるような エクステンションを作ることはよくありません。 代わりに、おそらくは複数の値を配列で返して、呼び出し元にそれを扱わせるように するべきです(これは後の例で行います)。 しかしながら、すでにある入力パラメータを書き換えるような C のルーチンの 呼び出しにより良く適応するために、この振る舞いが許されているのです。 次の例では、これをどう行うかを説明します。 (例 4) In this example, we'll now begin to write XSUBs that will interact with pre-defined C libraries. To begin with, we will build a small library of our own, then let h2xs write our .pm and .xs files for us. この例で、すでにある C ライブラリとやりとりするような XSUB の記述を 始めます。 これを始めるために、独自の小さなライブラリを作ります。 それから .pm と .xs のための h2xs を記述します。 Create a new directory called Mytest2 at the same level as the directory Mytest. In the Mytest2 directory, create another directory called mylib, and cd into that directory. ディレクトリ Mytest と同じレベルに、Mytest2 ディレクトリを新たに 作ります。 Mytest2 ディレクトリで、mylib という別のディレクトリを作成し、そこに cd します。 Here we'll create some files that will generate a test library. These will include a C source file and a header file. We'll also create a Makefile.PL in this directory. Then we'll make sure that running make at the Mytest2 level will automatically run this Makefile.PL file and the resulting Makefile. ここで、テスト用のライブラリを生成するための幾つかのファイルを作ります。 こういったファイルには、C ソースファイルとヘッダーファイルが含まれます。 また、このディレクトリで Makefile.PL も作ります。 その後で、Mytest2 のレベルで make を実行することにより自動的に Makefile.PL が実行され、その結果 Makefile が作成されます。 In the mylib directory, create a file mylib.h that looks like this: ディレクトリ mylib で、以下のような内容の mylib.h というファイルを 作成します。 Also create a file mylib.c that looks like this: #include "./mylib.h" ]]> And finally create a file Makefile.PL that looks like this: 'Mytest2::mylib', SKIP => [qw(all static static_lib dynamic dynamic_lib)], clean => {'FILES' => 'libmylib$(LIB_EXT)'}, ); ]]> Make sure you use a tab and not spaces on the lines beginning with "$(AR)" and "$(RANLIB)". Make will not function properly if you use spaces. It has also been reported that the "cr" argument to $(AR) is unnecessary on Win32 systems. "$(AR)" と "$(RANLIB)" で始まる行では空白ではなくタブを使っていることを 確認してください。 また、Win32 システムでは、$(AR) の "cr" 引数は不要であることが 報告されています。 We will now create the main top-level Mytest2 files. Change to the directory above Mytest2 and run the following command: ここでトップレベルの Mytest2 というファイルを作成します。 Mytest2 ディレクトリ に変更して、以下のコマンドを実行します。 This will print out a warning about overwriting Mytest2, but that's okay. Our files are stored in Mytest2/mylib, and will be untouched. これにより、Mytest2 を上書きするという警告が出ますが、気にすることは ありません。 私たちのファイルは Mytest2/mylib にありますが、さわりません。 The normal Makefile.PL that h2xs generates doesn't know about the mylib directory. We need to tell it that there is a subdirectory and that we will be generating a library in it. Let's add the argument MYEXTLIB to the WriteMakefile call so that it looks like this: h2xs が生成した通常の Makefile.PL は mylib ディレクトリに関してなにも 知りません。 私たちはそういったサブディレクトリがあり、そこにライブラリを作成すると いうことを教えなければなりません。 引数 MYEXTLIB を WriteMakefile 呼び出しに追加して、次のような感じに しましょう: '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)', ); ]]> and then at the end add a subroutine (which will override the pre-existing subroutine). Remember to use a tab character to indent the line beginning with "cd"! それから、末尾にサブルーチンを付け加えます(これは既に存在するサブルーチンを 上書きします)。 "cd" で始まる行のインデントにタブ文字を使うことを忘れないでください! Let's also fix the MANIFEST file so that it accurately reflects the contents of our extension. The single line that says "mylib" should be replaced by the following three lines: また、ファイル MANIFEST を私たちのエクステンションの内容を反映するように 修正しましょう。 "mylib" という単一の行を以下の三行で置き換えます。 To keep our namespace nice and unpolluted, edit the .pm file and change the variable @EXPORT to @EXPORT_OK. Finally, in the .xs file, edit the #include line to read: 私たちの名前空間を奇麗で、汚染されていない状態に保つために .pm ファイルを 編集して、@EXPORT を設定している行を @EXPORT_OK に変更します。 最後に .xs ファイルで、#include の行を編集します。 And also add the following function definition to the end of the .xs file: さらに、以下の関数定義を .xs ファイルの末尾に追加します。 Now we also need to create a typemap file because the default Perl doesn't currently support the const char * type. Create a file called typemap in the Mytest2 directory and place the following in it: ここで、デフォルトの Perl は今のところ const char * という型をサポートして いないので、typemap ファイルを作成する必要があります。 Mytest2 ディレクトリに typemap と呼ばれるファイルを作成し、それを以下の 内容にします: Now run perl on the top-level Makefile.PL. Notice that it also created a Makefile in the mylib directory. Run make and watch that it does cd into the mylib directory and run make in there as well. 次にトップレベルの Makefile.PL で perl を実行します。 mylib ディレクトリにある Makefile も作られるということに注意してください。 make を実行し、それにより mylib ディレクトリに cd し、そこで make が 実行されるのを確認します。 Now edit the Mytest2.t script and change the number of tests to "4", and add the following lines to the end of the script: Mytest2.t スクリプトを編集して、テストの数を "4" に変更して、 スクリプトの末尾に以下の行を追加します。 (When dealing with floating-point comparisons, it is best to not check for equality, but rather that the difference between the expected and actual result is below a certain amount (called epsilon) which is 0.01 in this case) (浮動小数点数の比較を行うとき、等しいということをチェックしないことが 最良なのですが、代わりに予想される値と実際の結果の差がある値 (εと呼ばれます)、この場合では 0.01 以内かを調べています) Run "make test" and all should be well. There are some warnings on missing tests for the Mytest2::mylib extension, but you can ignore them. "make test" を実行すれば、すべてがうまくいくはずです。 Mytest2::mylib エクステンションにテストがないという警告が出ますが、 無視して構いません。 (ここで何が起きているの?) Unlike previous examples, we've now run h2xs on a real include file. This has caused some extra goodies to appear in both the .pm and .xs files. 先の例とは違って、今回は実際のインクルードファイルに対して h2xs を 実行しました。 これは .pm ファイルと .xs ファイルの両方に対して幾つかの追加されるものを もたらします。 In the .xs file, there's now a #include directive with the absolute path to the mylib.h header file. We changed this to a relative path so that we could move the extension directory if we wanted to. .xs ファイルには、現在のところ絶対パスで mylib.h ヘッダーファイルを 指定する #include 指示子があります。 これを相対パスに変更することで、もし望むならエクステンションの ディレクトリを移動できるようにします。 There's now some new C code that's been added to the .xs file. The purpose of the constant routine is to make the values that are #define'd in the header file accessible by the Perl script (by calling either TESTVAL or &Mytest2::TESTVAL). There's also some XS code to allow calls to the constant routine. .xs ファイルに追加された C のコードがあります。 constant ルーチンの目的は、ヘッダーファイルで #define されている値を Perl スクリプト(この場合は、&Mytest2::TESTVAL の呼び出しによります)に よってアクセスできるようにすることです。 同様に constant ルーチンを呼び出すための XS コードがあります。 The .pm file originally exported the name TESTVAL in the @EXPORT array. This could lead to name clashes. A good rule of thumb is that if the #define is only going to be used by the C routines themselves, and not by the user, they should be removed from the @EXPORT array. Alternately, if you don't mind using the "fully qualified name" of a variable, you could move most or all of the items from the @EXPORT array into the @EXPORT_OK array. .pm ファイルは元々は配列 @EXPORT にある TESTVAL の名前を エクスポートします。 これは名前を壊す可能性があります。 よい経験則は #define が C のルーチンでのみ使われてユーザーからは 使われないのであれば、それを配列 @EXPORT から取り除いたほうが 良いというものです。 もう一つは、変数の完全修飾名を使うことを使うのが気にならないのであれば、 配列 @EXPORT にある要素のほとんどすべてを配列 @EXPORT_OK に 移すことができます。 If our include file had contained #include directives, these would not have been processed by h2xs. There is no good solution to this right now. インクルードファイルに #include 指示子あるのであれば、それらは h2xs によって処理されません。 現時点ではこれを正しく処理するのに良い解決策はありません。 We've also told Perl about the library that we built in the mylib subdirectory. That required only the addition of the MYEXTLIB variable to the WriteMakefile call and the replacement of the postamble subroutine to cd into the subdirectory and run make. The Makefile.PL for the library is a bit more complicated, but not excessively so. Again we replaced the postamble subroutine to insert our own code. This code simply specified that the library to be created here was a static archive library (as opposed to a dynamically loadable library) and provided the commands to build it. 私たちはすでにサブディレクトリ mylib で作成したライブラリについての 指示を Perl にしています。 ここで要求されているのは、変数 MYEXTLIB を WriteMakefile の呼び出しに 追加し、postamble サブルーチンを目的のディレクトリへ cd して make を 実行するようにすることだけです。 ライブラリのための Makefile.PL は多少複雑にはなりますが、 それほどでもありません。 このコードは単純に作成すべきライブラリが静的ライブラリ(動的ロード可能 ライブラリと反対のもの)であることを指定し、ライブラリを作成するための コマンドを提供します。 (.xs ファイルの解剖) The .xs file of "EXAMPLE 4" contained some new elements. To understand the meaning of these elements, pay attention to the line which reads "EXAMPLE 4" の .xs ファイルにはいくつか新しい要素を含んでいます。 これらの要素の意味を理解するために、以下の行に注目してください Anything before this line is plain C code which describes which headers to include, and defines some convenience functions. No translations are performed on this part, apart from having embedded POD documentation skipped over (see perlpod) it goes into the generated output C file as is. この行以前の全てはインクルードするヘッダおよび便利な関数を定義した プレーンな C コードです。 この部分では、組み込みの POD 文書が読み飛ばされる(perlpod を 参照してください)ことを除いては何の変換は行われず、そのまま出力 C ファイルが 出力されます。 Anything after this line is the description of XSUB functions. These descriptions are translated by xsubpp into C code which implements these functions using Perl calling conventions, and which makes these functions visible from Perl interpreter. この行以降の全ては XSUB 関数の記述です。 これらの記述は、関数を Perl 呼び出し規則を使って実装し、関数が Perl インタプリタから見えるように、xsubpp が C コードに変換します。 Pay a special attention to the function constant. This name appears twice in the generated .xs file: once in the first part, as a static C function, then another time in the second part, when an XSUB interface to this static C function is defined. constant 関数には特別な注意を払ってください。 この名前は生成された .xs ファイルに 2 回現れます: 1 回目は最初の部分に static C 関数として、2 回目は 2 番目の部分に、 この static C 関数への XSUB インターフェースが定義されたときです。 This is quite typical for .xs files: usually the .xs file provides an interface to an existing C function. Then this C function is defined somewhere (either in an external library, or in the first part of .xs file), and a Perl interface to this function (i.e. "Perl glue") is described in the second part of .xs file. The situation in "EXAMPLE 1", "EXAMPLE 2", and "EXAMPLE 3", when all the work is done inside the "Perl glue", is somewhat of an exception rather than the rule. これは .xs ファイルではかなり典型的です: 普通 .xs ファイルは既にある C 関数へのインターフェースを提供します。 それからこの C 関数はどこか(外部ライブラリか、.xs ファイルの最初の部分)で 定義され、この関数への Perl インターフェース(つまり「Perl の糊」)が .xs ファイルの 2 番目の部分に記述されます。 "EXAMPLE 1", "EXAMPLE 2", "EXAMPLE 3" の状況、 つまり全ての動作が「Perl の糊」の内側で行われるときは、 規則ではなく何らかの例外があります。 (太った部分を XSUB の外に出す) In "EXAMPLE 4" the second part of .xs file contained the following description of an XSUB: "EXAMPLE 4" で、.xs ファイルの 2 番目の部分には、以下の XSUB の 記述を含んでいます: Note that in contrast with "EXAMPLE 1", "EXAMPLE 2" and "EXAMPLE 3", this description does not contain the actual code for what is done is done during a call to Perl function foo(). To understand what is going on here, one can add a CODE section to this XSUB: "EXAMPLE 1", "EXAMPLE 2", "EXAMPLE 3" と比較して、この記述は Perl 関数 foo() の呼び出しに何が起きているのかの実際の コード は 含んでいません。 ここで何が起きているのかを理解するために、この XSUB に CODE セクションを 追加できます: However, these two XSUBs provide almost identical generated C code: xsubpp compiler is smart enough to figure out the CODE: section from the first two lines of the description of XSUB. What about OUTPUT: section? In fact, that is absolutely the same! The OUTPUT: section can be removed as well, as far as CODE: section or PPCODE: section is not specified: xsubpp can see that it needs to generate a function call section, and will autogenerate the OUTPUT section too. Thus one can shortcut the XSUB to become: しかし、これら 2 つの XSUB はほとんど同じ C コードを生成します: xsubpp コンパイラは、XSUB の記述の最初の 2 行から CODE: セクションを見つけ出すことができるぐらい賢いです。 OUTPUT: セクションについてはどうでしょう? 実際、これは全く同じです! CODE: セクションや PPCODE: セクションが指定されない限り、 OUTPUT: セクションも同様に削除でき、同様に OUTPUT セクションを 自動生成します。 従って、XSUB を以下のように省略できます: Can we do the same with an XSUB 同じことを "EXAMPLE 2" の XSUB: of "EXAMPLE 2"? To do this, one needs to define a C function int is_even(int input). As we saw in Anatomy of .xs file, a proper place for this definition is in the first part of .xs file. In fact a C function で出来るでしょうか? これをするためには、C 関数 int is_even(int input) を定義する 必要があります。 Anatomy of .xs file で見たように、この定義に適切な場所は .xs ファイルの 最初の部分です。 実際、C 関数 is probably overkill for this. Something as simple as a #define will do too: というのはおそらくここではやりすぎです。 #define と同じぐらい単純なこともできます: After having this in the first part of .xs file, the "Perl glue" part becomes as simple as .xs ファイルの最初の部分にこれを入れた後、 「Perl の糊」の部分は以下のように単純です This technique of separation of the glue part from the workhorse part has obvious tradeoffs: if you want to change a Perl interface, you need to change two places in your code. However, it removes a lot of clutter, and makes the workhorse part independent from idiosyncrasies of Perl calling convention. (In fact, there is nothing Perl-specific in the above description, a different version of xsubpp might have translated this to TCL glue or Python glue as well.) 実際の動作の部分から糊の部分を分離する技術は明らかなトレードオフです: もし Perl インターフェースをしようとすると、コードの 2 箇所を変更する 必要があります。 しかし、これは多くの乱雑なものを取り除き、実際の動作の部分を Perl 呼び出し 規則の特異性から独立させます。 (実際のところ、上述の記述には Perl 固有のものはなく、異なるバージョンの xsubpp はこれを TCL の糊や Python の糊にも変換できるかもしれません。) (さらに XSUB 引数について) With the completion of Example 4, we now have an easy way to simulate some real-life libraries whose interfaces may not be the cleanest in the world. We shall now continue with a discussion of the arguments passed to the xsubpp compiler. 例 4 を補完するために、私たちは世界で最もクリーンというわけではないであろう 現実のライブラリのシミュレートをするための簡単な方法があります。 私たちは xsubpp コンパイラに渡す引数についての議論を 続けなければなりません。 When you specify arguments to routines in the .xs file, you are really passing three pieces of information for each argument listed. The first piece is the order of that argument relative to the others (first, second, etc). The second is the type of argument, and consists of the type declaration of the argument (e.g., int, char*, etc). The third piece is the calling convention for the argument in the call to the library function. .xs ファイルでルーチンへの引数を指定したとき、あなたはそれぞれの 引数がリストアップされた三つの情報ブロックを渡しているでしょう。 最初のブロックは、引数の相対的な順序(一番目、二番目、…)です。 二番目のブロックは引数の型で、引数の型宣言からなります。 三番目のブロックは、引数がライブラリ関数を呼び出すときに使われる引数の 呼び出し規約です。 While Perl passes arguments to functions by reference, C passes arguments by value; to implement a C function which modifies data of one of the "arguments", the actual argument of this C function would be a pointer to the data. Thus two C functions with declarations Perl は関数に引数を参照渡ししますが、C は引数を値渡しします; 「引数」の 一つのデータを修正する C 関数を実装するには、この C 関数の実際の引数は そのデータへのポインタになります。 従って、2 つの C 関数宣言: 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. は完全に異なった意味を持ちます: 前者は s で示された char の配列を検査します; 後者は直ちに cp を デリファレンスして、*cp だけを操作します(返り値は成功を示すものとして 使われます)。 Perl からはこれらの関数は全く異なった方法で使います。 One conveys this info to xsubpp by replacing * before the argument by &. & means that the argument should be passed to a library function by its address. The above two function may be XSUB-ified as & による引数の前に * を置き換えることで、この情報を xsubpp に 伝えられます。 & は、引数がアドレスでライブラリ関数に渡されることを意味します。 上記の 2 つの関数は以下のように XSUB 化できます For example, consider: 例として、次のものを考えます: The first Perl argument to this function would be treated as a char and assigned to the variable a, and its address would be passed into the function foo. The second Perl argument would be treated as a string pointer and assigned to the variable b. The value of b would be passed into the function foo. The actual call to the function foo that xsubpp generates would look like this: 最初の Perl の引数はこの関数では char として扱われ、変数 a に代入され、 そしてそのアドレスは関数 foo に渡されます。 二番目の Perl の引数は文字列へのポインターとして扱われ、変数 b へ 代入されます。 b の 値 も関数 foo へ渡されます。 xsubpp が生成する関数 foo への実際の呼び出しは次のようになります。 xsubpp will parse the following function argument lists identically: xsubpp は以下の関数引数リストを同じものと解析します: However, to help ease understanding, it is suggested that you place a "&" next to the variable name and away from the variable type), and place a "*" near the variable type, but away from the variable name (as in the call to foo above). By doing so, it is easy to understand exactly what will be passed to the C function -- it will be whatever is in the "last column". しかしながらわかりやすくするために、 "&" に変数名を続けて変数の型からは 離しておくことと、 "*" を型名に近づけるが変数名からは離す(前述した foo の 呼び出しのように)ということをお勧めします。 これを行うことで、実際に C の関数に渡されるがなんなのかを簡単に 理解できます -- これは "last column" にあるものでしょう。 You should take great pains to try to pass the function the type of variable it wants, when possible. It will save you a lot of trouble in the long run. 可能ならば、関数に(自分が望む)変数の型を渡すことに挑戦して苦労したほうが 良いでしょう。 長い目で見ればそれによって多くのトラブルを避けることになります。 (引数スタック) If we look at any of the C code generated by any of the examples except example 1, you will notice a number of references to ST(n), where n is usually 0. "ST" is actually a macro that points to the n'th argument on the argument stack. ST(0) is thus the first argument on the stack and therefore the first argument passed to the XSUB, ST(1) is the second argument, and so on. 例 1 以外の このチュートリアルで作成した C コードを見たのならば、 たくさんのST(n) (n は通常は 0)に対する参照に気がついたことでしょう。 "ST" は実際には引数スタック上の n 番目の引数を指し示すマクロです。 従って ST(0) はスタック上の最初の引数なので、XSUB に渡される最初の 引数であり、ST(1) は二番目の引数となります。 When you list the arguments to the XSUB in the .xs file, that tells xsubpp which argument corresponds to which of the argument stack (i.e., the first one listed is the first argument, and so on). You invite disaster if you do not list them in the same order as the function expects them. .xs ファイル中で XSUB に対する引数をリストアップしたとき、それは引数 スタックの対応する引数を xsubpp に指定するということです(例えば、 リストの最初にあれば第一引数、二番目なら第二引数ということ)。 関数が期待するのと同じ順番でリストアップしなければ、思いがけない 災害を招くことになります。 The actual values on the argument stack are pointers to the values passed in. 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: 引数スタックの実際の値は渡された値へのポインタです。 引数が OUTPUT の値として挙げられている場合、スタック上の対応する値 (例えば、最初の引数なら ST(0)) が変更されます。 例 3 で生成された C コードを見ることでこれを検証できます。 round() XSUB ルーチンのコードは以下のように見える行を含んでいます: The arg variable is initially set by taking the value from ST(0), then is stored back into ST(0) at the end of the routine. 引数変数は、まず ST(0) の値から取られるものにセットされ、その後ルーチンの 最後に ST(0) に書き戻されます。 XSUBs are also allowed to return lists, not just scalars. This must be done by manipulating stack values ST(0), ST(1), etc, in a subtly different way. See perlxs for details. 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 "Getting the fat out of XSUBs" for a similar tradeoff of a complete separation of "Perl glue" and "workhorse" parts of an XSUB. XSUB はまた、Perl 関数引数から C 関数引数への自動変換を回避することも できます。 詳しくは perlxs を参照してください。 自動変換が行われる場合でも ST(i) を検査することでの手動変換を好む 人々もいて、これにより XSUB 呼び出しのロジックがよりきれいになると 主張しています。 XSUB における「Perl の糊」と「実働部隊」の完全な分離に関する似たような トレードオフに関して、"Getting the fat out of XSUBs" と 比較してください。 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 "Getting the fat out of XSUBs". This approach has the additional benefit of protecting the XSUB writer from future changes to the Perl API. 専門家はこれらの慣用法について主張する一方、Perl の内部に関する初心者は Perl 内部に固有のものを可能な限り小さくする方法を好みます; これはつまり "Getting the fat out of XSUBs" のような、自動変換と自動呼び出し 生成です。 この手法には、XSUB 作者を Perl API の将来の変更から守るという追加の利点も あります。 (エクステンションを拡張する) Sometimes you might want to provide some extra methods or subroutines to assist in making the interface between Perl and your extension simpler or easier to understand. These routines should live in the .pm file. Whether they are automatically loaded when the extension itself is loaded or only loaded when called depends on where in the .pm file the subroutine definition is placed. You can also consult AutoLoader for an alternate way to store and load your extra subroutines. Perlとあなたのエクステンションとの間のインターフェースをより簡単に、 より理解しやすくするのを助けるためにメソッドやサブルーチンを 作りたいと思う事があるかもしれません。 こういったルーチンは .pm ファイルに置くのが良いです。 これがエクステンション自身がロードされたときロードされるにしろ、 サブルーチン定義が置かれている. pm ファイルに依存する呼び出しのときのみ ロードするにしろ、自動的にロードが行われます。 追加のサブルーチンを保管して読み込むもう一つの方法としては AutoLoader を参考にすることもできます。 (エクステンションを文書化する) There is absolutely no excuse for not documenting your extension. Documentation belongs in the .pm file. This file will be fed to pod2man, and the embedded documentation will be converted to the manpage format, then placed in the blib directory. It will be copied to Perl's manpage directory when the extension is installed. あなたのエクステンションに関するドキュメントがないということについて、 あなたは何の言い訳もできません。 ドキュメントは .pm ファイルに属します。 このファイルは pod2man に送り込まれ、埋め込まれたドキュメントが man ページフォーマットに変換され、それから blib ディレクトリに置かれます。 このドキュメントは、エクステンションがインストールされるときに Perl の man ページディレクトリにもコピーされます。 You may intersperse documentation and Perl code within the .pm file. In fact, if you want to use method autoloading, you must do this, as the comment inside the .pm file explains. あなたは .pm ファイルにあるドキュメントと Perl コードをまき散らすことが あるかもしれません。 事実、あなたがメソッドを autoload しようとするならば、.pm ファイルの中に あるコメントで説明されているようにこれを行わねばなりません。 See perlpod for more information about the pod format. pod フォーマットについてのより詳しい情報は perlpod を参照してください。 (エクステンションをインストールする) Once your extension is complete and passes all its tests, installing it is quite simple: you simply run "make install". You will either need to have write permission into the directories where Perl is installed, or ask your system administrator to run the make for you. あなたの作ったエクステンションが完成し、かつすべてのテストに合格すれば、 それを実に単純なやりかたでインストールします。 ただ単に "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. 別の方法として、"make install" の後ろに (あるいはおかしな make を使っている 場合は "make" と "install" の間に)"PREFIX=/destination/directory" と 書くことで、エクステンションのファイルを置く正確なディレクトリを 指定できます。 これは、最終的に複数のシステムに配布されるエクステンションをビルドしている 場合にとても有用です。 その後単に出力先のディレクトリのファイルをアーカイブして、目的のシステムに 配布します。 (例 5) In this example, we'll do some more work with the argument stack. The previous examples have all returned only a single value. We'll now create an extension that returns an array. この例では、引数スタックにさらなる作業をします。 前の例では全て、単一の値を返すものだけです。 ここでは、配列を返すエクステンションを作ります。 This extension is very Unix-oriented (struct statfs and the statfs system call). If you are not running on a Unix system, you can substitute for statfs any other function that returns multiple values, you can hard-code values to be returned to the caller (although this will be a bit harder to test the error case), or you can simply not do this example. If you change the XSUB, be sure to fix the test cases to match the changes. このエクステンションはとても Unix 指向です(struct statfs と statfs システムコール)。 もし Unix システム以外で実行するなら、statfs を複数の値を返す別の関数に 置き換えるか、呼び出し元に返す値をハードコーディングする(しかしこれは エラーの場合をテストするのが少し難しくなります)か、あるいは単に この例を実行しないということもできます。 もし XSUB を変更したなら、テストケースも変更にあわせて確実に 修正してください。 Return to the Mytest directory and add the following code to the end of Mytest.xs: Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します: You'll also need to add the following code to the top of the .xs file, just after the include of "XSUB.h": また、.xs ファイルの先頭、"XSUB.h" をインクルードした直後に、以下のコードを 追加する必要があります: ]]> Also add the following code segment to Mytest.t while incrementing the "9" tests to "11": また、以下のコードを Mytest.t に追加する一方、"9" のテストを "11" に 増やします: (この例での新しいこと) This example added quite a few new concepts. We'll take them one at a time. この例はいくつかの全く新しい概念を追加します。 一回に一つずつやります。 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.) INIT: 指示子は、引数スタックがデコードされた直後に置かれるコードを含みます。 C では関数内の任の市での変数宣言を許していないので、 これは普通 XSUB によって必要なローカル変数を宣言するための最善の方法です。 (代替案としては、PPCODE: セクション全体を中かっこで囲って、それらの 宣言を先頭に置くこともできます。) 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. このルーチンはまた、statfs の呼び出しが成功か失敗かに依存して、異なった 数の値を返します。 エラーの場合は、エラー番号が単一の要素の配列として返されます。 呼び出しが成功した場合は、9 要素の配列が返されます。 この関数には引数が 1 つだけ渡されるので、返す 9 つの値を保持するために スタックに空きを作る必要があります。 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. これを、CODE: 指示子ではなく PPCODE: 指示子を使うことで行います。 これは、引数スタックに置かれる返り値の管理を自分自身で行うことを xsubpp に知らせます。 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.) 呼び出し元に返す値を置くための場所がスタック上にほしい時、 "XPUSH" で始まる一連のマクロを使います。 これには、スタック上に整数、符号なし整数、double、文字列、Perl スカラを 置くための 5 種類があります。 この例では、スタック上に Perl スカラをおきます。 (実際のところ、これは複数の値を返すときに使える唯一のマクロです。) 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. XPUSH* マクロは、返り値スタックがオーバーランすることを防ぐために、自動的に 返り値スタックを拡張します。 呼び出しプログラムから見えてほしい順番にスタックに値をプッシュします。 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. XSUB の返り値スタックにプッシュされた値は実際には揮発性の SV です。 これは揮発性なので、一旦呼び出しプログラムによって値がコピーされれば、 返り値を保持している SV は開放できます。 もしこれらが揮発性でないなら、XSUB ルーチンから返った後も存在し続けますが、 アクセスできなくなります。 これはメモリリークです。 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: もしコードサイズではなく性能に興味があるのなら、成功時には XPUSHs ではなく PUSHs を使って、返り値をプッシュする前に予めスタックを 拡張しておきます: 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). トレードオフは、予め返り値の数を計算しておく必要があることです (しかしスタックを余分に拡張しても、典型的にはメモリ消費以外にはなんの問題も ありません)。 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. 同様に、失敗時にはスタックを 拡張せずに PUSHs を使えます: Perl 関数のリファレンスはスタックで XSUB に渡されるので、 スタックは 常に 一つの返り値を返すには十分な大きさがあります。 (例 6) 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. この例では、入力パラメータとして配列へのリファレンスを受け付け、ハッシュの 配列へのリファレンスを返します。 ここでは、複雑な Perl データ型を XSUB から操作する方法を示します。 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. このエクステンションはやや不自然です。 これは以前の例のコードを基礎にしています。 これは statfs 関数を複数呼び出し、入力としてファイル名の配列への リファレンスを受け付けて、それぞれのファイルシステムのデータを含む ハッシュの配列へのリファレンスを返します。 Return to the Mytest directory and add the following code to the end of Mytest.xs: Mytest ディレクトリに戻って、Mytest.xs の末尾に以下のコードを追加します: And add the following code to Mytest.t, while incrementing the "11" tests to "13": また、以下のコードを Mytest.t に追加する一方、"11" のテストを "13" に増やします: [0]) ); ok( ! ref $results->[1] ); ]]> (この例での新しいこと) There are a number of new concepts introduced here, described below: ここでは後述するいくつかの新しい概念があります: 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. この関数は typemap を使いません。 代わりに、一つの SV* (スカラ) 引数を受け入れ、一つの SV* 値を返すように 定義して、これらのスカラをコード内で引き受けます。 一つの値だけを返すので、 PPCODE: 指示子は不要です - 代わりに、 CODE: と OUTPUT: の指示子を使います。 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. リファレンスを扱うとき、これを注意して扱うことが重要です。 INIT: ブロックはまず、SvROK が真を返すことろチェックします; これをパスが正当なリファレンスであることを示しています。 それから、SvRV でパスをデリファレンスして、SvTYPE でその型を 調べることで、パスでリファレンスされているオブジェクトが配列であることを 検証します。 追加のテストとして、(配列が空の場合に -1 を返す)av_len 関数を使って、 パスでリファレンスされた配列が空でないことをチェックします。 XSRETURN_UNDEF マクロは、これら 3 つの条件のどれかが成立しないときに XSUB を中断して未定義値を返すために使われます。 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. この XSUB でいくつかの配列を操作します。 配列は内部的に AV* ポインタで表現されていることに注意してください。 配列操作のための関数とマクロは Perl の関数と似ています: av_len は、 $#array と同様、AV* の最大の添え字を返します; av_fetch は添え字を 取って、配列から 1 つのスカラ値を取り出します; av_push はスカラ値を 配列の最後にスカラ値をプッシュし、もし必要なら自動的に配列を拡張します。 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. 特に、入力配列から一度に 1 つだけパス名を読み込み、結果を出力配列に 同じ順序で保管します。 もし statfs が失敗すると、返り値配列にプッシュされる要素は失敗時の errno です。 しかし、statfs が成功すると、返り値配列にプッシュされる値は statfs 構造体の 情報を含むハッシュへのリファレンスです。 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: 返り値スタックに関して、いくつの要素が返されるかは分かっているので、 データをプッシュする前に返り値配列を予め拡張しておくことが可能です (そして少し性能がよくなります): 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. この関数では、hv_store を使ってキーに対して新しいスカラを保管するという、 1 つのハッシュ操作のみを行います。 ハッシュは HV* ポインタで表現されます。 配列と同様、XSUB からハッシュを操作する関数は、Perl から利用可能な機能と 鏡写しです。 詳しくは perlguts と perlapi を参照してください。 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). リファレンスを作るには、 newRV 関数を使います。 この場合(およびその他多くの場合)、AV* か HV* を SV* 型に キャストできることに注意してください。 これにより、同じ関数で配列、ハッシュ、スカラのリファレンスを得ることが できます。 反対に、 SvRV 関数は常に SV* を返すので、もしこれが(SvTYPE を チェックして)スカラ以外の場合、適切な型にキャストする必要があります。 At this point, xsubpp is doing very little work - the differences between Mytest.xs and Mytest.c are minimal. この時点で、xsubpp はほとんど何もしていません - Mytest.xs と Mytest.c との 差は最小限です。 (例 7 (近日公開)) XPUSH args AND set RETVAL AND assign return value to array 引数の XPUSH と RETVAL のセットと返り値の配列への代入 (例 8 (近日公開)) Setting $! $! をセットする (例 9 オープンしたファイルを XS に渡す) You would think passing files to an XS is difficult, with all the typeglobs and stuff. Well, it isn't. 型グロブなどで、XS にファイルを渡すのは難しいと考えるかもしれません。 えっと、そうではありません。 Suppose that for some strange reason we need a wrapper around the standard C library function fputs(). This is all we need: 標準 C ライブラリ関数 fputs() のラッパーが必要、という不思議な 理由があるとしましょう。 必要なものは以下のものだけです: ]]> The real work is done in the standard typemap. 実際の作業は標準の typemap で行われます。 But you loose all the fine stuff done by the perlio layers. This calls the stdio function fputs(), which knows nothing about them. しかし、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. 標準 typemap は 3 種類の PerlIO * を提供します: InputStream (T_IN), InOutStream (T_INOUT), OutputStream (T_OUT) です。 生の PerlIO * は T_INOUT として扱われます。 コード中でこれが問題になる場合(なぜそうなり得るかは以下を 参照してください)、特定の名前の一つを #define や typedef して、 それを XS ファイルで引数や結果の型として使ってください。 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. perl 5.7 以前の標準 typemap には PerlIO * は含まれていませんが、 3 種類のストリームの種類があります。 PerlIO * を直接使うと、独自の typemap を提供しない限り、 後方互換ではありません。 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... perl から 来るストリームについて、主な違いは OutputStream が 出力 PerlIO * を得るということです - これはソケットの場合に違いとなります。 私たちの例と同様に… 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. perl に 渡されるストリームについて、新しいファイルハンドル (つまり、新しいグロブへのリファレンス)が作成され、提供された PerlIO * と 結び付けられます。 もし PerlIO * の読み込み/書き込み状態が正しくない場合、ファイルハンドルが 使われたときにエラーや警告を受けることになります。 従って、もし PerlIO * を "w" としてオープンしたなら実際には OutputStream であるべきですし、"r" としてオープンしたなら InputStream であるべきです。 Now, suppose you want to use perlio layers in your XS. We'll use the perlio PerlIO_puts() function as an example. ここで、XS で perlio 層を使いたいとしましょう。 例のように、perlio の PerlIO_puts() 関数を使います。 In the C part of the XS file (above the first MODULE line) you have XS ファイルの C の部分 (最初の MODULE 行の上) に以下のようにします And this is the XS code: そして XS コードはこれです: We have to use a CODE section because PerlIO_puts() has the arguments reversed compared to fputs(), and we want to keep the arguments the same. PerlIO_puts() は fputs() と比較する予約された引数を持っていて、 引数は同じままにしたいので、CODE セクションを使う必要があります。 Wanting to explore this thoroughly, we want to use the stdio fputs() on a PerlIO *. This means we have to ask the perlio system for a stdio FILE *: これを完全に探索するために、PerlIO * に stdio の fputs() を使いたいです。 これは、perlio システムに stdio の FILE * を問い合わせる必要があります: 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(). 注意: PerlIO_findFILE() は stdio 層の層を検索します。 もしそれが見つからなければ、新しい stdio FILE を生成するために PerlIO_exportFILE() を呼び出します。 新しい FILE が必要な場合にのみ PerlIO_exportFILE() を 呼び出すようにしてください。 これは呼び出し毎に新しいものを生成して新しい stdio 層にプッシュします。 従って、同じファイルに対して繰り返し呼び出さないでください。 PerlIO()_findFILE は、一度 PerlIO_exportFILE() で生成された stdio 層を 取り出します。 This applies to the perlio system only. For versions before 5.7, PerlIO_exportFILE() is equivalent to PerlIO_findFILE(). これは perlio システムにのみ適用されます。 5.7 以前のバージョンでは、PerlIO_exportFILE() は PerlIO_findFILE() と 等価です。 (これらの例のトラブルシューティング) As mentioned at the top of this document, if you are having problems with these example extensions, you might see if any of these help you. この文書の最初に触れたように、もしこれらの例のエクステンションで問題が あった場合、以下が参考になるかもしれません。 In versions of 5.002 prior to the gamma version, the test script in Example 1 will not function properly. You need to change the "use lib" line to read: γバージョン以前のバージョン 5.002 では、EXAMPLE 1 にあるテスト スクリプトは正しく動作しません。 "use lib" という行を以下の様に変更する必要があります。 In versions of 5.002 prior to version 5.002b1h, the test.pl file was not automatically created by h2xs. This means that you cannot say "make test" to run the test script. You will need to add the following line before the "use extension" statement: バージョン 5.002b1h 以前のバージョン 5.002 では、test.pl というファイルが h2xs によって自動生成されません。 これはテストスクリプトを実行するために、"make test" とすることが できないということです。 "use extension" という文の前に以下の行を追加する必要があります: In versions 5.000 and 5.001, instead of using the above line, you will need to use the following line: バージョン 5.000 および 5.001 では、上で示した行ではなく、以下に示した行を 使う必要があるでしょう。 This document assumes that the executable named "perl" is Perl version 5. Some systems may have installed Perl version 5 as "perl5". このドキュメントでは、"perl" という名前の実行ファイルが Perl のバージョン 5 であることを仮定しています。 Perl のバージョン 5 は "perl5" としてインストールされているシステムも あるかもしれません。 For more information, consult perlguts, perlapi, perlxs, perlmod, and perlpod. より詳しい情報は、perlguts, perlapi, perlxs, perlmod, perlpod を参照してください。 Jeff Okamoto <okamoto@corp.hp.com> Jeff Okamoto <okamoto@corp.hp.com> Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig, and Tim Bunce. Dean Roehrich, Ilya Zakharevich, Andreas Koenig, Tim Bunce によるレビューと 助力を受けました。 PerlIO material contributed by Lupe Christoph, with some clarification by Nick Ing-Simmons. PerlIO の素材は Lupe Christoph によって提供され、Nick Ing-Simmons によって 明確化されたものです。 Changes for h2xs as of Perl 5.8.x by Renee Baecker Perl 5.8.x での h2xs に関しては Renee Baecker が変更しました。 2007/10/11 Created: KIMURA Koichi Updated: Kentaro Shirakata <argrath@ub32.org> (5.8.8-)