Skip to content

Developper's manual

Jump to bottom Edit New page
Daisuke YAMAGUCHI edited this page Sep 20, 2016 · 14 revisions

siren 開発者向けのマニュアルです。

構成

LICENSE      ... ライセンスファイル
doc/         ... ドキュメンテーション
examples/    ... サンプルコード
inc/         ... C/C++ ヘッダー
mrblib/      ... Ruby スクリプトファイル
src/         ... C/C++ ソースコード
test/        ... テストファイル
viewer/      ... STLLoader ビューア(WebGL/three.js)
README.md    ... Readme
mrbgem.rake  ... ビルド設定

LICENSE ライセンスファイル

MIT ライセンスの文章。コピーライト表記や年が変わった場合のみ修正します。

doc ドキュメンテーション

siren に関するドキュメント置き場。ただし、現在は仕様が大きく変わり、オンライン情報との整合性も取りづらい（手がまわらない）ため、中にはオンラインを参照するようリンクのみを記述したファイルがあるだけです。

examples サンプルコード

siren で動くサンプルコード。リリースバージョンを作成する際、最低限このスクリプトは動くようにしています。今のところテストコードも兼用しています。

inc および src

C および C++ で記述した siren のコア部分のファイル置き場。Rake 時にこのディレクトリを参照します。 C や C++ で実装しなければならないコードは、主に OCCT の呼び出し部分のみにする方針です。Ruby 側で可能な処理は、生産性やメンテナンス性の向上のため、mrblib ディレクトリ内に Ruby スクリプトファイルとして記述します。

mrblib Ruby スクリプトファイル

このディレクトリにある Ruby スクリプトは、Rake 時にバイトコードに変換され、実行バイナリの内部に格納されます。 C または C++ で書く必要がない機能はこちらに入っています。

test テストファイル

機能の単体テスト用のファイル置き場。今のところ、テストコードはメンテされていません。（つまり、実装側の変更がすべてのテストコードにフィードバックされているわけではありません）

カスタマイズ

  • コードは C99 および C++11 に準拠しています。
  • OCCT のクラスのインスタンスは生成して使用しますが、siren 内で C++ のクラスを作らないようにします。現在のところ、siren が C++ の機能を使って構造化する必要がない上に、C++ の世界でのオブジェクトの作成・解放の管理が増えるためです。(mruby の GC と OCCT の GC が既に共存している形です。）

Siren モジュールに C++ でメソッドを追加する

Siren モジュールに新しいクラスメソッド(C++でいうスタティック関数のような呼び出しが可能なもの)を追加するには、次の手順を行います。

1. メソッドを追加するソースコードを選択する。

ソースコード名はほとんどが OCCT のツールキット名に対応しています。例えば、TKTopAlgo だった場合、ソースコードは topalgo.cpp ヘッダーファイルは topalgo.h になります。siren は、C/C++ で記述する部分を OCCT 側へのラッパーとして最低限にする方針です。そのため、ツールキット名に対応させています。ただし、複数の API を組み合わせたり、どのツールキットにも該当しない場合はこの限りではありません。また、Ruby 側に出しているクラスもツールキット名にはなりません。

例として topalgo.cpp を選択したとします。

2. 関数の追加。

OCCT の呼び出しを行う以上、関数内では C++ を用いていますが、C++ である必要がない部分は C の静的関数として実装します。siren 独自の C++ クラスは作っていません。例として test というメソッドを追加します。

  1. topalgo.h に、関数宣言を追加します。

    mrb_value siren_topalgo_test(mrb_state* mrb, mrb_value self);

  • 仮引数は上記のように宣言します。これは Ruby のメソッドとして呼び出すための共通インターフェイスとなっているため、変更はできません。
  • 関数名は、siren 独自のものは siren_ から始めます。mruby 由来のものは、すべて mrb_ 接頭辞が付いています。
  1. OCCT のヘッダーファイルが必要な場合は、ヘッダー内に追記します。
#include <TopoDS_Shape.hxx>
  1. topalogo.cpp に、関数の実体を追加します。
mrb_value siren_topalgo_test(mrb_state* mrb, mrb_value self)
{
  return mrb_nil_value();
}

上記の関数は、例として Ruby の Nil オブジェクトを返します。

3. メソッドとして登録

topalgo.cpp の siren_topalgo_install 関数を見つけ、

mrb_define_class_method(mrb, rclass, "test", siren_topalgo_test, MRB_ARGS_REQ(1));
mrb_define_method(mrb, rclass, "test", siren_topalgo_test, MRB_ARGS_REQ(1));

のように2行追加します。

1つめは Siren.test という記法で呼び出すための宣言です。2つめは、include Siren した後に test だけを記述して呼び出せるようにするためのものです。

第1、第2引数は変更する必要はありません。第3引数は、実際に Ruby から呼び出されるメソッド名の文字列、第4引数は前項で定義した関数のアドレス、第5引数はこのメソッドが必要としている引数の必要数・オプション数です(ただし mruby 側の実装では、まだこの値は引数チェックに使われていないと思います。不整合があっても動きます)。近隣のコードを参考にしてください。

3. ビルド、実行

mruby ディレクトリに移動して、make または ruby minirake します。ビルドが完了したら、bin/mirb または bin/mruby script.rb を実行します。

4. デバッグ

C/C++ コード部のデバッグには、GDB を用います。(cgdb, lldb (mac の標準) も使えます)

$ gdb bin/mruby
gdb> r script.rb
...

参考: http://uguisu.skr.jp/Windows/gdb.html

Shape モジュールにメソッドを追加する

Add a custom sidebar

Clone this wiki locally