ソースコードからのビルドとインストール (Windows編)¶
目次
準備¶
コレオノイドをソースコードからインストールするには、ビルドに必要なツールとライブラリを予め準備する必要があります。
- 必要なツール
- Visual C++ 2010 (Visual C++ 2008はバージョン1.2からサポート対象外としました。）
- CMake (2.8.6, 2.8.8)
- 必要なライブラリ
- Boost (1.47.0)
- Qt (4.8.1)
- OpenSceneGraph (3.0.1)
- Eigen (3.0.6) (コレオノイド1.2.0より自前インストールが必要)
まず、上記のツールとライブラリをインストールをして下さい。各ライブラリの括弧内の数値は、当方で利用し動作を確認したバージョンで、2012年7月19日時点での目安となるものです。これらより古いバージョンのものに必ずしも対応しないわけではありませんし、一方でこれらよりバージョンが上のものでビルドに失敗することもあり得ます。（正確に対応バージョンを特定するのは困難ですので、このような記述をご容赦ください。）一般的にはバージョン番号の２番目の値までが同じであれば、同様に使えると考えてよろしいかと思います。
各ツール・ライブラリのインストールに関する補足を以下に述べます。
- Visual C++
製品版でも結構ですし、無料で使用可能な Express Edition をダウンロードして利用することも可能です。
注釈
コレオノイドバージョン1.1.0までにあった、Visual C++ 2010 においてデバッグ版でビルドすると実行が出来ない問題は、コレオノイド1.2.0以降では解消されました。
注釈
当方の環境で、Visual Studio 2010 Professional Edition を対象にCMakeでソリューションファイルを作成しようとすると、エラーが出て先に進めないという問題が発生しています。詳細は不明ですが、Windows Update による Visual Stuido の修正が、CMakeにとって具合が悪かったのかもしれません。当方ではこの問題を解決できなかったので、現在 Visual C++ 2010 Express Edition を使用しています。
- CMake
CMakeのダウンロードページ より、Windows版のインストーラをダウンロードできます。
- Boost
ヘッダーのみではなく、system、filesystem、program_options、regex、signals、thread、iostreams 等のコンパイルが必要なライブラリも必要になります。コンパイル済みライブラリの取得には、 BoostProのダウンロードページ にて配布されているWindows版インストーラを利用するのが簡単です。この場合、インストールダイアログにて対応するVisual C++のバージョンをチェックし、ライブラリの形式については Multithread DLL をチェックします。デバッグ版もビルドする場合は、Multithread debug DLL もチェックしておきます。インストールするライブラリについては、全てをチェックしておけばよいかと思います。
注釈
コレオノイド1.2では Boost 1.50 を用いるとコンパイルエラーになってしまいましたが、コレオノイド1.3ではこの問題を解決しており、Boost 1.50 も利用することが可能です。
- Qt
Qt のダウンロードページ より、Windows版のインストーラをダウンロードできます。パッケージの種類がいくつかありますが、通常は "Qt libraries" の Windows・VS2010版を使うのがよろしいかと思います。
- OpenSceneGraph
AlphaPixel の OpenSeneGraphバイナリダウンロードページ から、対応するパッケージをダウンロードして使うのが簡単です。それぞれのバージョンに対してアーカイブが３つに分かれていますが、全てダウンロードして展開し、ひとつのディレクトリに統合（マージ）しておく（エクスプローラ上でコピーして「フォルダを統合しますか？」に「はい」と応える、などする）と使いやすいかと思います。7zファイルの展開は 7-Zip というソフトで行うことが出来ます。
注釈
このOpenSceneGraphライブラリの利用により、コレオノイドでは一般的なフォーマットの3Dモデルファイルを表示用として読み込んだり、3D表示領域を画像ファイルとして保存したりすることも可能です。その際に日本語等の非アスキー文字を含むファイルパスを利用したい場合は、OpenSceneGraphのビルド時に "OSG_USE_UTF8_FILENAMES" というビルドオプションを有効にしておく必要があります。上記のAlphaPixelで配布されているバイナリはこのオプションが有効になっていないようですので、ご注意ください。
- Eigen
Eigenの公式ページ からダウンロードできます。本ライブラリは基本的にヘッダファイルのみからなるテンプレートライブラリであり、適当なディレクトリに展開するだけで、インストールは完了となります。
ソースコードの取得¶
コレオノイドのソースコードアーカイブ (choreonoid-x.x.x.zip) をダウンロードページからダウンロードして適当なフォルダに展開して下さい。 このときパスに日本語が含まれていますとエラーが出る可能性がありますので注意して下さい。
以下では、コレオノイドのソースコードは、 "c:\choreonoid\src" の下に展開していると仮定して説明を進めていきます。
CMakeを実行¶
まず、スタートメニューからCMake(cmake-gui)を起動します。すると下記のようなダイアログが表示されます。
次に、上図の赤枠①で示された "where is the source code" の右側の入力ボックスにコレオノイドのソースコードのトップフォルダ（"c:\choreonoid\src"）を入力し、 "where is build the binaries" の右側の入力ボックスにコレオノイドをビルドするフォルダを入力します。 ビルドするフォルダはソースコードのトップと同じでも構いませんが、わかりにくくなるかもしれませんので、ソースコードのトップフォルダの下にbuildというフォルダを作成して、そこ（"c:\choreonoid\src"）を入力することにします。 フォルダの入力が終われば、赤枠②の "Configure" を押します。 すると下図のようなダイアログが開きますので、コンパイラを選びます。
お使いのVisual C++ バージョンに合わせて選択し、"Finish" を押します。 Visual C++ 2010 でしたら、"Visual Studio 10 2010" といった項目と、 デフォルトの "Use default native compilers" でよろしいかと思います。
注釈
コレオノイドバージョン1.2以降で当方が対応を確認しているVisual C++ のバージョンは 2010 のみとなっており、他のバージョンではそのままではビルドできない可能性がありますので、ご注意ください。
すると、CMakeのConfigureが進行し、再度、下図のようなエラーダイアログで停止します。 これは、OpenSceneGraphに関する設定が見つからなかったためです。 （他のエラーが最初に出るかもしれません。これについては後ほど説明します。） ここでは、 "OK" を押して下さい。
次に、上部のEntry入力部の OSG_DIR の右の入力ボックスにOpenSceneGraphをインストールしたフォルダを入力します。OSG_DIR の設定が終わったら、再度、"Configure" を押して下さい。
注釈
他のライブラリに関しても、CMakeのバージョンやインストールしたライブラリのバージョン、インストール箇所などによっては、検出できずに同様のエラーが出ることがあります。また、以下で説明するオプションの選択によっても、エラーが出る場合があります。この場合、上記のOpenSceneGraphと同様に、手動でインストール先を入力するようにしてください。コレオノイドバージョン1.2であれば、他にEigen, Open Dyanmics Engine (ODE), OmniORB などが、インストール先の指定が必要なライブラリとして挙げられます。
注釈
Boostに関してはお使いのCMakeやコレオノイドがリリースされた時期よりも新しいバージョンのものは、基本的に検出できないようです。この場合、Boostに関して同様の検出エラーが発生します。自動検出を行うためには、ChoreonodiソースのトップディレクトリのCMakeLists.txtにある "Boost_ADDITIONAL_VERSIONS" に使いたいバージョン番号を追加する必要があります。
必要なライブラリのインストール先が全て特定され、エラーが出なくなるまで、上記と同様の設定を繰り返してください。 それらが全て完了すると、エラーメッセージの出ていない、下図のような画面になります。
後は、必要に応じてビルドに関する他の様々なオプションを設定することが可能となっています。 例えば、コレオノイドが備えているいくつかの機能はデフォルトではオフになっていますが、 必要に応じてそれらをオンにすることができます。
他にいくつか設定した方がよい項目を説明します。 まず、インストール先の設定があります。 これは CMAKE_INSTALL_PREFIX という項目で設定することが可能で、 デフォルトでは "c:\Program Files\Choreonoid" になっています。しかし、Windows7 では "c:\Program Files" 以下は、管理者以外はアクセス不可になっているようですので、インストール時に失敗する可能性があります。管理者権限で実行してそこにインストールしてもよいのですが、他のフォルダにインストールした方が扱いやすい場合もあります。 その場合は、 CMAKE_INSTALL_PREFIX に適当な、例えば "c:\choreonoid\program"といったフォルダを 指定しておいてください。
また、デフォルトではインストール先にコピーされるのは、コレオノイドのソースから作成したライブラリとコマンドのみであり、Boost や OpenSceneGraph 等のライブラリはコピーされません。もしコレオノイドの起動時に必要なファイルをすべてインストールさせたい場合には、 INSTALL_DEPENDENCIES の項目にチェックを入れておいて下さい。 INSTALL_DEPENDENCIES にチェックを入れない場合は、各ライブラリのDLLにパスが通っている必要があります。
必要な設定を終えたら、"Configure"を押してください。 設定を終えても、"Generate"のボタンが押せるようになっていない場合は、再度"Configure"を押します。 Configureが進行し、下図のように下部のメッセージ出力部に、 “Configuring done” と表示され、 "Generate"ボタンが押せるようになったら、設定は完了です。
最後にVisual Studio のプロジェクトファイルを生成するために、"Generate" を押して下さい。
ソリューションファイルの生成が終了すれば、メッセージ出力部に “Generating done” と表示されて完了です。 エクスプローラ等で、コレオノイドをビルドするフォルダにVisual Studio のソリューションファイル "Choreonoid.sln" が生成されていることを確認して下さい。
Visual Studio の起動とソリューションの読み込み¶
CMake で Visual Studio のソリューションファイルが生成されていることが確認できれば、次はコレオノイドのビルドを行いますので、 "Choreonoid.sln" をダブルクリックして下さい。Visual Studio が起動し、ソリューションファイルがオープンされていると思います。 もし Visual Studio が起動しない場合には、インストール時に何かあったかもしれませんので、Visual Studio を再インストールするか、関連付けを修正してみてください。あるいは、まず Visual Studio を起動し、その後 Visual Studio のメニューからソリューションファイルを読み込めばうまくいくかもしれません。
コンパイル¶
ソリューションの読み込みが終われば、下図のような画面になります。 ここで、赤枠の部分を "Release" に変更して下さい。 なお、"Debug"にすると、デバッグ可能なバイナリを生成することができます。ただしこれは"Relese"でコンパイルしたものと比べて圧倒的に遅くなってしまうので、デバッグが必要な時以外は、"Release"でコンパイルしたバイナリを使うようにします。
次に、コレオノイドのビルドを実行します。メニューのプロジェクトをクリックすると下図のようなプルダウンメニューが出てきますので、赤枠にあるように "ソリューションのビルド(B)" を選択して下さい。 すると、コレオノイドのビルドが開始されます。 下部のメッセージウィンドウで最後に、 “0 失敗” と出てくればコンパイルは終了です。
インストール¶
コレオノイドのビルドが終了したら、最後にインストールを実行します。 インストールは、下図にあるように、上段左の "ソリューションエクスプローラ" で "INSTALL" のプロジェクトの部分を右クリクするとメニューが表示されます。このメニューの最上部に "ビルド(U)" がありますので(下図の赤枠部分です)、それを選択して下さい。正常に終了すれば、CMakeの時の CMAKE_INSTALL_PREFIX で指定されたフォルダの下に、コレオノイドのバイナリがコピーされます。CMakeによるソリューションファイル生成時に INSTALL_DEPENDENCIES の項目にチェックを入れておけば、依存ライブラリのバイナリもコピーされます。
以上でコレオノイド のインストールは終了です。
インストール先の bin フォルダにある choreonoid.exe をダブルクリックすることで、コレオノイドが起動します。
オプション機能のビルド¶
コレオノイドでは、上記手順のデフォルト状態で有効になるもの以外にも、いくつかのモジュールやプラグイン、サンプル等があります。それらは、CMakeの設定で有効にすることで、ビルドすることができます。 ここではそれらオプション機能のうちいくつかのビルドについて述べます。 オプションモジュールの概要 にて他のオプションについてもまとめてありますので、そちらもご参照ください。
ODEプラグイン¶
フリーの動力学計算ライブラリである"Open Dynamics Engine (ODE)"を、コレオノイドのシミュレーション機能の計算エンジンとして利用できるよにするプラグインです。
本プラグインをビルドして利用するためには、ODEライブラリのインストールが必要です。 Open Dynamics Engine のページから取得して、まずそちらをビルド・インストールしてください。現在当方でテストを行ったバージョンは、0.12になります。
後は、コレオノイドのビルドに関するCMakeの設定で、 BUILD_ODE_PLUGIN という項目を "ON" にすることで、本プラグインがビルドされます。このライブラリはWindows上では自動検出されませんので、 BUILD_ODE_PLUGIN を "ON" にした後、 ODE_DIR にODEのインストール先を指定してください。
CORBAモジュール¶
コレオノイド上でCORBA関連の機能を使えるようにするためのモジュールです。 OpenHRP関連機能を提供する"OpenHRPプラグイン"を利用するためには、このモジュールが必要となり、 そのためにはCORBAライブラリのひとつである "omniORB" のインストールも必要となります。
omniORBは 配布元 から取得して自前でビルド・インストールを行なってもよいのですが、Windowsだと少々手間がかかります。一方、より簡単にインストールする方法として、OpenRTM-aistのインストーラを使う方法があります。その場合、 OpenRTM-aist official website の「ダウンロード」のページから、対象となる Visual Studio バージョンとCPUアーキテクチャに適合する「Windowsインストーラ」をダウンロードして、インストールしてください。これにより、OpenRTM-aistと同時にomniORBもインストールされます。
omniORBが正しくインストール出来ましたら、CMake上でまず ENABLE_CORBA をオンにし、続けてomniORBのインストール先を OMNIOR_DIR に設定します。さらに、 BUILD_CORBA_PLUGIN をオンにすると、OpenHRPプラグインに対応する BUILD_OPENHRP_PLUGIN もビルドできるようになります。
GRobotプラグイン¶
../choreograph-tutorial/index では、エイチ・ピー・アイ・ジャパンによる小型二足歩行ロボット"G-Robots GR001"をサンプルモデルとして使います。このロボットの実機をお持ちの場合は、 BUILD_GROBOT_PLUGIN をオンにして、GRobotプラグインをビルドしておいてください。すると、実機を動かしながらチュートリアルを進めることが出来ます。
Balancerプラグインの導入¶
"Balancerプラグイン"の導入により、二足歩行ロボットを対象に動力学バランスを自動補正し、実機においても転倒しない動作を作成する機能が追加されます。このプラグインは現在のところソースを公開しておらず、コンパイル済みのバイナリのみの提供としています。
Windowsにおいては、現在のところ Visual C++ 2010 の32ビット・リリースモードとしてビルドされたChoroenoid本体に対して有効なバイナリを提供しています。これを利用するためには、ソースのproprietary/BalancerPlugin以下の"CnoidBalancerPlugin.dll"を、コレオノイドのプラグインディレクトリ(インストール先の lib/choreonoid-x.x/ 以下）にコピーしてください。
また、"proprietary/BalancePlugin/locale/ja/LC_MESSAGES/CnoidBalancerPlugin-1.2.mo" をビルド（インストール）先の "share/locale/ja/LC_MESSAGES/" 以下にコピーすることで、本機能を日本語で利用できるようになります。
なお、Balancerプラグインのライセンスはコレオノイド本体のライセンス(LGPL)とは異なりますので、ご注意ください。使用条件は proprietary/BalancerPlugin/LICENSE でご確認ください。この条件を超える範囲の利用やソースコードに取得に関しては、産総研までお問い合わせください。