Note: This tutorial assumes that you have completed the previous tutorials: Creating a ROS Package.
(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

workspace で catkin パッケージをビルドして使う

Description: catkin_make を使ったビルドの方法と catkin workspaceでのソースからのインストールの方法について学びます

Keywords: catkin workspace

Tutorial Level: BEGINNER

Next Tutorial: Overlaying catkin packages using workspaces

ワークスペース内パッケージのインストール

本チュートリアルでは,まず catkin_make の動作の基礎について解説します.その後,catkin_make を使わずにcatkinワークスペースをビルドする方法に関するチュートリアルを読み進めることもできます.これはcatkin_make の動作を理解する上でとても有効です.

catkin_make を使う場合

catkin_make を用いたビルドはとても単純です.ただし,ワークスペースの最上位のディレクトリで実行する必要があります.典型的なフローは次の通りです:

$ cd ~/catkin_ws/src/beginner_tutorials/src

# Add/Edit source files

$ cd ~/catkin_ws/src/beginner_tutorials

# Update CMakeFiles.txt to reflect any changes to your sources

$ cd ~/catkin_ws

$ catkin_make -DCMAKE_BUILD_TYPE=Release

Note: You might want to select a different CMake build type (e.g. RelWithDebInfo or Debug, see http://cmake.org/cmake/help/v2.8.12/cmake.html#variable:CMAKE_BUILD_TYPE).

この操作により,source space (~/catkin_ws/src) 内の全パッケージを build space (~/catkin_ws/build) にビルドします. 全てのソースファイル(python ライブラリ, スクリプト, その他静的なファイル) は source space に残ります. 一方, 生成されるファイル(ライブラリ, 実行ファイル, 自動生成コード)は devel space に格納されます.また,devel space には,setup.*sh ファイルが生成されます.本ファイルは source されることで devel space にプレフィックスされます.

catkin_make に標準的な引数を渡せるようにしたい場合,例えば下記のように install ターゲットを make します:

$ cd ~/catkin_ws
$ catkin_make install

これは 'cd ~/catkin_ws/build && make install' を呼ぶことに相当します.このコマンドを実行すれば,自身のsetup.*sh ファイルが格納された install space (~/catkin_ws/install) が生成されるはずです.このファイルを source することで,実行PC上の環境が上書きされます.

なお,install space か devel spaceのどちらか一方を使うべきで,同時に両者を使うべきではありません.devel space は開発者自身で作成したワークスペース内のパッケージを開発する上で有効です.毎回 install を起動する必要がないからです. Python やテスト実行で開発する上で特に便利です.

install space は自身で開発したパッケージを配布したり,外部から取得したパッケージをインストールする際に有効となります.例えば,'install' が有効なソースを,catkin_make に対してCMake 引数 '-DCMAKE_INSTALL_PREFIX=/opt/ros/groovy' を渡してインストールしてROSをビルドする場合,次のようなコマンドとなります:

# This is an example
$ cd ~/catkin_ws
$ catkin_make install -DCMAKE_INSTALL_PREFIX=/opt/ros/groovy  # might need sudo

もし事前にワークスペースをコンパイル済みで新規にパッケージを追加する場合,catkin に対してそのパッケージをコンパイル済みのバイナリに追加するように命令するコマンドは次のようになります:

$ catkin_make --force-cmake

コンパイル実行時のコマンドラインを見たい場合は以下のオプションを catkin_make 実行時に追加します:

$ catkin_make -DCMAKE_VERBOSE_MAKEFILE=ON

catkin_make の更に詳細な動作については,次のチュートリアルを参照してください: Overlaying catkin packages using workspaces.

catkin_make を使わない場合

ここまで解説で,catkin_make を使ってワークスペースをビルドできるようになりました.ここからは,catkin_makeを使わずにビルドする方法について深堀りしてきます.

ビルドの準備

はじめに, build space 用のフォルダを作成する必要があります.通常,<workspace>/build となります.このフォルダは,catkinやCMakeによって生成されるテンポラリファイルが格納される場所となります.下記コマンドで build space を作成します:

$ mkdir ~/catkin_ws/build
$ cd ~/catkin_ws/build

There is only one build space directory per workspace. CMake users may find this unusual, we will have a single build folder for all our catkin projects. This is a key feature of catkin, it will work as if it were one large CMake project.

このフォルダはビルド用スクリプトを呼び出すフォルダとなるので,大切な設定項目です.複数の構成が必要となる場合にbuild とは異なる名前のフォルダに設定することもできますが,'build' はデフォルトとしてよい例ですし,他の名前を付ける場合でも接頭辞として 'build_' を付与することが慣例的にも良いとされています.

パッケージの設定をする

次に,ビルドシステムの設定を行います.ここは,開発システムおよび開発環境に対応したビルドのためのパッケージの設定できるように,CMake(つまりcatkin)を呼び出すステップです. source space にファイルが追加されたり削除されたり,パッケージ内のビルドファイルを変更したり,ビルドシステムの設定を変えるたびに,このステップが必要となります.

ワークスペースのセットアップが完了していれば,CMake を行うことでcatkin パッケージの設定とビルドスクリプトを生成できます.次のように build space に移動してCMake を実行します:

$ cd ~/catkin_ws/build
$ cmake ../src

これによって CMake の実行結果が何行か出力されますが,それ以上のことはしません.source space 内にcatkin パッケージが存在しないためです.

このステップでは,install space 接頭辞を初めととするCMakeやcatkin の設定項目の設定もできます.例えば,CMake 変数である CMAKE_INSTALL_PREFIX を用いれば任意のinstall space 接頭辞を設定できます:

$ cd ~/catkin_ws/build
$ cmake ../src -DCMAKE_INSTALL_PREFIX=../install -DCATKIN_DEVEL_PREFIX=../devel`

この例では,install の生成物をデフォルトの /usr/local ではなく,~/catkin_ws/install ディレクトリに生成します.

ポイント:下'記のように CMake オプションを追加することで,ワークスペース内の devel space ディレクトリを設定できます: cmake ../src -DCATKIN_DEVEL_PREFIX=../devel

ポイント:下記のように CMake オプションを追加することで,ワークスペース内の install ディレクトリを設定できます' : cmake ../src -DCMAKE_INSTALL_PREFIX=../install

パッケージをビルドする

前のステップでは,ワークスペース内の source space にある catkin パッケージの設定を行い,ビルドスクリプトを build space ディレクトリに生成しました.build space から biuld スクリプトを呼び出し,catkin パッケージ をビルドできることを学びました.デフォルトでは,CMake によって Make スクリプトが生成されます.その後 build space ディレクトリに移動して meke コマンドによって catkin パッケージを ビルドします:

$ cd ~/catkin_ws/build
$ make

catkin パッケージのビルドによって作成されるファイルは devel space に格納されます.devel space は FHS-compliant install space の構成をミラーリングします.これによって devel space にいくつかファイルが追加されます:

catkin_ws/               -- WORKSPACE
  src/                   -- SOURCE SPACE
    ...
  build/                 -- BUILD SPACE
  devel/                 -- DEVEL SPACE
    setup.bash          \
    setup.sh            |-- Environment setup files
    setup.zsh           /
    etc/                 -- Generated configuration files
    include/             -- Generated header files
    lib/                 -- Generated libraries and other artifacts
      package_1/
        bin/
        etc/
        include/
        lib/
        share/
        ...
      package_n/
        bin/
        etc/
        include/
        lib/
        share/
    share/               -- Generated architecture independent artifacts
    ...

これらのファイルのほとんどは手入力で編集されるべきではありません.CMakeCache.txt だけは例外で,手動で変えたり, ccmake (cmake-curses-gui) や cmake-gui (Ubuntu の apt-get でインストール可能) といった標準的な cmake ツールで編集できます.

devel space はビルドステップの生成物だけが格納されます.source space 内のどのファイル(ヘッダーやリソースなど)も何種類かのリダイレクトを経て提供されます.Python を例にとると,Python のモジュールを source space で編集した後,再度 CMake や make をせずに devel space で編集結果のテストが可能です.

CMake users may find this unusual, since a more conventional workflow requires installation before usage. This is a key feature of catkin allowing quicker development cycles. It is up to you whether you want to use this feature.

パッケージをインストールする

ワークスペースでcatkin パッケージをビルドしたあとは,そのパッケージをcatkin/workspaces#Development_.28Devel.29_Space で直接使うか,インストールすることができます.catkin パッケージのインストールはCMake によって生成される特別なinstall 対象を呼び出すことによって可能です.

本チュートリアルの Configuring Packages セクションで,cmakeのための CMAKE_INSTALL_PREFIX のパスを通すことでinstall 接頭辞を変えられることについて説明しました.このinstall 接頭辞はintall ステップで生成されるファイルをどこに格納するかを決めるものです.この場所は install space として参照されます.それでは,この install space をワークスペース内の任意の場所に設定して,install ステップを実行します:

$ cd ~/catkin_ws/build
$ make install

権限の不足でmake install が失敗する場合は, -DCMAKE_INSTALL_PREFIX オプションをつけてcmake をしていない可能性が高いです.この場合, make install の前に再度cmake を実行しなおしてください.

まだsrc フォルダ内に何もパッケージがないので何のcatkin パッケージもインストールされませんが,ワークスペース内にいくつかファイルが生成されます.

make install中は,ユーザが設定したCMAKE_INSTALL_PREFIXにファイルがコピーされます.大抵の場合は'bin', 'lib', 'share', 等のフォルダが生成されます.catkin 用の setup.*sh もここに生成されます. これらの環境設定ファイル は、シェルからsourceする際に使われる便利なファイルです.パッケージ内のinstall spaceやdevel space をインクルードして環境を拡張するのに使えます.

setup.*sh を利用するタイミングとして,実行形式のファイルが含まれるパッケージでmakemake installをしたあとに,その実行形式ファイルを環境変数のPATHに追加したい時が挙げられます.

catkin_ws/               -- WORKSPACE
  src/                   -- SOURCE SPACE
    ...
  build/                 -- BUILD SPACE
  devel/                 -- DEVEL SPACE
    setup.sh
    setup.bash
    setup.zsh
    ...
  install/               -- INSTALL SPACE
    setup.sh
    setup.bash
    setup.zsh
    ...

上記のように,install space はdevel space と同様のディレクトリ構成をとります.

catkin ではないソフトウェアの場合,自分で環境変数PATHを拡張するか、PATHが既に通っているディレクトリ(例えば /usr)をパッケージのインストール先に指定する必要があります. 一方catkin を使う場合なら,次に示すように環境設定ファイルを source するだけで簡単に環境拡張ができます:

source ~/catkin_ws/install/setup.bash

Which files of your package get installed, static or generated, is determined by CMake commands in your CMakeLists.txt. Generally your executables are put into a 'bin' folder, your libraries in a 'lib', and so on, but the prefix for those folders is set by the CMAKE_INSTALL_PREFIX. The CMAKE_INSTALL_PREFIX defaults to '/usr/local', which is the UNIX convention when building software yourself, but it can be overridden at CMake invocation time. We strongly recommend using a different folder for developers like a folder in the workspace to allow easy uninstall and working with multiple ROS distributions. Do NOT install from source to the default location on a shared computer (like a robot) unless you are the robot administrator and are aware that there is no uninstall command. Catkin calls the space where you install things to the install space.

クリーンナップ

You can delete your buildspace and install space whenever you want, and re-create them using the steps above. The main purpose of this is to 'uninstall' packages you have built or make install'ed previously.

Next you should go ahead and learn how to Overlaying catkin packages using workspaces.

次は、Overlaying catkin packages using workspacesに進みましょう。

Wiki: ja/catkin/Tutorials/using_a_workspace (last edited 2018-02-28 14:40:12 by DaisukeSato)