Những gì tạo nên một gói catkin ?

Để tạo thành một gói được xem là gói catkin phải thỏa mãn những yêu cầu sau:

• Gói phải chứa một tập tin catkin compliant package.xml .

  • Tập tin package.xml cung cấp thông tin (meta information) về gói đó.

• Gói phải chứa tập tin CMakeLists.txt which uses catkin. Nếu nó là một gói lớn catkin metapackage nó phải chứa những bản mẫu CMakeLists.txt liên quan.

• Trong mỗi thư mục không có hơn một gói.
  • Điều này có nghĩa không có gói chứa những gói khác hoặc nhiều gói trong cùng một thư mục.

Một gói đơn giản nhất sẽ có cấu trúc giống như sau:

• my_package/
    CMakeLists.txt
    package.xml

Gói trong một không gian làm việc catkin (hay catkin Workspace)

Phương pháp khuyên dùng làm việc với gói catkin là dùng một không gian làm việc catkin workspace, nhưng cũng có thể xây dựng một gói catkin độc lập. Một không gian làm việc thường giống như sau:

• workspace_folder/        -- WORKSPACE không gian làm việc
    src/                   -- SOURCE SPACE không gian chứa mã nguồn
      CMakeLists.txt       -- 'Toplevel' tập tin CMake, cung cấp bởi catkin
      package_1/
        CMakeLists.txt     -- tập tin CMakeLists.txt cho package_1
        package.xml        -- gói Package manifest cho package_1
      ...
      package_n/
        CMakeLists.txt     -- tập tin CMakeLists.txt cho package_n
        package.xml        -- gói manifest cho package_n

Trước khi tiếp tục với hướng dẫn tạo ra một catkin workspace rỗng theo hướng dẫn sauCreating a workspace for catkin.

Tạo một gói catkin (hay catkin Package)

Hướng dẫn sẽ minh họa làm cách nào dùng catkin_create_pkg script để tạo ra một gói catkin, và những gì bạn có thể làm sau khi gói đã tạo ra.

Đầu tiên đi đến thư mục mã nguồn bạn đã tao ra theo hướng dẫn trước Creating a Workspace for catkin tutorial:

# Thư mục bạn đã tạo ra trong mục Tạo một không gian làm việc
$ cd ~/catkin_ws/src

Bây giờ dùng catkin_create_pkg script để tạo ra một gói mới gọi là 'beginner_tutorials' phụ thuộc vào các gói std_msgs, roscpp, và rospy:

$ catkin_create_pkg beginner_tutorials std_msgs rospy roscpp

Nó sẽ tạo ra một thư mục beginner_tutorials trong đó chứa tập tin package.xml và CMakeLists.txt, với những thông tin mà bạn đã đưa khi dùng lệnh catkin_create_pkg.

catkin_create_pkg yêu cầu bạn đưa ra tên gói 'package_name' và lựa chọn danh sách những gói sẽ phụ thuộc :

# Đây là một ví dụ, không thử chạy dòng này
# catkin_create_pkg <package_name> [depend1] [depend2] [depend3]

catkin_create_pkg cũng cung cấp nhiều chức năng tiện ích khác được mô tả trong catkin/commands/catkin_create_pkg.

Xây dựng không gian catkin và thiết đặt mã nguồn

Bây giờ bạn cần tạo gói trong không gian làm việc catkin:

$ cd ~/catkin_ws
$ catkin_make

Sau khi workspace xây dựng xong nó sẽ có cấu trúc giống trong thư mục con devel devel như bạn thường thấy /opt/ros/$ROSDISTRO_NAME.

Để thêm workspace vào môi trường ROS bạn cần thiết đặt nguồn bởi tập tin cài đặt đã tạo ra:

$ . ~/catkin_ws/devel/setup.bash

Sự phụ thuộc của gói (package dependencies)

Sự phụ thuộc First-order

Khi dùng catkin_create_pkg ở trên, một vài gói phụ thuộc được cung cấp. Sự phụ thuộc đầu tiên (first-order) có thể được xem với công cụ rospack.

$ rospack depends1 beginner_tutorials

• std_msgs
  rospy
  roscpp

Như bạn thấy, rospack liệt kê danh sách phụ thuộc giống như khi ta tạo ra gói dùng catkin_create_pkg với các tham số phụ thuộc . Sự phụ thuộc của một gói sẽ lưu trữ trong tập tin 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>

Phụ thuộc gián tiếp (Indirect dependencies)

Trong nhiều trường hợp, một sự phụ thuộc sẽ những sự phụ thuộc của riêng nó. Một ví dụ, rospy có những sự phụ thuộc khác.

$ rospack depends1 rospy

• genpy
  rosgraph
  rosgraph_msgs
  roslib
  std_msgs

Một gói có thể có khá nhiều sự phụ thuộc gián tiếp. May mắn thay, rospack có thể duyệt hết sự phụ thuộc gián tiếp này.

$ 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

Tùy chỉnh gói của bạn

Phần này sẽ xem xét từng tập tin được sinh ra bởi catkin_create_pkg và mô tả , theo từng dòng , mỗi thành phần của những tập tin và làm thế nào để tùy chỉnh chúng cho gói bạn cần.

Tùy chỉnh tập tin package.xml

Tập tin tạo ra package.xml phải ở trong gói mới tạo ra. Bây giờ tìm hiểu package.xml các thành phần quan trọng.

mô tả nhãn (tag)

Đầu tiên cập nhật nhãn mô tả:

   5   <description>The beginner_tutorials package</description>

Thay đổi mô tả sang bất cứ điều gì bạn thích, nhưng theo quy ước, câu đầu tiên nên ngắn gọn trong khi bao quát phạm vi của gói. Nếu khó có thể mô tả gói trong một câu thì có thể cần phải chia nhỏ.

nhãn quản trị

Tiếp theo là thẻ quản trị viên:

   7   <!-- One maintainer tag required, multiple allowed, one person per tag --> 
   8   <!-- Example:  -->
   9   <!-- <maintainer email="jane.doe@example.com">Jane Doe</maintainer> -->
  10   <maintainer email="user@todo.todo">user</maintainer>

Đây là thẻ bắt buộc và quan trọng cho package.xml vì nó cho phép những người khác biết ai để liên lạc. Ít nhất một người bảo trì là bắt buộc, nhưng bạn có thể có nhiều nếu bạn thích. Tên của người bảo trì đặt trong phần thân của thẻ, nhưng cũng cần có một email:

   7   <maintainer email="you@yourdomain.tld">Your Name</maintainer>

nhãn giấy phép

Tiếp theo là thẻ giấy phép, cũng được yêu cầu:

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

Bạn nên chọn một giấy phép và điền nó vào đây. Một số giấy phép mã nguồn mở phổ biến là BSD, MIT, Boost Giấy phép phần mềm, GPLv2, GPLv3, LGPLv2.1 và LGPLv3. Bạn có thể đọc về một số điều này tại Sáng kiến Nguồn mở Source Initiative. Đối với hướng dẫn này, chúng ta sẽ sử dụng giấy phép BSD vì các thành phần ROS cốt lõi sử dụng nó:

   8   <license>BSD</license>

nhãn phụ thuộc

Tập tiếp theo của các thẻ mô tả các phụ thuộc của gói của bạn. Các phụ thuộc được chia thành build_depend, buildtool_depend, run_depend, test_depend. Để có giải thích chi tiết hơn về các thẻ này, hãy xem tài liệu về Catkin Dependencies. Vì chúng ta đã đưa vào std_msgs, roscpp và rospy như các đối số cho catkin_create_pkg, các phụ thuộc sẽ giống như sau:

  27   <!-- The *_depend tags are used to specify dependencies -->
  28   <!-- Dependencies can be catkin packages or system dependencies -->
  29   <!-- Examples: -->
  30   <!-- Use build_depend for packages you need at compile time: -->
  31   <!--   <build_depend>genmsg</build_depend> -->
  32   <!-- Use buildtool_depend for build tool packages: -->
  33   <!--   <buildtool_depend>catkin</buildtool_depend> -->
  34   <!-- Use exec_depend for packages you need at runtime: -->
  35   <!--   <exec_depend>python-yaml</exec_depend> -->
  36   <!-- Use test_depend for packages you need only for testing: -->
  37   <!--   <test_depend>gtest</test_depend> -->
  38   <buildtool_depend>catkin</buildtool_depend>
  39   <build_depend>roscpp</build_depend>
  40   <build_depend>rospy</build_depend>
  41   <build_depend>std_msgs</build_depend>

Tất cả các phụ thuộc được liệt kê đã được thêm như là build_depend , ngoài buildtool_depend mặc định trên catkin. Trong trường hợp này, chúng ta muốn tất cả các phụ thuộc được chỉ định có sẵn tại thời điểm tạo và thực thi, vì vậy chúng ta sẽ thêm một thẻ run_depend cho mỗi một trong số chúng:

  12   <buildtool_depend>catkin</buildtool_depend>
  13 
  14   <build_depend>roscpp</build_depend>
  15   <build_depend>rospy</build_depend>
  16   <build_depend>std_msgs</build_depend>
  17 
  18   <exec_depend>roscpp</exec_depend>
  19   <exec_depend>rospy</exec_depend>
  20   <exec_depend>std_msgs</exec_depend>

Final package.xml

Như bạn thấy final package.xml, nếu không có chú thích và không dùng thẻ, sẽ trở nên súc tích:

   1 <?xml version="1.0"?>
   2 <package format="2">
   3   <name>beginner_tutorials</name>
   4   <version>0.1.0</version>
   5   <description>The beginner_tutorials package</description>
   6 
   7   <maintainer email="you@yourdomain.tld">Your Name</maintainer>
   8   <license>BSD</license>
   9   <url type="website">http://wiki.ros.org/beginner_tutorials</url>
  10   <author email="you@yourdomain.tld">Jane Doe</author>
  11 
  12   <buildtool_depend>catkin</buildtool_depend>
  13 
  14   <build_depend>roscpp</build_depend>
  15   <build_depend>rospy</build_depend>
  16   <build_depend>std_msgs</build_depend>
  17 
  18   <exec_depend>roscpp</exec_depend>
  19   <exec_depend>rospy</exec_depend>
  20   <exec_depend>std_msgs</exec_depend>
  21 
  22 </package>

Tùy chỉnh tập tin CMakeLists.txt

Bây giờ gói tinpackage.xml có chứa thông tin meta đã được chỉnh sửa cho gói của bạn, bạn đã sẵn sàng tiếp tục theo hướng dẫn. Tệp CMakeLists.txt được tạo bởi catkin_create_pkg sẽ được đề cập đến trong các hướng dẫn sau về xây dựng mã ROS.