This is an old revision of the document!


CRAM Programming Guidelines

Collaborative Development

If you're working on a package that other people are working on / are using, please try to stick to the following guidelines:

  • Always use the GIT version control system when developing
  • One commit per feature with a meaningful commit message
  • Send a pull request through GitHub, when:
    • you want somebody to review your code
    • you want your code to be tested on a different machine than yours
    • you want to notify people of changes in the interface (?) ← do we want to do it this way, or announce interface changes differently

Development of Roslisp Packages

package.xml/manifest.xml

Relevant documentation: Package.xml Ref

  • No manifest.xml's :) If you create a new package, please stick to catkin
  • As a <build_depend> only specify all the rosdep keys or ROS packages that your package requires at build-time, e.g. other ROS package sources, library headers. Whereas, <run_depend> is for rosdep keys and ROS packages that your package needs at run-time, e.g. shared libraries, executables, Python modules, launch scripts.
    For example, you should put sbcl as a build dependency for all your Lisp packages. Although we don't explicitly use sbcl when catkin_make-ing our Roslisp packages, you will still need sbcl in the next step of your compilation process (inside emacs slime). For all packages where sbcl is a build dep, it will be automatically sudo apt-get install-ed by rosdep when you first cloned the source code of that package and ran rosdep on it. On the other hand, you actually don't need a Common Lisp compiler during the execution of your compiled Lisp *.fasl executives, so I guess you don't need sbcl as a run dep (is this actually correct?)… A good example of this is: <build_depend>libsomelib1.6-dev</build_depend>, whereas <run_depend>libsomelib1.6</run_depend>. More documentation for this can be found here.
  • Use <export><deprecated /></export> to tag deprecated packages
  • The license for all CRAM code should be BSD
  • Put links to github into the <url type=“bugtracker”> and <url type=“repository”> tags

my-package-name.asd files

  • Put it into the root of your source directory, no need for symbolic links and asdf directories
  • Always explicitly specify dependencies on all the Lisp packages, symbols of which you use in your code (even if the dependency is transitive and is automatically added by other packages that you depend on because of hierarchical dependencies) ← is this actually clear?

Coding Style

Lisp

  • Pay attention to the indentation! :D
  • Try not to exceed 80 symbols in width in your code
  • Lisp names (variables, classes, methods, packages) are all lowercase with dashes in between: my-awesome-lisp-variable
  • Do you usually get that feeling that something is underdocumented? :) Think about that when writing your own code. (not that the author of this guideline always sticks to the rules herself hmm…)

Ros-related

  • ROS packages' names are usually lowercase with underscores in between: my_awesome_ros_package

Lisp Programming

Some Lisp patterns and stuff would be nice, like tail recursive functions and accumulators, making sure the functions have no side effects, etcetc…

Testing

The preferred Lisp package for writing simple unit tests is lisp-unit.

Running existing tests

Just do

,r-l-s ROS_SYSTEM_TO_TEST asdf-system-to-test-tests

The asdf system for tests usually has either the -tests suffix, or -test suffix.

And then:

,!p asdf-system-to-test-tests
(run-tests)
or
...
(run-tests my-define-tests-function-name)

That's all.

Writing unit tests for your functions

TODO: here should go a link with some testing tutorial

FiveAM If lisp-unit isn't expressive enough for you, consider using FiveAM. To run tests written with FiveAM (1) load the tests asdf package, (2) change to the corresponding Lisp package in the REPL and (3) execute (run!). If (run!) doesn't do anything automatically, try specifying the test suite name: (run! 'MY_TEST_SUITE_NAME). You can find the name by rgrep-ing (def-suite in your ASDF package.