Do que é feito um pacote catkin?

Para que um pacote seja considerado um pacote catkin, ele deve responder à alguns requerimentos:

• O pacote deve conter um arquivo package.xml

  • O arquivo package.xml provê meta-informações sobre o pacote

• O pacote deve conter uma CMakeLists.txt que use catkin.

  • Catkin metapackages têm que ter um arquivo CMakeLists.txt de "boilerplate".

• Não pode haver mais de um pacote em cada diretório
  • Isso significa que múltiplos pacotes não podem ficar no mesmo diretório

O pacote mais simples possível poderia ser assim:

• my_package/
    CMakeLists.txt
    package.xml

Pacotes em um espaço de trabalho catkin

O método recomendado para trabalhar com pacotes catkin é usando um espaço de trabalho catkin, mas você também pode criar pacotes catkin por fora. Um espaço de trabalho trivial poderia ser algo do tipo:

• espaco_de_trabalho/      -- espaço de trabalho (workspace)
    src/                   -- espaço do código fonte
      CMakeLists.txt       -- arquivo CMake mais acima, provido pelo catkin
      pacote_1/
        CMakeLists.txt     -- arquivo CMake para pacote_1
        package.xml        -- manifesto para pacote_1
      ...
      pacote_n/
        CMakeLists.txt     -- arquivo CMake para pacote_n
        package.xml        -- manifesto para pacote_n

Antes de continuar com este tutorial, crie um espaço catkin vazio seguindo o tutorial sobre criar um espaço de trabalho catkin.

Criando um pacote catkin

Este tutorial vai mostrar como usar o script catkin_create_pkg para criar um novo pacote catkin, e o que você pode fazer com ele depois de ter sido criado.

Primeiro vá para o diretório de código fonte que você criou no tutorial Criando um espaço de trabalho catkin:

# Você já deveria ter criado este diretório no tutorial anterior
$ cd ~/catkin_ws/src

Agora use o script catkin_create_pkg para criar um novo pacote chamado beginner_tutorials, que depende de std_msgs, roscpp, e rospy:

$ catkin_create_pkg beginner_tutorials std_msgs rospy roscpp

Isso vai criar uma pasta beginner_tutorials que contém os arquivos package.xml e CMakeLists.txt, que já foram parcialmente preenchidos com informações que você deu ao script catkin_create_pkg.

catkin_create_pkg pede que você dê um `nome_do_pacote' e opcionalmente uma lista de dependências para o pacote:

# Isso é um exemplo, não rode
# catkin_create_pkg <nome_do_pacote> [depende1] [depende2] [depende3]

catkin_create_pkg também tem funcionalidades mais avançadas que são descritas em catkin/commands/catkin_create_pkg.

Compilando o espaço catkin e usando o arquivo de setup

Agora você precisa compilar os pacotes no espaço de trabalho catkin:

$ cd ~/catkin_ws
$ catkin_make

Depois do espaço ter sido compilado, ele criou uma estrutura similar na subpasta devel, como geralmente encontrado em /opt/ros/$ROSDISTRO_NAME.

Para adicionar o espaço ao seu ambiente ROS você precisa "source" o arquivo setup gerado com o seguinte comando:

$ . ~/catkin_ws/devel/setup.bash

Dependências do pacote

Dependências de primeira ordem

Quando usamos catkin_create_pkg antes, algumas dependências foram fornecidas. Essas dependências de primeira ordem agora podem ser revisadas com a ferramenta rospack.

$ rospack depends1 beginner_tutorials

• roscpp
  rospy
  std_msgs

Você pode ver que rospack lista as mesmas dependências que foram usadas como argumentos quando rodamos catkin_create_pkg. Essas dependências de pacote são guardadas no arquivo package.xml:

$ roscd beginner_tutorials
$ cat package.xml

• <package format="2">
  ...
    <buildtool_depend>catkin</buildtool_depend>
    <build_depend>roscpp</build_depend>
    <build_depend>rospy</build_depend>
    <build_depend>std_msgs</build_depend>
  ...
  </package>

Dependências indiretas

Em muitos casos, uma dependência também vai ter suas próprias dependências. Por exemplo, rospy tem outras dependências.

$ rospack depends1 rospy

• genpy
  roscpp
  rosgraph
  rosgraph_msgs
  roslib
  std_msgs

Um pacote pode ter várias dependências. Felizmente, rospack pode determinar recursivamente todas as dependências herdadas.

$ rospack depends beginner_tutorials
cpp_common
rostime
roscpp_traits
roscpp_serialization
catkin
genmsg
genpy
message_runtime
gencpp
geneus
gennodejs
genlisp
message_generation
rosbuild
rosconsole
std_msgs
rosgraph_msgs
xmlrpcpp
roscpp
rosgraph
ros_environment
rospack
roslib
rospy

Customizando seu pacote

Esta parte do tutorial vai examinar cada arquivo gerado por catkin_create_pkg e descrever, linha por linha, cada componente desses arquivos e como customizá-los para seu pacote.

Customizando package.xml

O arquivo package.xml gerado deve estar no seu novo pacote. Agora vamos ao novo package.xml e modificar os elementos que precisam de sua atenção.

tag description

Primeiro, atualize a tag:

   5   <description>The beginner_tutorials package</description>

Modifique a descrição para qualquer coisa que você goste, mas por convenção a primeira frase deve ser curta o bastante para abranger o escopo do pacote. Se for difícil descrever o pacote em uma simples frase então ela pode ser quebrada em mais frases.

tag maintainer

Em seguida, vem a tag maintainer:

   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>

Essa é uma tag obrigatória e importante para o package.xml porque ela permite que outras pessoas saibam com quem entrar em contato para saber mais sobre o pacote. Ao menos um mantenedor (maintainer) é necessário, mas se quiser você pode inserir quantos for necessário. O nome do mantenedor vai no corpo da tag, mas também tem um atributo de email que deve ser preenchido:

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

tag license

Próximo é a tag license, que também é obrigatória:

  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>

Você deve escolher uma licença e inseri-la aqui. Algumas licenças comuns são BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, and LGPLv3. Você pode ler sobre algumas delas em Open Source Initiative. Para este tutorial iremos usar a licença BSD porque o restante dos componentes do ROS já utiliza ela:

   8   <license>BSD</license>

tags dependencies

O próximo conjunto de tags descreve as dependências do seu pacote. As dependências são dividas em build_depend, buildtool_depend, exec_depend, test_depend. Para uma explicação mais detalhadas destas tags, veja a documentação Dependências Catkin. Como passamos std_msgs, roscpp, and rospy como argumentos para catkin_create_pkg, as dependências terão essa aparência:

  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>

Todas as nossas dependências listadas foram adicionadas como build_depend, além do padrão buildtool_depend para catkin. Nesse caso, queremos que todas as nossas dependências especificadas estejam disponíveis no tempo de compilação e execução, portanto adicionaremos a tag exec_depend para cada um delas também:

  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

Como você pode ver o package.xml final, sem comentários e sem tags não utilizadas, é muito mais conciso:

   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>

Customizando o CMakeLists.txt

Agora que o package.xml, que contém meta-informação, foi adaptado para o seu pacote, você está pronto para seguir em frente nos tutoriais. O arquivo CMakeLists.txt criado no tutorial catkin_create_pkg será abordado nos próximos tutoriais sobre compilação dos códigos do ROS.