ROS系列-官方catkin創建工程

原文地址：http://wiki.ros.org/ROS/Tutorials

爲catkin創建一個工作空間

這個教程假設你已經裝好了catkin，並且初始化好了環境變量。如果你是通過apt-get來裝ROS inidgo，下面的命令是source的命令

$ source /opt/ros/indigo/setup.bash

創建一個catkin工作空間：

$ mkdir -p ~/catkin_ws/src
$ cd ~/catkin_ws/src
$ catkin_init_workspace

即使這個工作空間是空的（沒有任何包在src這個目錄下，只有一個CMakeLists.txt）你仍然可以“編譯”這個工作空間：

$ cd ~/catkin_ws/
$ catkin_make

catkin_make 這個命令是個很方便的工具用來操作catkin工作空間，如果你查看點錢目錄下的文件夾，你會看到‘build’和‘devel’這兩個文件夾。在devel文件夾裏，你可以看到有幾個setup.*sh文件，通過source命令激活這些文件中任何一個文件都會將這個工作空間覆蓋到最上層的環境中：

$ source devel/setup.bash

爲了確認工作空間被正確的通過sh腳本覆蓋，先確認ROS_PACKAGE_PATH的環境變量包含在你自己的目錄中，如下：

$ echo $ROS_PACKAGE_PATH
/home/youruser/catkin_ws/src:/opt/ros/kinetic/share

接下來你需要繼續學習怎麼使用這個工作空間，進行下一個教程的學習：創建一個ROS工作空間。

catkin包室友什麼組成？
對於一個安裝包catkin包需要考慮並滿足到以下幾點要求：

The package must contain a catkin compliant package.xml file.必須包含一個兼容的package.xml文件
That package.xml file provides meta information about the package.這個文件提供了包的一些元信息
The package must contain a CMakeLists.txt which uses catkin. If it is a catkin metapackage it must have the relevant boilerplate CMakeLists.txt file.必須包含一個使用catkin的CMakeLists.txt文件或者模板。
There can be no more than one package in each folder.每個文件夾不猛存在超過一個安裝包
This means no nested packages nor multiple packages sharing the same directory.多個包不能共享一個文件夾
The simplest possible package might have a structure which looks like this:一個簡單的包的目錄樹如下：  

my_package/
  CMakeLists.txt
  package.xml

Packages in a catkin Workspace

建議使用catkin工作空間來操作catkin 安裝包相關事宜，當然你也可以單獨編譯catkin 安裝包，幾個比較小的工作空間如下所示：

workspace_folder/        -- WORKSPACE
  src/                   -- SOURCE SPACE
    CMakeLists.txt       -- 'Toplevel' CMake file, provided by catkin
    package_1/
      CMakeLists.txt     -- CMakeLists.txt file for package_1
      package.xml        -- Package manifest for package_1
    ...
    package_n/
      CMakeLists.txt     -- CMakeLists.txt file for package_n
      package.xml        -- Package manifest for package_n

在繼續這個教程之前，先按照前面一個教程的方法創建一個空的工作空間。

Creating a catkin Package

加下來會演示如何使用catkin——create_pkg這個腳本去創建一個新的catkin安裝包，還有你接下去要如何做。

首先先把環境切換到catkin工作空間的源碼目錄下：

$ cd ~/catkin_ws/src

現在使用catkin_create_pkg腳本去創建一個新的安裝包”beginner_tutorials”,這個包依賴於 std_msgs, roscpp, and rospy:

$ catkin_create_pkg beginner_tutorials std_msgs rospy roscpp

這個將會創建一個 beginner_tutorials文件夾，包含了package.xml and a CMakeLists.txt.

catkin_create_pkg會要求你提供一個安裝包的名字還有一些可選的依賴包：

This is an example, do not try to run this

catkin_create_pkg [depend1] [depend2] [depend3]

catkin_create_pkg也有一些深層的功能，都在catkin/commands/catkin_create_pkg中有所描述。

編譯一個catkin工作空間，然後source者安裝文件腳本：

$ cd ~/catkin_ws
$ catkin_make

在工作空間被編譯之後，它會創建一個與/opt/ros/$ROSDISTRO_NAME目錄中相似的的目錄樹結構。

把這個工作空間添加到你自己的ROS環境中的話，你需要source自動生成的腳本文件：

$ . ~/catkin_ws/devel/setup.bash

安裝包的依賴:
早些時間在使用catkin_create_pkg的時候，需要提供少部分的依賴安裝包這些依賴包現在可以用用rospack這個工具來review。

$ rospack depends1 beginner_tutorials 
std_msgs
rospy
roscpp

就像你所看到的，rospack列出了同樣的依賴包，跟之前運行catkin_create_pkg時加的參數是一樣的。這些依賴關係被保存在package.xml文件中：

$ roscd beginner_tutorials
$ cat package.xml
<package>
...
  <buildtool_depend>catkin</buildtool_depend>
  <build_depend>roscpp</build_depend>
  <build_depend>rospy</build_depend>
  <build_depend>std_msgs</build_depend>
...
</package>

間接依賴：
在許多情況下，一個依賴通常還會有自己的依賴，也就是間接依賴，比如rospy就有其他依賴：

$ rospack depends1 rospy
genpy
rosgraph
rosgraph_msgs
roslib
std_msgs

一個包可以有相當多的間接依賴關，幸運的是rospack可以遞歸地確定所有嵌套依賴項
.

$ rospack depends beginner_tutorials
cpp_common
rostime
roscpp_traits
roscpp_serialization
genmsg
genpy
message_runtime
rosconsole
std_msgs
rosgraph_msgs
xmlrpcpp
roscpp
rosgraph
catkin
rospack
roslib
rospy

客製化自己的package:
這個教程會詳細地分析每一個靠catkin_create_pkg生成的文件，還有這些文件的每一部分和如何去客製化這些package。

客製化 package.xml
生成的package.xml 應該在你的新的package裏面. 現在逐一分析一下心得package.xml文件：

description tag

首先是 description tag:

<description>The beginner_tutorials package</description>

可以改變描述,但是按照慣例第一句話應該簡短，畢竟是要覆蓋整個package範圍。如果很難用一個句子描述，可能需要分開。

maintainer tags（required）

接下來是 maintainer tag:

<!-- One maintainer tag required, multiple allowed, one person per tag --> 
  <!-- Example:  -->
  <!-- <maintainer email="[email protected]">Jane Doe</maintainer> -->
  <maintainer email="[email protected]">user</maintainer>

這是對於package.xml是一個重要的tag。因爲它可以讓別人知道關於這個package可以聯繫誰。至少一個維護者是必需的,當然可以有很多。維護者的名稱進入主體的標籤,但也有一個電子郵件屬性,應填寫:

<maintainer email="[email protected]">Your Name</maintainer>

license tags

接下來是license tag（required）:

<!-- One license tag required, multiple allowed, one license per tag -->
  <!-- Commonly used license strings: -->
  <!--   BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, LGPLv3 -->
  <license>TODO</license>

你應該選擇一個許可證然後填在這裏。一些常見的開放源碼許可BSD,麻省理工學院,提升軟件許可證,GPLv2,GPLv3 LGPLv2.1,LGPLv3。你可以讀到一些開放源代碼項目。在本教程中我們將使用BSD許可,因爲其餘的核心ROS組件也使用了。

8   <license>BSD</license>

dependencies tags

下一組標籤描述您的軟件包的依賴關係。依賴關係分成build_depend、buildtool_depend run_depend test_depend。我們通過std_msgs、roscpp rospy catkin_create_pkg作爲參數,所以會像這樣的依賴關係:

<!-- The *_depend tags are used to specify dependencies -->
  <!-- Dependencies can be catkin packages or system dependencies -->
  <!-- Examples: -->
  <!-- Use build_depend for packages you need at compile time: -->
  <!--   <build_depend>genmsg</build_depend> -->
  <!-- Use buildtool_depend for build tool packages: -->
  <!--   <buildtool_depend>catkin</buildtool_depend> -->
  <!-- Use run_depend for packages you need at runtime: -->
  <!--   <run_depend>python-yaml</run_depend> -->
  <!-- Use test_depend for packages you need only for testing: -->
  <!--   <test_depend>gtest</test_depend> -->
  <buildtool_depend>catkin</buildtool_depend>
  <build_depend>roscpp</build_depend>
  <build_depend>rospy</build_depend>
  <build_depend>std_msgs</build_depend>

我們所有的依賴關係添加了作爲build_depend對我們來說,除了默認buildtool_depend。在這種情況下,我們希望我們所有的指定依賴項可以在構建和運行時,我們將添加一個run_depend標記他們每個人:

<buildtool_depend>catkin</buildtool_depend>

  <build_depend>roscpp</build_depend>
  <build_depend>rospy</build_depend>
  <build_depend>std_msgs</build_depend>

  <run_depend>roscpp</run_depend>
  <run_depend>rospy</run_depend>
  <run_depend>std_msgs</run_depend>

package.xml

package.xml的最後沒有任何comments和tags， 相當的簡潔：

<?xml version="1.0"?>
<package>
  <name>beginner_tutorials</name>
  <version>0.1.0</version>
  <description>The beginner_tutorials package</description>

  <maintainer email="[email protected]">Your Name</maintainer>
  <license>BSD</license>
  <url type="website">http://wiki.ros.org/beginner_tutorials</url>
  <author email="[email protected]">Jane Doe</author>

  <buildtool_depend>catkin</buildtool_depend>

  <build_depend>roscpp</build_depend>
  <build_depend>rospy</build_depend>
  <build_depend>std_msgs</build_depend>

  <run_depend>roscpp</run_depend>
  <run_depend>rospy</run_depend>
  <run_depend>std_msgs</run_depend>

</package>

客製化CMakeLists.txt：
package.xml包含了元信息，它包含元數據信息,是根據你的包量身定製的,你可以準備繼續後面的教程。CMakeLists。txt文件由catkin_create_pkg命令創建，關於這部分內容會在下面的教程說明。

Building Packages

只要你的package所有的依賴包都安裝好了，接下來就可以編譯這個package了。

在接下去的操作前，記得先source環境變量，在ubuntu中可能是這樣source的：

$ source /opt/ros/%YOUR_ROS_DISTRO%/setup.bash
$ source /opt/ros/kinetic/setup.bash             (For Kinetic for instance)

使用 catkin_make
catkin_make 是一個命令工具用來簡化catkin的標準工作流程的，你可以想象一下catkin_make工具可以調用cmake和make來完成編譯。
用法:

In a catkin workspace

$ catkin_make [make_targets] [-DCMAKE_VARIABLES=...]

For people who are unfamiliar with the standard CMake workflow, it breaks down as follows:
如果有些人對標準的cmake編譯流程不太熟悉，可以把上述命令拆成下面的步驟執行：

Note: If you run the below commands it will not work, as this is just an example of how CMake generally works.

In a CMake project

$ mkdir build
$ cd build
$ cmake ..
$ make
$ make install  # (optionally)

這個操作流程適用於每個CMake項目，而catkin可以在一個工作空間編譯多個項目，如下操作：

In a catkin workspace

$ catkin_make
$ catkin_make install  # (optionally)

上面的命令將會編譯任何catkin項目，只要是能在src文件夾中找到。在此之前REP128設定的建議。如果你的源代碼是在不同的地方,比如在my_src文件夾下，那麼catkin_make命令可以這樣用:

Note: If you run the below commands it will not work, as the directory my_src does not exist.

In a catkin workspace

$ catkin_make --source my_src
$ catkin_make install --source my_src  # (optionally)

For more advanced uses of catkin_make see the documentation: catkin/commands/catkin_make

編譯Package

看到這頁想編譯你自己代碼的讀者，可以事先學習一下C++/Python語言，因爲你將會修改CMakeList.txt配置問題。
到這邊你應該有一個catkin的工作空間和一個新的catkin package—–beginner_tutorials。進入catkin工作空間，你可以看到src文件夾：

$ cd ~/catkin_ws/
$ ls src

beginner_tutorials/  CMakeLists.txt@

你在src文件夾下可以看到之前用catkin_create_pkg命令創建的額文件夾–beginner_tutorials，我們現在可以用catkin_make命令來編譯這個package：

$ catkin_make

這個命令的log會像是cmake和make的過程，如下所示：

Base path: /home/user/catkin_ws
Source space: /home/user/catkin_ws/src
Build space: /home/user/catkin_ws/build
Devel space: /home/user/catkin_ws/devel
Install space: /home/user/catkin_ws/install
####
#### Running command: "cmake /home/user/catkin_ws/src
-DCATKIN_DEVEL_PREFIX=/home/user/catkin_ws/devel
-DCMAKE_INSTALL_PREFIX=/home/user/catkin_ws/install" in "/home/user/catkin_ws/build"
####
-- The C compiler identification is GNU 4.2.1
-- The CXX compiler identification is Clang 4.0.0
-- Checking whether C compiler has -isysroot
-- Checking whether C compiler has -isysroot - yes
-- Checking whether C compiler supports OSX deployment target flag
-- Checking whether C compiler supports OSX deployment target flag - yes
-- Check for working C compiler: /usr/bin/gcc
-- Check for working C compiler: /usr/bin/gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Using CATKIN_DEVEL_PREFIX: /tmp/catkin_ws/devel
-- Using CMAKE_PREFIX_PATH: /opt/ros/kinetic
-- This workspace overlays: /opt/ros/kinetic
-- Found PythonInterp: /usr/bin/python (found version "2.7.1") 
-- Found PY_em: /usr/lib/python2.7/dist-packages/em.pyc
-- Found gtest: gtests will be built
-- catkin 0.5.51
-- BUILD_SHARED_LIBS is on
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- ~~  traversing packages in topological order:
-- ~~  - beginner_tutorials
-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- +++ add_subdirectory(beginner_tutorials)
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/catkin_ws/build
####
#### Running command: "make -j4" in "/home/user/catkin_ws/build"
####

注意,catkin_make最開始顯示是每個space所使用的的路徑。REP128和文檔中描述的space：wiki:catkin/workspace。比較重要的需要注意的是,由於這些默認值，幾個文件夾已經被創建在你的工作區。用ls看一看:

$ ls
build
devel
src

build文件夾是build空間的默認位置，另外也是cmake和make配置並編譯你的package的所在目錄。devel文件夾是devel空間的默認路徑，也就是在你安裝你的package之前你的執行文件和庫文件的所在的位置。