
ソースコードからのビルドとインストール (Ubuntu Linux編)
========================================================

.. sectionauthor:: 中岡 慎一郎 <s.nakaoka@aist.go.jp>

Linuxには様々なディストリビューションがありますが、現在のところChoreonoidが公式にサポートしているディストリビューションは Ubuntu Linux になります。本ドキュメントでは、Ubuntu Linux におけるChoreonoidのソースコードからのビルド方法について説明します。ポイントを押さえれば他のディストリビューションでもビルド出来ると思われますので、必要であればトライしてみてください。

Choreonoidの最新版であるバージョン1.5では、Ubuntuバージョン14.04、16.04、x64アーキテクチャ(64ビット）でのビルドと動作を確認しています。

.. contents::
   :local:


ソースコードの取得
------------------

リリース版
~~~~~~~~~~

Choreonoidのリリース版のソースコードは、 `ダウンロード <http://choreonoid.org/ja/download.html>`_ のページからダウンロードすることが可能です。このページにある「ソースパッケージ」の該当するバージョンをダウンロードしてください。ファイルはZIPファイルになっていますので、適当なディレクトリで ::

 unzip choreonoid-1.5.0.zip

などとして展開してください。

展開すると choreonoid-1.5.0 といったディレクトリが生成されます。このディレクトリの中にソースコード一式が格納されており、本マニュアルではこれを今後 **「ソースディレクトリ」** と呼ぶことにします。


開発版
~~~~~~

Choreonoid開発版も利用可能です。これは `git <http://git-scm.com/>`_ リポジトリとして管理されており、 `github <https://github.com/>`_ の以下のアドレスにて公開されています。

- https://github.com/s-nakaoka/choreonoid

リポジトリの利用にあたってはgitコマンドが必要です。Ubuntuでは以下のコマンドでgitをインストールできます。 ::

 sudo apt-get install git

Choreonoidのリポジトリは以下のコマンドを実行することで取得できます。 ::

 git clone https://github.com/s-nakaoka/choreonoid.git

これによってリポジトリを格納した "choreonoid" というディレクトリが生成されます。このディレクトリ内で ::

 git pull

などとすることにより、その時点での最新のソースコードにアップデートできます。

gitの使用方法の詳細についてはgitのマニュアルや解説記事を参照してください。


開発ツールと依存ソフトウェアのインストール
------------------------------------------

Choreonoidをソースコードからビルドするためには、以下の開発ツールが必要になります。

- C/C++標準開発ツール一式: C/C++コンパイラ、Make等の標準開発ツール一式が必要です。Ubuntuであれば "build-essential" というパッケージで一式インストールできます。C/C++コンパイラに関しては通常GCCを用いますが、Clang/LLVMも利用可能です。
- `CMake <http://www.cmake.org/>`_ :  ビルドツールです。本ツール独自の記述から、Make や Visual Studio といった標準ビルドツールのファイルを生成します。多くの環境に対応したビルド記述を効率的に行うことが可能です。

また、基本機能をビルドするにあたって以下のライブラリも必要になります。

* `Boost C++ Libraries <http://www.boost.org/>`_ : C++の便利なライブラリ集です。
* `Eigen <eigen.tuxfamily.org>`_ : 行列・ベクトル・線形代数演算のための高速・高機能なテンプレートライブラリです。
* `Qt <http://qt-project.org/>`_ : GUIツールキットを含むフレームワークライブラリです。
* `gettext <http://www.gnu.org/s/gettext/>`_ : 表示を多国語対応とするためのツール・ライブラリです。
* `libjpeg <http://libjpeg.sourceforge.net/>`_ : JPEG形式の画像ファイルを読み込むためのライブラリです。
* `libpng <http://www.libpng.org/pub/png/libpng.html>`_ : PNG形式の画像ファイルを読み込むためのライブラリです。
* `LibYAML <http://pyyaml.org/wiki/LibYAML>`_ : YAML形式テキストのパーサです。
* `GLEW <http://glew.sourceforge.net/>`_ : OpenGLの拡張機能を利用するためのライブラリです。

また、オプションの機能をビルドする際には、以下のようなソフトウェアも追加で必要となってきます。

* `Python <https://www.python.org/>`_ : プログラミング言語Pythonを用いてChoreonoidを操作するための「Pythonプラグイン」を利用する際に必要となります。通常Pythonは標準でインストールされていますが、プラグインをビルドする際に開発用のライブラリが必要となります。
* `omniORB <http://omniorb.sourceforge.net/>`_ : オープンソースのCORBA実装です。CORBAプラグインやOpenRTMプラグイン、OpenHRPプラグインを利用する際に必要です。
* `OpenRTM-aist <http://openrtm.org/>`_ : 産総研によるRTミドルウェアの実装です。OpenRTMプラグインを利用する際に必要です。
* `Open Dynamics Engine (ODE) <http://www.ode.org/>`_ : 物理計算ライブラリです。この物理計算によるシミュレーションを行うための「ODEプラグイン」を利用する際に必要です。
* `Bullet Physics Library <http://bulletphysics.org>`_ : 物理計算ライブラリです。この物理計算によるシミュレーションを行うための「Bulletプラグイン」を利用する際に必要です。
* `GStreamer <http://gstreamer.freedesktop.org/>`_ : メディアファイルを扱うためのライブラリです。音声ファイルや動画ファイルをChoreonoid上で再生するための「Mediaプラグイン」を利用する際に必要です。
* `PulseAudio <http://www.freedesktop.org/wiki/Software/PulseAudio/>`_ : 音声出力を行うためのシステムです。Ubuntuでは標準でインストールされていますが、Mediaプラグインをビルドする場合には別途開発用ライブラリが必要になります。
* `libsndfile <http://www.mega-nerd.com/libsndfile/>`_ : 音声ファイルを読み込むためのライブラリです。Mediaプラグインを利用する際に必要です。

Ubuntuの場合、"misc/script" 以下にある "install-requisites-ubuntu-x.x.sh" というスクリプトを用いることにより、以上のソフトウェアのほとんどを簡単にインストールすることができます。x.xはUbuntuのバージョンに対応します。例えば Ubuntu 16.04 であれば ::

 misc/script/install-requisites-ubuntu-16.04.sh

を実行すると、sudoのパスワードが求められるので入力してください。すると、パッケージシステム経由で、必要なパッケージが自動でインストールされます。

なお、上にあげたソフトウェアのうち、OpenRTM-aist と Bullet Physics Library についてはこのスクリプトではインストールされません。

OpenRTM-aistについては今のところUbuntuの標準パッケージにはなっていません。開発元が用意している追加リポジトリからパッケージをインストールするか、ソースコードからビルドするなどしてください。詳しくはOpenRTM-aistのドキュメントを参照ください。OpenRTMプラグインが必要なければ、インストールする必要はありません。

BulletについてはUbuntu 14.04では標準パッケージに含まれているのですが、そちらのパッケージでインストールすると必要なファイルが欠けているようでBulletプラグインをビルドできません。従って、Bulletプラグインをビルドする場合には、Bullet本体をソースコードからビルドしてインストールするようにしてください。こちらについても、Bulletプラグインが必要なければ、インストールする必要はありません。Bulletをビルドする際のCMakeの設定では **BUILD_SHARED_LIBS** と **USE_DOUBLE_PRECISION** を "ON" にしおてきます。

Qtについては、バージョン4と5のどちらも利用可能となっていますが、Ubuntuにおいてデフォルトではバージョン4を使うようになっています。バージョン5を使いたい場合は、まず以下のようにしてQt5関連のパッケージをインストールします ::

 sudo apt-get install qt5-default libqt5x11extras5-dev qt5-style-plugins

その上で、CMakeの **USE_QT5** をONにしておきます。

.. note:: Ubuntu 14.04 で Qt5 を使用するようにしたところ、フォントが化けてしまったりしてまともに動かず、修正方法もみつけられませんでした。設定にもよるとは思うのですが、Ubuntu 14.04 では Qt5 は十分サポートされていないと考えて、Qt4 を使ったほうが無難なようです。Ubuntu 16.04ではQt5で問題なく動作します。逆にQt4を使うとなぜかChoreonoid起動が遅くなってしまうようなので、Ubuntu 16.04ではQt5の使用をおすすめします。

.. note:: Qt5の場合、環境によってはフォントのサイズが適切でない場合もあるようです。例えば Ubuntu 16.04 の Ubuntu Mate デスクトップ環境で試したところ、フォントサイズがかなり大きくなってしまったことがありました。これはコントロールセンターの「外観の設定」の「フォント」タブにある「詳細」で解像度（ドット／インチ）を設定し直すことで直すことができました。	  

.. _build-ubuntu-cmake:
	  
CMake によるビルド設定
----------------------

まず、cmakeコマンドを使ってChoreonoidをビルドするために必要なMakefileを生成します。Choreonoidのソースディレクトリ上で ::

 cmake .

を実行すると、必要なライブラリをチェックしMakefileを生成します。(cmakeコマンドのあとのピリオドに注意してください。）

対象バージョンのUbuntuにおいて上述の説明通りに作業を進めていれば問題なくMakefileが生成されるはずですが、必要なライブラリが所定の場所にインストールされていなかったりすると、cmake実行の際にエラーが出ることがあります。その場合には、適切にインストールを行うか、CMakeによるビルド設定を修正することが必要になります。ビルド設定はcmakeコマンドを用いてコマンドラインから行うことも可能ですが、ccmakeコマンドを ::

 ccmake .

と実行することにより、各種設定をメニュー形式で行うことも可能です。詳しくはCMakeのマニュアルを参照してください。

Choreonoidは、上記のデフォルトではビルドされないオプション機能もいくつか備えています。それらの概要を :doc:`options` にまとめてありますので、希望する機能がある場合はCMakeの設定で有効にしてください。例えば、Open Dynamics Engine によるシミュレーション機能を使いたい場合は、 **BUILD_ODE_PLUGIN** を "ON" にしておきます。


.. note:: CMakeを実行したディレクトリを **「ビルドディレクトリ」** と呼びます。上記の例ではソースディレクトリ直下をビルドディレクトリとしていますが、一般的には他のディレクトリを作成してそこをビルドディレクトリとします。これにより、ソースファイルとビルドのための中間ファイルを分離できますし、デバッグ用・リリース用など、設定を分けて同時に扱うことも可能となります。
 例えばソースディレクトリ内に "build" ディレクトリを作成して、これをビルドディレクトリとする場合は、以下のようにします。 :: 

  mkdir build
  cd build
  cmake .. (or ccmake ..)


.. note:: 32ビット環境でGCCを使ってコンパイルする場合、SSE関連の拡張命令を有効とすることで、シミュレーションなどの実行速度がより速いバイナリを生成できます。これはCMakeの **ADDITIONAL_CXX_FLAGS_RELEASE** に以下のようなオプションを入力することで実現できます。 ::

  -mtune=core2 -march=core2 -mfpmath=sse -msse -msse2 -msse3 -mssse3 -msse4 -msse4.1 -msse4.2

 開発者の環境で試したところ、この記述を行うことによりシミュレーションの実行速度が10〜15%程度速くなりました。

 なお、64ビット環境ではデフォルトでこのような拡張命令を使うようになっており、特に設定する必要はありません。また、64ビット環境では、32ビット環境で上記の対応を行った場合よりもさらに実行速度が向上するようです。

.. _install_build-ubuntu_build:

Choreonoidのビルド
--------------------

CMakeによりMakefileの生成が成功すれば、makeコマンドでChoreonoidをビルドします。CMakeを実行したディレクトリ（ビルドディレクトリ）で ::

 make

を実行します。

マルチコアCPUであれば、"-j" オプションにより並列ビルドを行うことでビルド時間を短縮できます。例えば、 ::

 make -j4

とすると、最大で４つのビルドプロセスが同時に実行されることになります。通常論理コア数に1〜2を足した程度のプロセス数を指定することで、CPU能力を最大限に活かした並列ビルドができるのではないかと思われます。

なお、CMakeが生成したMakefileによるmakeでは、実行コマンドの詳細は表示されず、ビルド過程がすっきりとまとまった表示で出力されます。これはビルドの進行を確認する際には大変見やすくてよいのですが、GCCに与えている細かなコンパイルオプションなどは確認できません。その必要があるときには、 ::

 make VERBOSE=1

というように VERBOSE変数をオンにしてmakeを行うことで、全てのコマンド実行文の詳細を出力させることも可能です。



インストール
------------

Linuxでは、ビルドディレクトリ内に生成される実行ファイルを（インストール作業なしに）そのまま実行することが可能です。ビルドに成功すれば、ビルドディレクトリ内の"bin"というディレクトリの下に "choreonoid" という実行ファイルが生成されていますので、これを実行してください。 ::

 bin/choreonoid

ビルドに問題がなければ、Choreonoidのメインウィンドウが起動します。

このようにインストール作業なしに実行できるのは便利なのですが、一般的にはインストール作業を行なって、インストール先の実行ファイルを実行することになります。これを行うためには、ビルドディレクトリ上で ::

 make install

を実行します。すると、実行に必要なファイル一式が所定のディレクトリにインストールされます。

Linuxではデフォルトのインストール先は "/usr/local" となっています。このディレクトリへの書き込みは通常はroot権限が必要ですので、 ::

 sudo make install

とする必要があります。

インストール先は、CMakeの **CMAKE_INSTALL_PREFIX** の設定で変更することも可能です。複数のアカウントで利用する必要がなければ、ホームディレクトリのどこかをインストール先にしてもOKです。この場合、インストール時にsudoをする必要もなくなります。

なお、通常はインストール先のlibディレクトリに共有ライブラリパスが通っている必要がありますが、 **ENABLE_INSTALL_RPATH** を "ON" にしておくと、パスが通っていなくてもそのまま動かすことが可能となります。


Qtスタイルの変更による描画速度の改善
------------------------------------

Choreonoidが利用しているGUIライブラリのQtでは、ボタン等のGUI部品の外観をカスタマイズする「スタイル」機能が備わっています。そして、Ubuntuのデフォルト状態では、このQtのスタイルが、Linuxの標準GUIライブラリである "GTK+" の外観と同じになるように設定されています。実はGTK+自体も見た目をカスタマイズする機能を備えているのですが、QtのGTK+スタイルは、GTK+においてカスタマイズされた見た目もダイナミックに反映してくれます。

これは外観の統一という点で大変素晴らしい機能なのですが、GTK+の動的なスタイル設定をQtでも反映させることにはやはりコストがかかってしまうようで、このデフォルト状態ではQtのGUI部品の描画が大変遅くなってしまいます。それでも通常のアプリケーションではさほど問題にならないのですが、Choreonoidでは例えばロボットの関節角の表示や変更を行うGUI機能があり、これをロボットの動きと連動させる場合などには、多くのGUI部品をスムーズに描画することが求められます。しかしQtのスタイルがGTK+スタイルであると、このような場合に描画がスムーズでなくなってしまいます。

これを解決するため、QtのスタイルをGTK+でないスタイルに変更しておくことをお勧めします。これを行う方法はQt4とQt5で異なるのですが、以下にそれぞれの方法を示します。

Qt4の場合
~~~~~~~~~

Qt4では、以下に示す "qtconfig-qt4" というGUIツールを使うのが簡単です。（コマンドラインから "qtconfig-qt4" を実行するか、アプリケーションメニューから「Qt4設定」を実行すると、このツールが起動します。）

このツール上で、「外観」タブの「GUIスタイル」について、適当な変更を行なってください。例えば "Cleanlooks" スタイルに変更します。

.. image:: images/qtconfig-qt4-1.png

次に、「フォント」タブの「スタイル」を "Regular" に変更します。これを行わないとフォントが太字で表示されてしまいます。

.. image:: images/qtconfig-qt4-2.png

Qt スタイルを "Cleanlooks" スタイルに変更した場合、Choreonoid のツールチップが正常に表示されません。
これを修正するために、「外観」タブの「パレットの調整」から「ツールチップのテキスト」を選択してフォントの色を黒色に変更します。
これでツールチップが正常に表示されるようになります。

.. image:: images/qtconfig-qt4-3.png

最後に、メニューの「ファイル」-「保存」を実行すると、この設定が反映されます。
   
Qt5の場合
~~~~~~~~~

Qt5では上記のQt4の設定ツールのようなものは利用できなくなってしまったようです。そこで環境変数"QT_STYLE_OVERRIDE"を使ってスタイルを変更することにします。 ::

 export QT_STYLE_OVERRIDE=スタイル名

などとしてこの変数にスタイル名を設定します。

スタイルとしてはまずFusion, Windows, GTK+が利用可能なようです。Ubuntuでは恐らくGTK+がデフォルトになっていて、この場合Gtk+と同じ外観になるのですが、これは上述のように動作が遅くなってしまいます。Ubuntu 16.04では qt5-sytle-plugins というパッケージをインストールすることで他にCleanlooks, Motif, Plastiqueというスタイルも利用可能になります。この中でおすすめはCleanlooksです。

環境変数によるスタイルの設定を行った後にQtのアプリケーションを起動すると、そのスタイルが使われるようになります。例えば ::

 export QT_SYTLE_OVERRIDE=Cleanlooks

という記述を .profile ファイルに記述しておけば、OS起動の度に設定しなくても、このスタイルが使われるようになります。

