Development

This project makes use of Docker in order to make sure that development machines do not become "special snowflakes" which cannot be reproduced. Docker allows lightweight "containers" to be created which wrap up an application and all of its dependencies. We make use of Docker in our build system to create a virtual machine image containing our software on each compile.

The "Dockerfile" and "Makefile" in this repo, therefore, contains all of the information required to re-create the development machine at any time.

Useful pages

• [Getting started](Getting started) - a description of how to get up and running with development.
• Recipes - quick recipes for reference.

The "zen" of development

We want to make sure that this project is useful for future students and somewhat robust against individual machines dying. To this end we are forced to be honest by doing all development within a (temporary) container. You can view this as forcing you to re-install your machine after each change. This makes sure that we keep the process to re-create the system as automated as possible.

Common gotchas

Doing any of these things will result in a "biscuit fine". The perpetrator will have to buy a pack of biscuits for everyone else.

• Having your email address in git commits be different from your GitHub email address. Fix this with git config --global user.email "foobar@example.com".
• Developing in master. The first thing you do of a day should start with git checkout -b.

Development workflow

All development is done within this repo. The src/ros directory contains ROS packages which together implement our system. Whenever you do a make gui or make shell, the contents of this directory are copied to a temporary container with ROS installed.

CHANGES YOU MAKE TO THE CONTAINER WILL BE LOST WHENEVER YOU REBUILD THE IMAGE. EXPERIMENT WITHIN THE CONTAINER BUT YOU SHOULD NOT USUALLY BE EDITING FILES WITHIN THE CONTAINER.

This behaviour is by design. It may seem frustrating initially but it keeps you honest.

A typical workflow might look like this:

0. Create a new development branch with git checkout -b my-development-branch. Use a better name than that though. Choose something which expresses your current goal. If you can't sum up your current coal in two or three words, you need to split your problem into smaller goals.
1. Make a change to some file under src/ros.
2. Run make to build the container image and compile your code. NOTE: if you already have a container running, the build system will not delete it automatically; you'll need to do that manually by following the instructions presented.
3. Either start a roslaunch file via make launch or start a GUI session via make gui.
4. Test your change.
5. Decide on a modification.
6. If running a GUI session, close it.
7. If you've not managed to get the change to work, go to step 2.
8. git commit, Ctrl+O enter Ctrl+X, go to step 2 if it isn't going home time and if you haven't achieved the goal.
9. git push -u __github_Name___ __branch_name___ and write comment again on github
10. (Obsolete) git checkout master git pull (to make sure local master is up-to-date) and git merge my-development-branch
11. (Obsolete) git push
12. Go to step 1 unless it is going home time.

Copying a folder from GUI

1. make sftp to log onto gui on your original terminal
2. cd toward the desired directory
3. get -r XXname_of_folderXX -r means recursive, i.e. take all the files within the folder. Make sure you're at the right directory on your original terminal because the files will be pasted there.

Making sure that docker cache is updated

This is to make sure that the docker image is updated and upgraded to the latest version. It is usually done every few months, and is especially important if there is a need to install new packages.make DOCKER_BUILD_OPTS=--no-cache