====== Creating a CRAM package ======

**Description:** In this tutorial you will set up a ROS package to use the CRAM plan language within the Lisp REPL. You can find the code resulting from the beginner tutorials on [[https://github.com/cram2/cram_tutorials|GitHub]]..

**Next Tutorial:** [[tutorials:beginner:controlling_turtlesim_2|Controlling turtlesim from CRAM]]

===== Creating a ROS package =====

First we need to create a ROS package that depends on ''cram_language''. On the ROS website there are two tutorials on creating a package: [[http://wiki.ros.org/catkin/Tutorials/CreatingPackage|Package creation]] and [[http://wiki.ros.org/ROS/Tutorials/Creating%20a%20Package%20by%20Hand|Package creation by hand]] (it is recommended that you work with ''catkin'' and not legacy ''rosbuild'').

In the ''src'' subdirectory of your ROS workspace execute the following command:
<code bash>$ catkin_create_pkg cram_my_beginner_tutorial cram_language </code>
===== Setting up the Lisp infrastructure =====

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.
After that we will need to create a Common Lisp package (i.e. the equivalent of C++ namespaces). You can learn ''roslisp'' in more detail through [[http://wiki.ros.org/roslisp/Tutorials|roslisp tutorials]]

==== Creating an ASDF system ====

Switch into the root directory of the ''cram_my_beginner_tutorial'' package  
and create a file ''cram-my-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.

Put the following content into ''cram-my-beginner-tutorial.asd'':

<code lisp>
(defsystem cram-my-beginner-tutorial
  :depends-on (cram-language)
  :components
  ((:module "src"
            :components
            ((:file "package")
             (:file "control-turtlesim" :depends-on ("package"))))))
</code>
             

The first line defines the name of the system. 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 sub-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 ''control-turtlesim.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.

==== Creating the Lisp Package ====

Lisp packages are the equivalent to C++ namespaces or Python modules. Lisp packages cannot be hierarchical. Through Lisp packages 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.

Create a sub-directory ''src'' in your package. Then create the file ''package.lisp'' and put the following code into it:

<code lisp>
(defpackage :cram-my-beginner-tutorial
  (:nicknames :tut)
  (:use :cpl))
</code>  
  
We define a package with the name ''cram-my-beginner-tutorial''. Packages in Common Lisp can have an arbitrary number of nicknames. In our case we nickname ''cram-my-beginner-tutorial'' as ''tut''. Finally, we define that the package uses another package ''cpl'' which is a nickname of the package  ''cram-language'' from the metapackage ''cram_core''. 

==== 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 ''control-turtlesim.lisp'' in ''src'', so create it with the following content:

<code lisp>
(in-package :tut)
</code>

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 the next tutorial.

Now we are ready to compile and load our new system. First of all, let us compile the ROS workspace, such that ROS knows about our new ''cram_my_beginner_tutorial'' package:

<code bash>
$ roscd && cd .. && catkin_make
</code>

Then launch the Lisp REPL (''$ roslisp_repl'', if you already have a REPL running, keep in mind that you need to restart it whenever a new ROS package is added to the workspace). 
Then load your newly created system by typing:

<code lisp>
CL-USER> (ros-load:load-system "cram_my_beginner_tutorial" :cram-my-beginner-tutorial)
</code>

This loads the ''cram-my-beginner-tutorial'' of the package ''cram_my_beginner_tutorial''.
Test it by evaluating

<code lisp>
CL-USER> (in-package :tut)
</code>

== Next ==


Now that we have created our first CRAM package, let's try controlling the ROS turtlesim from it...

[[tutorials:beginner:controlling_turtlesim_2|Controlling turtlesim from CRAM]]