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
- When sending pull requests always try to include a person who you'd like to review it in the comment to the request
If you want to introduce major interface changes through you code, make an announcement on the cram-developers mailing list
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 putsbcl
as a build dependency for all your Lisp packages. Although we don't explicitly usesbcl
whencatkin_make
-ing our Roslisp packages, you will still needsbcl
in the next step of your compilation process (inside emacs slime). For all packages wheresbcl
is a build dep, it will be automaticallysudo apt-get install
-ed byrosdep
when you first cloned the source code of that package and ranrosdep
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 needsbcl
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 / Public Domain
- 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).
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 optimization flags, 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.