Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
doc:beginner:creating_a_cram_package [2013/12/09 16:01] – [Exporting the asdf system to ROS] bbrieberdoc:beginner:creating_a_cram_package [2014/03/11 13:39] (current) – hmess
Line 1: Line 1:
 ====== Creating a CRAM package ====== ====== Creating a CRAM package ======
  
-Description: In this tutorial you will learn how to set up a ROS package to use the CRAM plan language+**Description:** In this tutorial you will learn how to set up a ROS package to use the CRAM plan language
  
-===== Creating the ROS package ===== +**Next Tutorial:** [[doc:beginner:controlling_turtlesim|Controlling turtlesim from Lisp]]
-First we need to create a ROS package. It needs to depend on ''roslisp_runtime'' and on ''cram_language''.+
  
-**catkin** +This tutorial assumes that you have set up your ROS environment and installed ''cram_core''. If not, go through the //Basic// and //For Developers// parts of the [[/installation|installation document]].
-<code> +
-catkin_create_pkg cram_tutorial roslisp_runtime cram_language +
-</code> +
-**rosbuild** +
-<code> +
-roscreate-pkg cram_tutorial roslisp_runtime cram_language +
-</code>+
  
-That was easy. Now we need to set up the lisp infrastructure.+===== Creating a ROS package =====
  
-===== Setting up the Lisp infrastructure =====+First we need to create a ROS package that depend on ''cram_language''. 
 +You can do this with either catkin or rosbuild.
  
-Setting up the Common Lisp part is a little more work. First we need to create a Lisp 'project file', i.e. an asdf system.+**For catkin**
  
-**Note:** ROS is still based on asdf 1.x so no asdf 2.0 features should be used.+Go to the ''src'' subdirectory of your catkin workspace: 
 +<code bash>$ cd MY_CATKIN_WORKSPACE_PATH/src</code> 
 +and execute the following: 
 +<code bash>$ catkin_create_pkg cram_beginner_tutorial cram_language </code> 
 +More information on ''catkin_create_pkg'' can be found by executing 
 +<code>$ catkin_create_pkg --help</code> 
 +or on the [[http://wiki.ros.org/catkin/Tutorials/CreatingPackage|ROS Website]].
  
-After we created the system, we need to create a Common Lisp package (i.e. the equivalent to C++ namespaces).+**For rosbuild**
  
-==== Creating an asdf system ====+Please use ''rosbuild'' only if you really need to. And keep in mind that it is deprecated and will be removed from ROS at some point. 
 +In your rosbuild workspace root do: 
 +<code bash>$ roscreate-pkg cram_beginner_tutorial cram_language</code> 
 +That was easy. Now we need to set up the Lisp infrastructure.
  
 +===== Setting up the Lisp infrastructure =====
  
-Switch into the root directory of the cram_tutorial package and create the file ''cram-tutorial.asd''. You shouldn't use underscores but dashes in asd file names. The reason is that the system that is defined in the asd file should be named like the file itself and in Lisp it is very uncommon to use underscores.+Setting up the Common Lisp part is a little bit more work. First we need to create a Lisp 'project file', i.e. an ASDF system (yes, the system is indeed called ASDF :P). 
 +After that we will need to create a Common Lisp package (i.e. the equivalent to C++ namespaces).
  
-=== The code ===+==== Creating an ASDF system ==== 
 + 
 +Switch into the root directory of the ''cram_beginner_tutorial'' package: 
 + 
 +<code bash> 
 +$ rospack profile 
 +$ roscd cram_beginner_tutorial 
 +</code> 
 +   
 +and create a file ''cram-beginner-tutorial.asd''. You shouldn't use underscores but dashes in asd file names. The reason is that the system that is defined in the asd file should be named like the file itself and in Lisp it is very uncommon to use underscores in general.
  
 +=== The code ===
  
-Put the following content into ''cram-tutorial.asd'':+Put the following content into ''cram-beginner-tutorial.asd'':
  
-<code> +<code lisp> 
-(defsystem cram-tutorial +(defsystem cram-beginner-tutorial 
-  :depends-on (roslisp cram-language)+  :depends-on (cram-language)
   :components   :components
   ((:module "src"   ((:module "src"
Line 47: Line 61:
 === The code explained === === The code explained ===
  
 +The first line defines the name of the system. It should be named like the file name in which it is defined. Then we specify the dependencies of the system, i.e. other systems that need to be loaded before we load our system.
  
- +Finally, we define the components of the system. A component is a sort of a sub-system of a system and might be either a module (i.e. a sub-directory) or a file. ASDF knows some more component types but they are not relevant for us most of the time. We define that the system knows a sub-directory ''src''. Further, we define that this module contains two components, one file for the package definition ''package.lisp'' and one with the actual tutorial code ''tutorial.lisp'' that has exactly one dependency - the component ''package''. We will create these two source files next. Dependencies inside the system can be any component that is known in the current scope. That means that a component can only depend on those components that are defined in the same parent component. Please note that the file extension must be left out when defining files.
-The first line defines the name of the system. It should be named like the file name in which it is defined. Then we define the dependencies of the system, i.e. other systems that need to be loaded before we load our system. +
- +
-Finally we define the components of the system. A component is sort of a sub-system of a system and might be either a module (i.e. a sub-directory) or a file. asdf knows some more component types but they are not relevant for us most of the time. We define that the system knows a sub-directory src. Further, we define that this module contains two files, one for the package definition package.lisp and one with the actual tutorial code tutorial.lisp that has exactly one dependency, the component package. We will create these two source files next. Dependencies inside the system can be all components that are known in the current scope. That means that a component can only depend on components that are defined in the same parent component. Please note that the file extension must be left out when defining files.+
  
 ==== Creating the Lisp Package ==== ==== Creating the Lisp Package ====
  
- +Lisp packages are the equivalent to C++ namespaces or to Python modules. Lisp packages cannot be hierarchic. We can define which other packages should be used, i.e. which symbols should be accessible without a package prefix. Further, we can define which symbols should be exported from the package.
-Lisp packages are the equivalent to C++ namespaces or to python modules. Lisp packages cannot be hierarchic. We can define which other packages should be used, i.e. which symbols should be accessible without a package prefix. Further, we can define which symbols should be exported from the package.+
  
 === The code === === The code ===
- 
  
 Create a sub-directory ''src'' in your package. Then create the file ''package.lisp'' and put the following code into it: Create a sub-directory ''src'' in your package. Then create the file ''package.lisp'' and put the following code into it:
  
-<code> +<code lisp> 
-(defpackage cram-tutorial+(defpackage cram-beginner-tutorial
   (:nicknames :tut)   (:nicknames :tut)
-  (:use #:cpl #:roslisp))+  (:use #:cpl))
 </code>   </code>  
      
 === The code explained === === The code explained ===
  
 +We define a package with the name ''cram-beginner-tutorial''. Packages in Common Lisp can have an arbitrary number of nicknames. In our case we nickname ''cram-beginner-tutorial'' as ''tut''. Finally, we define that the package uses another package ''cpl'' which is the nickname of a package of the CRAM Plan Language. Please note that most Common Lisp packages actually use the package ''common-lisp'' which exports all symbols of the Common Lisp standard. The packages ''cpl'' and ''common-lisp'' cannot be used together because the CRAM Language re-defines some of the symbols of the ''common-lisp'' package and thus ''cpl'' and ''common-lisp'' would conflict.
  
-We define a package with the name ''cram-tutorial''. Packages in Common Lisp can have an arbitrary number of nicknames. Finally, we define that the package uses two packages, the package cpl which is the package of the cram plan language, and the package roslisp. Please note that most Common Lisp packages actually use the package common-lisp which exports all symbols of the Common Lisp standard. The packages ''cpl'' and ''common-lisp'' cannot be used together because the cram language re-defines some of the symbols of the common-lisp package and thus ''cpl'' and ''common-lisp'' would conflict.+==== Exporting the ASDF system to ROS ====
  
-==== Exporting the asdf system to ROS ====+To actually load the ASDF system, all files referenced in the system definition must be present and we are missing the file ''tutorial.lisp'' in ''src'', so create it with the following content:
  
-To actually load the asdf system, all files referenced in the system definition must be present. Create the file ''src/tutorial.lisp'' with the following content: +<code lisp>
- +
-<code>+
 (in-package :tut) (in-package :tut)
 </code> </code>
Line 84: Line 93:
 This just selects the namespace of the file by the nickname '':tut'' we defined in ''package.lisp''. We will fill it with more content in later tutorials. This just selects the namespace of the file by the nickname '':tut'' we defined in ''package.lisp''. We will fill it with more content in later tutorials.
  
 +Now we are ready to compile and load our new system. Launch Emacs and load the Lisp REPL. If it is already running, reload it by executing
 +
 +<code lisp>
 +,
 +restart-inferior-lisp
 +</code>
  
-Now we are ready to compile and load our new system. Launch Emacs and load the Lisp REPL. Enter the following command:+in the REPL. Then, enter the following command:
  
-<code> +<code lisp> 
-(ros-load:load-system "cram_tutorial" :cram-tutorial)+(ros-load:load-system "cram_beginner_tutorial" :cram-beginner-tutorial)
 </code> </code>
  
-You need to load the system every time before you use it, experts would build their own shortcuts to this command or use the rosemacs function:+You need to load the system every time before you use it, so experts would build their own shortcuts to this command or use the rosemacs function unstead:
  
-<code> +<code lisp> 
-"," > ros-load-system > cram_tutorial > cram-tutorial+, 
 +ros-load-system 
 +cram_beginner_tutorial 
 +cram-beginner-tutorial
 </code> </code>
  
-The first parameter names the ROS package in which to search for the system, the second parameter names the system to be loaded. Executing the above command should load our new asdf system. Now the package ''cram-tutorial'' should be defined. Test it by evaluating+The first parameter to ''ros-load-system'' names the ROS package in which to search for the system, the second parameter names the system to be loaded. Executing the above command should load our new ASDF system. Now the package ''cram-beginner-tutorial'' should be defined. Test it by evaluating
  
-<code>+<code lisp>
 (in-package :tut) (in-package :tut)
 </code> </code>
  
-Now that we have created our first cram package, let's try controlling the ROS turtlesim from it..+Now that we have created our first CRAM package, let's try controlling the ROS turtlesim from it...
  
 +[[doc:beginner:controlling_turtlesim|Controlling turtlesim from Lisp]]