Inline-0.43 > Inline

名前

Inline - 他のプログラミング言語でPerlのサブルーチンを作成する。

概要

    use Inline C;
    
    print "9 + 16 = ", add(9, 16), "\n";
    print "9 - 16 = ", subtract(9, 16), "\n";
 
    __END__
    __C__
    int add(int x, int y) {
      return x + y;
    }
 
    int subtract(int x, int y) {
      return x - y;
    }

説明

Inlineモジュールは他のプログラミング言語からのソースコードをPerlスクリプトやモジュールに直接"Inline"(=一緒)に入れることを可能にします。コードは自動的に必要に合わせてコンパイルされ、そしてPerlからすぐにアクセスするためにロードされます。 InlineはXSやSWIGといった手段を使って、独自のつなぎのコードを書き、コンパイルするといった難しいことをしないで済むようにしてくれます。単にそれが欲しいところでコードをタイプし、いつものようにPerlを実行してください。難しいことは全て、あなたの代わりに扱われます。あなたのコードのコンパイルとインストールはすべて透過的に行われます;あなたが分かることといえば、最初に実行したときにコンパイルによって遅くなることだけです。

Inlineのコードは、あなたが最初に実行するとき(あるいはそれが変更されたとき)にだけコンパイルされます。そのためパフォーマンス上の問題は1度だけしか発生しません。(CPAN上のように)配布されるモジュールにInlineに入っているコードは、モジュールがインストールされるときコンパイルされるでしょう。そのためエンド・ユーザはコンパイル時間に気がつくことはないでしょう。

何よりよいことは、これがUnixとMicrosoft Windowsの両方で同じように動くことです。サポート情報についてはInline-Supportをご覧ください。

なぜInlineなの?

"なぜPerlで他の言語を使わなければいけないのですか?"あるいは"そうするために、なぜInlineを使わなきゃいけないのですか?"ということを知りたいですか?その両方に答えてみようと思います。

なぜPerlで他の言語を使わなければいけないのですか?

最も明確な理由はパフォーマンスです。インタープリトされる言語としては、Perlは非常に速いものです。多くの人々が"PerlにできることをCは速くできる"というでしょう。(彼らは開発する時間については言及することはありません :-)、いずれにしても、他の言語を使うことにより、その言語であなたのプログラムを完全に書くことなく、あなたのPerlコードでのボトルネックを解消することができるかもしれません。これは、クリティカルではないコードのすべてにPerlを使うので、開発時間全体を低く抑えます。

もう1つの理由は、その言語が使う既存のAPIからの機能にアクセスするためです。このコードは場合によっては、バイナリ形式でしか利用することができないかもしれません。しかしネイティブな言語で小さなサブルーチンを作ることにより、既存ライブラリとあなたのPerlとの"つなげる(=glue)"ことができます。CPANの利用者であれば、あなたはコードの再利用がよいことが分かるでしょう。それじゃあなぜFortranのライブラリを放っておくんですか?

InlineをCと一緒に使うならば、Perl自身の内部の全てにアクセスすることができます。これは非常に強力な力と危険性の両方への門を開くことになります。

たぶん一番の理由は"そうしたいから!"でしょう。いろんなことがあるから世界は面白いんです。TMTOWTDI!

そうするために、なぜInlineを使わなきゃいけないのですか?

既に2つの有名な、CでPerlを格納するためのファシリティが存在します。XSとSWIGです。両方とも、少なくともPerlに関しては、その特性は似通っています。そして両方ともInlineに比べると学習するのは非常に困難です。

XS環境を設定し利用することの学習曲線は非常に鈍いものになります。あなたは以下のドキュメントに精通する必要があります:

 * perlxs
 * perlxstut
 * perlapi
 * perlguts
 * perlmod
 * h2xs
 * xsubpp
 * ExtUtils::MakeMaker

Inlineではすぐにはじめて、実行することができます。実際にある問題に拡張することができる短いけれども完全なプログラムがたくさん入った、C Cookbookがあります。背後で行われる複雑な構築プロセスについて学習する必要はありません。あなた自身でコードをコンパイルする必要すらありません。Cのコードを書くこと以外は、Inlineがすべての面倒を見てくれます。

Perlプログラマはコンパイルのような馬鹿げたことで悩まされることはありません。"Tweak, Run, Tweak, Run"(=ちょっとイジって実行、ちょっとイジって実行)が私たちのやり方です。面白くない仕事は全て、Inlineがあなたに代わってやってくれます。

Inlineのもう1つの利点は、スクリプトで直接使うことが出来ることです。Perlのワンライナーでそれをつかうこともできます。XSやSWIGでは、常に完全に別のモジュールを設定します。1つあるいは2つの関数しか持っていなくても。Inlineは簡単なことは簡単に、難しいことも可能にします。ちょうどPerlのように。

最後に、Inlineは数多くのプログラミング言語をサポートします(単にCやC++だけでなく)。これを書いている時点で、InlineはC, C++, Java, Python, Tcl, アセンブラ, そして CPRをサポートしています。そしてさらに多くの追加の計画があります。詳しくはInline-Support をご覧ください。

Inline.pm モジュールの使い方

Inlineは、あなたが使ってきたほとんどPerlモジュールとはちょっと違います。それはあなたの名前空間に何も関数をインポートしませんし、オブジェクト指向のメソッドも持っていません。(2つの小さな例外を除けば)そのインターフェースは全ては'use Inline ...'コマンドを通して指定されます。

このセクションはuse Inlineの全ての異なる方法を説明します。今すぐInlineでCを使い始めたければ、Inline::C-Cookbookをご覧ください。

基本

Inlineを使う最も基本的な形式は以下の通りです:

    use Inline X => "X source code";

'X'のところはサポートされているInlineプログラミング言語の1つになります。2番目のパラメータはPerlに結び付けたいソースコードを示します。ソースコードは以下の書き方のいずれでも指定することができます:

DATA
    use Inline Java => 'DATA';
    
    # Perlのコードはここ...
    
    __DATA__
    __Java__
    /* Javaのコードはここ ... */

Inline Perlプログラムで、最も簡単で最も見た目にはっきりとソースコードを指定する方法は、特別なDATAキーワードを使うことです。これはDATAファイルハンドルの入力ストリームで特別な印を探すようにInlineに伝えます。この例では__Java__が特別な印です。それは2つのダブルスコアで囲まれたプログラミング言語になります。

あなたが何もしなければ、DATAという仮のファイルは、あなたのプログラムの__END__ あるいは __DATA__ セクションの後のすべてのテキストになります。もしmainの外で動くのであれば、__DATA__マーカーを使うことが一番です。そうでなければInlineはあなたのコードを見つけることができません。

この仕組みではPerlのコードは先頭にあるままです。そして醜いJavaのコードは全て下に入ります。これは見た目にはっきりし、維持しやすいコードにします。すばらしい副産物として、Perlの文字列でのように文字を何もエスケープする必要がありません。ソースコードはその文字通りになります。このため、私はこの方法が一番好きです。

この形式の唯一の問題点は、Perlが実行時までDATAファイルハンドルを読むことが出来ないので、実行時まであなたの関数をバインドすることが明らかに出来ないことです。この正味の影響は、Perlがコンパイルする間それらが存在することが分からないので、(それらをあらかじめ宣言することなく)Inlineの関数をそのままの名前で使うことが出来ないことです。

FILE, BELOW
    use Inline::Files;
    use Inline Java => 'FILE';
    
    # Perlのコードはここ...
    
    __JAVA__
    /* Javaのコードはここ... */

これはソースコードを指定する最も新しい方法です。これはDamian Conwayによって作成されたPerlモジュールInline::Filesを使用します。基本的な形式と意味はDATAキーワードと同じです。しかし書き方と意味にいくつかの工夫が入っています。

まず最初に、あなたはそれらのファイルを必要とする'use Inline'コードの前に、'use Inline::Files'とする必要があります。特別な'DATA'キーワードは'FILE'あるいは'BELOW'に置き換えることができます。これによって以下の駄洒落のような慣用句が可能になります:

    use Inline C => 'BELOW';

現在は__DATA__タグを省略することが出来ます。Inline::Filesは、Perlがそれをコンパイルする前に、あなたのプログラムからこれらのセクションを削除するソースフィルタです。そして、それらはInlineが使用するために利用できます。そしてこの全てがコンパイル時に行われるので、'DATA'キーワードでの警告について心配する必要がありません。 このモジュールはいくつかの小さな注意点があります。Inline::Filesは大文字のファイルのマーカーしか理解しないので、言語名を大文字の形式で指定しなければなりません。同様に、ソースコード・フィルタを使うためには起動時のペナルティがあります。

この時点では、Inline::Filesはアルファ版のソフトウェアで、それを使用することは実験的です。このモジュールをInlineに統合することも始まったばかりです。Inline::Filesでやろうとしていることに、拡張がコンパイルしなかったときエラーメッセージが正しいソースファイルと行番号を示すように、行番号情報を取得することがあります。

私ができる最もよいアドバイスはテストのためにはInline::Filesを使い(特に改良のサポートとしては)、製品用や配布用/CPANコードにはDATAを使うことです。

文字列
    use Inline Java => <<'END';
    
    /* Javaのコードはここ... */
    END
    
    # Perlのコードはここ...

ソースコードを1つの文字列として指定することもできます。文字列を書く手軽な方法はPerlでの引用のための"ヒアドキュメント"形式を使うことです。これは小さな関数では大丈夫ですが、大きなものでは厄介なことになるでしょう。また残念ながらバックスラッシュ文字をすべてエスケープする必要もあります。

プラスの面としては、文字列変数はおそらく起動時のペナルティが最少で、全ての関数がコンパイル時に結び付けられることがあります。

スカラ変数にその文字列を入れたければ、useステートメントがコンパイル時のディレクティブであるとこに気がついてください。そのため、それが使う全ての変数もコンパイル時、'use Inline'ステートメントのに設定されていなければなりません。以下のその方法の1つを示します:

    my $code;
    BEGIN {
        $code = <<END;
    
    /* Javaのコードはここ... */
    END
    }
    use Inline Java => $code;
    
    # Perlのコードはここ ...
bind() 関数

BEGINブロック・メソッドを使うもう1つの方法は、'Inline->bind()'メソッドを使って実行時にソースコードを指定することです。(これは上記で述べたインターフェースの例外の1つです)bind()メソッドは'use Inline ...'と同じ引数を取ります。

    my $code = <<END;
    
    /* Javaのコードはここ... */
    END
    
    Inline->bind(Java => $code);

bind()は強力な機能ですが、それはInlineをベースとしたモジュールにはお薦めしません。実際、インストールすることができるモジュールには全く機能しません。Inlineでモジュールを作るためには下記の手順をご覧ください。

その他のメソッド

Inlineのためのソースコードは、外部ファイル名、ソースコードを返すサブルーチンへのリファレンス、あるいはソースコードの行が入った配列へのリファレンスとしても指定することができます。これらのメソッドはそれほど頻繁には使われませんが、状況によっては便利でしょう。

省略形

上記で説明された'DATA'あるいは'FILE'メソッドを使い、さらに特別なパラメータが無ければ、そのキーワードを省略することが出来ます。例えば:

    use Inline 'Java';
    
    # Perlのコードはここ...
    
    __DATA__
    __Java__
    /* Javaのコードはここ... */

あるいは

    use Inline::Files;
    use Inline 'Java';
    
    # Perlのコードはここ...
    
    __JAVA__
    /* Javaのコードはここ... */

DATAセクションについての詳細情報

もしあなたがモジュールを書くのであれば、DATAセクションをPODやAutoLoaderサブルーチンのためにも使いたいかもしれません。最初のInlineマーカーよりも前にそれらを置くようにだけしてください。もしヘルパーモジュールInline::Filtersをインストールすると、あなたのInlineコードの内側でもPODを使うことさえもできます。あなたは外すためのフィルタを指定するだけです。

また複数のInlineセクション、おそらく異なるプログラミング言語を指定することもできます。以下に例をもう1つ示します:

    # モジュール Foo.pm
    package Foo;
    use AutoLoader;
    
    use Inline C;
    use Inline C => DATA => FILTERS => 'Strip_POD';
    use Inline Python;
    
    1;
    
    __DATA__
    
    sub marine {
        # これはオートロードされるサブルーチンです
    }
    
    =head1 External subroutines
    
    =cut
    
    __C__
    /* 最初のCのセクション */
    
    __C__
    /* 2番目のCのセクション */
    =head1 My C Function
    
    Some POD doc.
    
    =cut
    
    __Python__
    """Pythonのセクション"""

忘れてはいけない重要なことは、それぞれの"__Foo__"マーカーに対して1つの"use Inline Foo => 'DATA'"を持つ必要があり、それが同じ順番でなければならないということです。これにより各セクションに異なる構成設定オプションを適用することができます。

構成設定オプション

Inlineはできるだけ多く正しいことをしようとします。しかし場合によっては、デフォルトの動きを上書きする必要があるかもしれません。これを行うのは簡単です。単にInline構成設定オプションを通常のInlineパラメータの後に並べてください。全ての構成設定オプションは(キー,値)の組み合わせで指定されます。

    use Inline (C => 'DATA',
                DIRECTORY => './inline_dir',
                LIBS => '-lfoo',
                INC => '-I/foo/include',
                PREFIX => 'XXX_',
                NOWARN => 1,
               );

構成設定オプションを、以下のような別のInline呼び出しで指定することもできます:

    use Inline (C => Config =>
                DIRECTORY => './inline_dir',
                LIBS => '-lfoo',
                INC => '-I/foo/include',
                PREFIX => 'XXX_',
                NOWARN => 1,
               );
    use Inline C => <<'END_OF_C_CODE';

特殊なキーワード'Config'は、これが構成設定のみの呼び出しであることをInlineに伝えます。ソースコードはコンパイルされたり、Perlに結び付けられたりしません。

特定の言語に適用されない、グローバルな構成設定オプションを指定したいのであれば、呼び出しのさいに言語をはずすだけです。以下のようになります:

    use Inline Config => DIRECTORY => './inline_dir';

Configオプションは継承され、追加されます。何回でも好きなだけConfig呼び出しを使うことが出来ます。そして異なるコードセクションに異なるオプションを適用することができます。ソースコード・セクションが渡されたとき、Inlineはその時点で指定されている全てのオプションを適用します。以下に複雑な構成例を示します:

    use Inline (Config => 
                DIRECTORY => './inline_dir',
               );
    use Inline (C => Config =>
                LIBS => '-lglobal',
               );
    use Inline (C => 'DATA',         # 最初のCのセクション
                LIBS => ['-llocal1', '-llocal2'],
               );
    use Inline (Config => 
                NOWARN => 1,
               );
    use Inline (Python => 'DATA',    # 最初のPythonのセクション
                LIBS => '-lmypython1',
               );
    use Inline (C => 'DATA',         # 2番目のCのセクション
                LIBS => [undef, '-llocal3'],
               );

最初のConfig は後の呼び出しの全てに適用されます。2番目のConfigは残りのCのセクションに適用されます(しかしPythonセクションには適用されません)。最初のCのセクションでは、外部ライブラリglobal, local1 そして local2が使われます。(ほとんどのオプションは文字列と配列リファレンスのどちらも受け付け、適切に対応します。)Pythonセクションはglobalライブラリは利用しません。しかし同じDIRECTORYを使用します。そして警告は無効になっています。2番目のCのセクションはlocal3ライブラリだけを使用します。それはundefという値が付加する動きをリセットするからです。

DIRECTORYNOWARNというオプションは汎用的なInlineオプションです。他の全てのオプションは言語に特有です。Cのオプションが何かを見るためには、Inline::Cをご覧ください。

NOTE - Inlineの0.30より前のバージョンは、Inlineを構成設定するために、Inline::Configというモジュールを使いました。このモジュールはもはやサポートされていません。そしてInlineではもはや機能しません。もしそれをインストールしているのであれば、時折、発生する警告を避けるため、それを削除してください。Inline::Configで全てのことは、新しい構成設定の書き方を通して今でも可能です。

On と Off

もしある構成設定オプションの選択肢が1と0であれば、ENABLEとDISABLEという修飾語を使うことが出来ます。言い換えれば以下の通りです:

    use Inline Config => 
               FORCE_BUILD => 1,
               CLEAN_AFTER_BUILD => 0;

これを以下のように書き換えることが出来ます

    use Inline Config =>
               ENABLE => FORCE_BUILD,
               DISABLE => CLEAN_AFTER_BUILD;

他のものと'一緒(=with)'

Inlineは他のPerlモジュールからより多くの構成設定オプションを取得するように伝える特別な構成設定の書き方を持っています。以下に例を示します:

    use Inline with => 'Event';

これはInlineにモジュールEvent.pmをロードし、それに構成設定情報を尋ねるように伝えます。Eventは独自のC APIを持っているので、InlineにEventでのCのコールバックをシームレスに使うために必要とされるすべての情報を渡すことが出来ます。

つまりtypemap、共有ライブラリ、インクルードファイル、そしてこれが機能するために必要とされるその他の情報を指定する必要がないということです。

1つのモジュールあるいはモジュールのリストを指定することができます。以下のように:

    use Inline with => qw(Event Foo Bar);

現時点では、EventがInlineと一緒に(=with)機能する唯一のモジュールです。

Inlineのショートカット

Inlineにはコマンドラインから多くの構成設定オプションを設定することができます。これらのオプションは'ショートカット(=shortcut)'と呼ばれます。特にデバッグのときのように、一時的にだけオプションを設定したいときには、それはとても手軽です。

例えば、スクリプトFoo.plでのInlineコードについてのいくつかの一般的な情報を取得するためには、このコマンドを使ってください:

    perl -MInline=INFO Foo.pl

既にコンパイルされていたとしても、強制的にコードをコンパイルしたければ、、以下のようにしてください:

    perl -MInline=FORCE Foo.pl

その両方をやりたければ、以下のようにしてください:

    perl -MInline=INFO -MInline=FORCE Foo.pl

あるいは、このようにも書けます:

    perl -MInline=INFO,FORCE Foo.pl

Inline ディレクトリ

Inlineはコードをビルドし、ビルド結果をインストールするための場所を必要とします。通常の状況では'.Inline/'という名前の1つのディレクトリを使用します。もしこのディレクトリをあなたのホームディレクトリ、カレント・ディレクトリあるいはあなたのプログラムがあるディレクトリに作成すると、Inlineはそれを見つけ、利用します。それを環境変数PERL_INLINE_DIRECTORYや、DIRECTORYキーワード・オプションを使うことにより直接プログラムの中で指定することもできます。もしInlineがこれらの全ての場所で、そのディレクトリを見つけることが出来なければ、カレント・ディレクトリかスクリプトがあるディレクトリに'_Inline/'ディレクトリを作成します。

Inlineをうまく使うためのキーとなることは、このディレクトリを理解することです。コードを開発するとき、通常このディレクトリをカレント・ディレクトリに作成することが(あるいはInlineにそうさせることが)最もよいでしょう。それがコンパイルされたコードが入っているということを除いてはこのディレクトリについてなんら特別なことは無いということを忘れないでください。いつでも自由に削除することができます。Inlineは次の実行の際、単にスクラッチから初めて、コードを再コンパイルするだけです。もし強制的にリコンパイルしたいプログラムを複数の持っているのであれば、単純に'.Inline/'を削除してください。

おそらくあなたが作業しているプロジェクト毎に別の'.Inline/'ディレクトリを持つほうがいいでしょう。安定したコードをホームディレクトリの.Inline/に入れておきたいかもしれません。複数ユーザのシステムでは、それぞれのユーザは独自の'.Inline/'ディレクトリを持つべきでしょう。そのディレクトリを/tmp/のような共有されている場所におくことはセキュリティ上、危険となりえます。

Inlineエラーのデバッグ

全てのプログラマがミスします。正しくないCのコードを書くというように、Inlineでミスをすると、画面上の大きなエラーレポートが表示されます。このレポートはデバッグする場所を教えてくれます。

Inlineは何かビルドする必要があるとき、DIRECTORY/build/の下にサブディレクトリを作ります。ここが、あなたの拡張をビルドするために必要な全てのコンポーネントを書き出す場所になります。XSファイル、Makefileそして出力ログファイルといったものがあります。

もし全てがうまくいけば、Inlineはこのサブディレクトリを削除します。もしエラーがあれば、Inlineはそのディレクトリをそのまま残し、その場所を出力します。あなたがそのディレクトリに行き、何が起こったのかを理解するであろうと考えています。

詳細についてはそれぞれのInline言語モジュールのドキュメントをご覧ください。

'config' レジストリ・ファイル(=Registry File)

Inlineは、全てのInline言語サポート・モジュール(=Inline Language Support Module)の全てのメタデータのキャッシュされたファイルをconfigというファイルに取っておきます。このファイルはDIRECTORYディレクトリにあります。もしそのファイルが無ければ、Inlineは新しいものを作成します。それはあなたのシステムでInline::から始まるすべてのモジュールを検索します。そして将来の呼び出しのために有効な情報を取得するためにそのモジュールのregister()メソッドを呼び出します。

新しいILSMを追加するときにはいつでも、Inlineが自動的に新しくインストールされた言語モジュールを見つけるように、このファイルを削除しなければなりません。

構成設定オプション

このセクションは汎用のInline構成設定オプションをリストアップします。言語特有の構成設定については、その言語のドキュメントをご覧ください。

DIRECTORY

DIRECTORY構成設定オプションはInlineが拡張をビルドし、インストールするという両方に使うディレクトリです。

通常、Inlineは'.Inline/'というディレクトリを既知のディレクトリの中から検索します。それに失敗すると、'_Inline/'というディレクトリを作成します。

あなた独自のディレクトリを指定したければ、この構成設定オプションを使ってください。

DIRECTORYのディレクトリはあなた自身が作成しなければならないことに注意してください。Inlineはあなたに代わってそうすることはありません。

名前

このオプションを使ってあなたのInline拡張オブジェクト・モジュールの名前を設定することができます。例えば:

    use Inline C => 'DATA',
               NAME => 'Foo::Bar';

これはCコードを以下のようなオブジェクトにコンパイルさせます:

    lib/auto/Foo/Bar/Bar.so
    lib/auto/Foo/Bar/Bar.inl

(.inlコンポーネントには、ソースコードが実行形式と同期が取れていることを保証するための依存情報が入っています)

NAMEを使わなければ、Inlineはあなたのプログラム名あるいはパッケージ名に基づいて名前を選ぶでしょう。この場合、Inlineは一意であるようにするため、オブジェクト名をMD5フィンガープリントの小さな固まりにしてわからなくするAUTONAMEオプションも有効にするでしょう。

AUTONAME

このオプションはNAMEパラメータが指定されていないときにはいつでも有効になります。無効にするには以下のようにしてください:

    use Inline C => 'DATA',
               DISABLE => 'AUTONAME';

AUTONAMEは一意であるようにするために十分なMD5フィンガープリントで分からないようにします。AUTONAMEで作られたオブジェクトは置き換えられることはありません。これは自動的には片付けられないということも意味します。

AUTONAMEは小さく、捨ててしまうようなスクリプトにはとても便利です。より重要なものについては、常にNAMEオプションを使ってください。

VERSION

Inline拡張オブジェクトのバージョン番号を指定します。これはモジュールだけに有効です。そしてそれはグローバル変数$VERSIONに対応しなければなりません。さらにこのオプションはモジュールがPerlのsitelibツリーに永続的にインストールされるように設定されているとき(そしてそのときにのみ)使われるべきです。それ以外に使うならばInlineは警告(=croak)するでしょう。

VERSIONパラメータの存在は、あなたのコードがインストールすることができる/インストールされたモジュールであることをInlineが知る公式な方法です。VERSIONが設定されていると、Inlineは決して一時的なキャッシュ(_Inline/ directory)にオブジェクトを生成しません。それはだれかのPerlサイト・ツリーにインストールインストールされているモジュールをリコンパイルしようとしません。

そこで基本的な規則としては、開発はVERSIONなしに、配布はVERSION付でということになります。

WITH

WITHは、特殊な'with'による書き方の代わりに、構成設定オプションとしても使うことが出来ます。異なるモジュールにおいて=with、異なるInlineコードのセクションを使いたいのであれば、こうしてください。(おそらくは非常に珍しい使い方でしょう)

    use Event;
    use Inline C => DATA => WITH => 'Event';

WITHの構成設定(=config)形式を使って指定されたモジュールは、自動的にはrequireされません。それはあなた自身がuseしなければなりません。

GLOBAL_LOAD

このオプションはコンパイルされた言語専用です。これはInlineにDynaLoaderに、そのシンボルが他のオブジェクトファイルによって動的に解決されるような方法で、オブジェクトファイルをロードするよう伝えるように指示します。すべてのプラットホームで動くわけではないかもしれません。下記のGLOBALという短縮形をご覧ください。

UNTAINT

このオプションをPerlの-Tスィッチを使うときにはいつでも、このオプションを使わなければなりません。このオプションはInlineに盲目的に全ての汚染された(=tainted)変数を汚染されていないようにするよう伝えます。デフォルトでSAFEMODEを有効にもします。下記のUNTAINTという短縮形をご覧ください。

SAFEMODE

悪意あるコードを妨害するよう、特別なセキュリティ・チェックを実行します。このオプションは安全性を保障することは出来ません。しかし全ての現在実装されてるチェックを有効にします。

SAFEMODEを使うことによって若干起動が遅くなります。またUNTAINTを使うことは自動的に、このオプションを有効にします。-T (汚染)チェックしながら、コードの起動を速くする必要があれば、このオプションを手動で無効にする必要があります。安全の危険性について心配していないときにだけ、そうしてください。下記のUNSAFEという短縮形もご覧ください。

FORCE_BUILD

Inlineにプログラムが実行されるたびにソースコードをビルド(コンパイル)させます。デフォルトは0です。下記のFORCEという短縮形をご覧ください。

CLEAN_AFTER_BUILD

Inlineに、ビルドが成功したら現在のビルド領域をきれいにするように伝えます。時にはデバッグのためにこれをDISABLEにしたいかもしれません。デフォルトは1です。下記のNOCLEANという短縮形をご覧ください。

CLEAN_BUILD_AREA

InlineにInline DIRECTORY全体にある古いビルド領域をきれいにするように伝えます。デフォルトは0です。下記のCLEANという短縮形をご覧ください。

Inlineにソースコードに関する様々な情報を出力するように伝えます。デフォルトは0です。INFOという短縮形をご覧ください。

Inlineにそれ自身のバージョン(=Version)情報を出力するよう伝えます。デフォルトは0です。下記のVERSIONという短縮形をご覧ください。

REPORTBUG

Inlineを'REPORTBUG'モードにします。それはバグを報告したいときに望むものです。

NOWARN

このオプションはInlineにすべての警告を無効にするよう伝えます。

注意: これはまだ NOT 実装されていません。

Inline構成設定 短縮形

これは、現在Inlineで利用できる構成設定オプションの短縮形の全てのリストです。Inlineスクリプトを実行するとき、コマンド行からそれらを指定してください。

    perl -MInline=NOCLEAN inline_script.pl

あるいは

    perl -MInline=Info,force,NoClean inline_script.pl

複数の短縮形をカンマで区切って指定することができます。大文字/小文字は区別されません。以下のようにInlineプログラムの中で短縮形を指定することも出来ます:

    use Inline 'Info', 'Force', 'Noclean';

注意: もし'use Inline'ステートメントが短縮形を設定するために使われるならば、それを追加の目的のために使うことは出来ません。

CLEAN

Inlineにビルド領域にある全てのビルド・ディレクトリを削除するように伝えます。通常はこれらのディレクトリはビルドが成功するとすぐに削除されます。例外は、ビルドが失敗したときやあなたがNOCLEANやREPORTBUGオプションを使うときです。

FORCE

全てが最新であったとしても、コードが再コンパイルされるよう強制します。

GLOBAL

GLOBAL_LOADオプションを有効にします。

INFO

覆いの下で何が行われようとしているのかを知りたいときには、これはとても便利なオプションです。これはInlineに助けになる情報をSTDERRに出力するように伝えます。出力されるもののなかには、どのInline関数が正常にPerlに結び付けられたかのリストも入っています。

NOCLEAN

Inlineにコンパイル後、ビルドに使ったファイルをそのままにしておくよう伝えます。

REPORTBUG

Inlineを'REPORTBUG'モードにします。それはバグを報告したいとき、特別な処理を行います。REPORTBUGは自動的にビルドを強制し、その後、きれいにしないようにもします。これはビルド・ディレクトリをtarし、私にメールできるようにするためです。REPORTBUGは実行すべき手順を厳密に出力します。それを注意して読み、従ってください。

注意: REPORTBUG はtarコマンドを使うように知らせます。もしあなたのシステムがtarを持っていなければ、同等のzipコマンドを使ってください。

SAFE

SAFEMODEを有効にします。UNTAINTが自動的に有効になります。このコードは特別なセキュリティ・チェックを行いますが、安全性は保証しません。

SITE_INSTALL

このパラメータはインストール可能なInlineモジュールを作成するよう使われてきました。Inlineから削除され、さらに簡単で、より強力な仕組みであるInline::MakeMakerに置き換えられました。Inlineでモジュールを作る方法については下記のセクションをご覧ください。

UNSAFE

SAFEMODEを無効にします。-Tのとき起動時間を少し速くするため、UNTAINTと組み合わせて使ってください。その環境が安全であると確信しているときにだけ使ってください。

UNTAINT

UNTAINTオプションを有効にします。-Tと一緒に使われます。

VERSION

Inlineに、そのリリース・バージョンを出力するように伝えます。

Inlineでモジュールを書く方法

Inlineを使えば、Cのコードを使うCPANモジュールを書くことは簡単です。Math::Simpleというモジュールを書きたいとします。まず以下のコマンドを使うことから始めてください:

    h2xs -PAXn Math::Simple

これは配布可能なモジュールを作成するために必要な骨組みを形成する一連のファイルを生成します。(オプションが何をするのかを知るために、h2xsマニュアルページをお読みください)次にSimple.pmファイルを以下のように変更してください:

    package Math::Simple;
    
    use strict;
    use vars qw($VERSION @ISA @EXPORT_OK);
    require Exporter;
    @ISA = qw(Exporter);
    @EXPORT_OK = qw(add subtract)
    $VERSION = '0.20';
    
    use Inline C => 'DATA',
               VERSION => '0.20',
               NAME => 'Math::Simple';
    
    1;
    
    __DATA__
    
    =pod
    
    =cut
    
    __C__
    int add(int x, int y) {
      return x + y;
    }
    
    int subtract(int x, int y) {
      return x - y;
    }

ここで注意しなければならない大切なことは、NAMEVERSIONパラメータを指定しなければならないことです。NAMEはモジュールのパッケージ名と対応しなければなりません。VERSIONパラメータはモジュールの$VERSION変数に対応しなければなりません。そしてそれは/^\d\.\d\d$/という形式でなければなりません。

注意: これらはCPANにアップロードする前に行うべきを確実に知っているようにするための、Inlineの健全かどうかのチェックのチェックです。これにより、一旦、モジュールがだれかのシステムにインストールされると、モジュールはいかなる理由があっても自動的には再コンパイルされないことを保証します。これによりInlineをベースとしたモジュールはXSをベースとしたものと全く同じ方法で機能することになります。

最後にMakefile.PLを変更する必要があります。単に以下のように変更してください:

    use ExtUtils::MakeMaker;

を以下のように

    use Inline::MakeMaker;

そして以下の行を変更してください:

    WriteMakefile(...);

を以下のように

    WriteInlineMakefile(...);

Math::Simpleをインストールする人は"make"するとき、生成されたMakefileは、Cのコードがコンパイルされ、実行可能コードが./blibディレクトリに置かれるように、Inlineを呼び出します。そして"make install"が行われると、モジュールは適切なPerlsitelibディレクトリにコピーされます(そこはインストールされるモジュールが行くべきところです)。

そして、あなたがしなければいけないことはこれだけです:

    perl Makefile.PL
    make dist

これは配布可能なパッケージであるファイルMath-Simple-0.20.tar.gzを生成します。それがあれば完了です。

重要事項: 上記のステップは機能するモジュールを生成しますが、新しく生まれるCPAN authorとして、さらにいくつかの責任を持たなければならないことがあります。あなたは多くのドキュメントを書き、多くのテストを書かなければなりません。すばらしいテスト・ハーネスを作るアイデアのための、よりよいCPANモジュールを探してください。実際、私に聞かないで、以下の資料をご覧ください:

    perldoc perlnewmod
    http://www.cpan.org/modules/04pause.html
    http://www.cpan.org/modules/00modlist.long.html

どのようにInlineは機能するのか

実際には、Inlineは(XSなどを使って)手でやるとすれば、あなたがやらなければならないことの全てを自動化しているだけです。

Inlineは以下の段階を行います:

1 ソースコードの受取

Inlineは以下のようなステートメントが入った、あなたのスクリプトやモジュールからソースコードを受け取ります:

    use Inline C => "Source-Code";

あるいは

    use Inline;
    bind Inline C => "Source-Code";

Cのところはソースコードのプログラミング言語になります。そしてSource-Codeは文字列、ファイル名、配列リファレンスあるいは特別な'DATA'キーワードになります。

Inlineが"use"ステートメントで書かれているので、すべてのことはPerlのコンパイル時に行われます。もし行われなければならないことの何かがSource-Codeに影響を与えるのであれば、"use Inline ..."ステートメントのにあるBEGINブロックで行われる必要があります。実行時にInlineにコードを指定する必要が本当にあれば、bind()メソッドを使うことが出来ます。

あなたのコードの'DATA'セクションに格納されているソースコードは、InlineでのINITサブルーチンによって読み込まれます。これはDATAファイルハンドルがコンパイル時点では利用できないからです。

2 ソースコードがビルドされているかをチェックする

Inlineはまだビルドされていないときにだけ、ソースコ−ドをビルドする必要があります。それはこの表面上は魔法のような仕事を非常に簡単で直接的な方法で実現します。それは実質上は一意になる128ビットの"指紋(=フィンガープリント)"を生成するため、ソースコードをDigest::MD5に通します。そのフィンガープリントは、その他の偶発的な情報と一緒に、あなたの実行可能なオブジェクトの隣にある.inlファイルに格納されます。例えばexample.plというスクリプトからのCのコードは、以下のようなファイルを作成するでしょう:

    example_pl_3a9a.so
    example_pl_3a9a.inl

もし全ての偶発的な情報が.inlファイルに格納されている値とマッチすれば、ステップ8に進みます。(コンパイルは必要ありません)

3 ビルドしインストールする場所を見つける

この時点でInlineはソースコードをビルドする必要があることが分かっています。最初に知らなければならないことは、コンパイルに関連する厄介ものをどこに作るか、そしてそれが終わったときオブジェクトをどこに入れるかです。

デフォルトでは、Inlineは以下の条件に合う最初の場所の下にビルドしインストールしようとします:

    A) DIRECTORY= config オプション; 指定されていれば
    B) PERL_INLINE_DIRECTORY 環境変数; 設定されていれば
    C) (現在のディレクトリの).Inline/ ; 存在し、$PWD != $HOMEであれば
    D) (あなたのスクリプトのディレクトリの)bin/.Inline/ ; 存在すれば
    E) ~/.Inline/; 存在すれば
    F) ./_Inline/; 存在すれば
    G) bin/_Inline; 存在すれば
    H) ./_Inline/を作成; 可能であれば
    I) bin/_Inline/を作成; 可能であれば

それに失敗すると、Inlineはcroakします。これは非常にまれで、単にInlineが使うディレクトリを作成するだけで簡単に直すことができます;

モジュール・オプションが永続的なインストールのためにコンパイルされるのであれば、Inlineはビルドするためだけに./_Inline/を使い、実行ファイルをインストールするため$Config{installsitearch}ディレクトリを使うでしょう。この動きはInline::MakeMakerによって引き起こされます。そしてCPANで配布されるモジュールで使われることを目指して、適切な場所にインストールされます。

4 意味的な手がかりのためにソースを解析

Inline::Cは、Cのソースコードの固まりを解析し、実行時の結び付けを作ることが出来るようなものを探すため、モジュールParse::RecDescentを利用します。Cでは、全ての関数定義を探し、それを名前とデータ型に分解します。これらの要素はCの関数をPerlのサブルーチンに正しく結びつけるために使われます。PythonやJavaのような他のInline言語はInlineコードを解析するためpythonjavacモジュールを使います。

5 ビルド環境の作成

これでInlineは収集された情報のすべてを取得し、ソースコードを実行形式にビルドするための環境を作成することができます。全ての詳細に入りこむことなく、(Cのための)XSファイルも含めて適切なソースファイルとMakefile.PLを作成します。

6 コードをビルドし、実行形式をインストール

惑星は直線に並んでいます。ここからは簡単な部分です。Inlineは単にモジュールをインストールするためにあなたがするであろうことをするだけです。"perl Makefile.PL && make && make test && make install"します。何かがうまくいかなければ、Inlineはさらに詳しい情報のためにどこを見るべきかを示すメッセージでcroakします。

7 後片付

デフォルトでは、Inlineは、すべてが上手くいったものとすれば、ビルド・プロセスで作成されたすべてのゴミを削除します。もしビルドに失敗すると、あなたがエラーをデバッグできるように、Inlineは全てをそのままにして残しておきます。NOCLEANという短縮形オプションを設定することも、Inlineに片付けを止めさせます。

8 実行形式をDynamicLoad

C (そして C++)では、Inlineは、あなたの実行形式をPerlの空間に引っ張り込むためにDynaLoader::bootstrapメソッドを使います。これで全ての外部関数をPerlのサブルーチンのように呼び出すことが出来ます。

PythonやJavaのような他の言語は、それ専用のローダを備えています。

参考資料

CでInlineを使うことについての情報についてはInline::Cをご覧ください。

CでInlineを使うサンプル・プログラムについてはInline::C-Cookbookをご覧ください。

Inlineについて"既に答えられている質問"については、Inline-FAQをご覧ください。

サポートされている言語とプラットホームについての情報はInline-Supportをご覧ください。

独自のInline言語サポートモジュールを作成することについての情報はInline-APIをご覧ください。

Inlineのメーリングリストはinline@perl.orgです。

参加するためには、inline-subscribe@perl.orgにメールしてください。

バグと欠陥

Inline.pmはベータ(=BETA)版のソフトウェアです。非常に強力で広く使われているツールですが、まだ開発中であり、発展中です。Inlineは後方互換性のないいくつかの段階を通ることでしょう。こうしたことはあまりありませんし、合理的な理由によるものでしょう。そしてメーリングリストで常に議論されています。

バグを報告するときには以下のことをしてください:

 - コードの先頭に"use Inline REPORTBUG;"と入れるか、"perl -MInline=REPORTBUG ..."というコマンドライン・オプションを使ってください。
 - コードを実行してください。
 - 出力される説明に従ってください。

リリース0.40は、チェックの古いメソッドを新しくより強力なもので置き換えます。しかしまだそのように新しいコードであり、新しいバグもあるかもしれません。製品の中でInlineを使うのであれば、リリース0.4xが安定していると分かるまでは、最後の0.3xバージョンに留まっていたいかもしれません。

作者(=AUTHOR)

Brian Ingerson <INGY@cpan.org>

Neil Watkiss <NEILW@cpan.org> は Inline::CPP, Inline::Python, Inline::ASM, Inline::Struct そして Inline::Filtersの作者です。彼はInline仲間の極内輪では"Boy Wonder"として知られています。

著作権(=COPYRIGHT)

Copyright (c) 2000, 2001. Brian Ingerson. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html