Rework development tooling

[hidmic]

Precisely what the title says. This patch replaces our multiple Dockerfiles and scripts with a multi-stage build and a single script to help manage a containerized workspace.

Connected to #257. Documentation upcoming!

[hidmic]

@arjo129 @caguero are we actually using these scripts? I was on the fence as to whether to migrate them along or not.

[arjo129]

This script was a hack for back when I was working with the mbari controller in the loop. It made it easy for me to get set up with the controller

[hidmic]

Do you think it's still useful in that context? I plan to support running publicly available missions with the MBARI controller.

[arjo129]

Yep, it definitely is, although a user would have to know a bit about how to navigate tmux. The top pane loads the mbari CLI and the bottom pane the simulator. The second window was for plotting vehicle behavior as seen internally by the mbari controller (we were debugging issues like sign flips for integration etc). I think the second window can be removed.

[hidmic]

Circling back here. On a second look, theses scripts are super specific to MBARI's codebase. I think we should move them to the other side and make sure they are present in the public image (along with the same capabilities this tooling I'm adding has to iterate on them).

[hidmic]

@arjo129 @caguero are these linting scripts being used at all? I've relocated them, but I'd be inclined to remove them if we are not using them (or integrating them with CTest to enforce them through CI).

[hidmic]

See modified installation page below.

---

Installation

Use Docker image

Build the latest LRAUV simulation image:

docker build --target lrauv -t osrf/lrauv:latest -f tools/setup/Dockerfile https://github.com/osrf/lrauv.git#main

You may then run a sample simulation:

docker run --rm -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix:ro --gpus all osrf/lrauv:latest

or attach to the container and run gz sim manually.

Note: at the moment, these Docker images require Nvidia graphics. Make sure you have a recent version of Docker and nvidia-docker installed if so required by your Docker version.

Build from source

There are two ways to build the LRAUV simulation from source:

1. Using a local workspace
2. Using a containerized workspace

Using a local workspace

Install prerequisites

Ideally you want to be running Ubuntu Focal or Jammy on an amd64 architecture.

Gazebo Garden

Gazebo is the toolbox of development libraries for simulation that is used to simulate LRAUVs. Gazebo Garden is the version used by the LRAUV simulation and it needs to be installed first.

Instructions on how to compile and install Gazebo Garden from source can be found here.

NOTE: The latest source in this repository will need specific changes on some of the gazebo libraries. Instead of the Gazebo Garden collection file it is recommended to use the following repos file when getting the sources:

wget https://raw.githubusercontent.com/osrf/lrauv/main/tools/setup/gz-garden.yaml

Alternatively, unstable binary packages for Gazebo Garden can also be installed from the nightly Gazebo repositories. Gazebo nightlies are packages released every night which can be used for different purposes like testing the last feature added to gazebo code. The nightly packages repository is designed to work together with the stable repository, so both need to be added:

sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list'
sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-nightly `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-nightly.list'
wget https://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add -

After this just update and install the Gazebo Garden metapackage:

sudo apt-get update
sudo apt-get install gz-garden

Colcon

Colcon is the command line tool used to help easily compile and test all the packages in the LRAUV repository.

First, the ROS2 repositories that contain the colcon binary packages need to be enabled:

sudo sh -c 'echo "deb [arch=amd64,arm64] http://repo.ros2.org/ubuntu/main `lsb_release -cs` main" > /etc/apt/sources.list.d/ros2-latest.list'
wget https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc -O - | sudo apt-key add -

Then just update an install the colcon packages:

sudo apt-get update
sudo apt-get install python3-colcon*

Extra dependencies

sudo apt-get install \
    libeigen3-dev \
    libpcl-dev \
    python3-empy \
    python3-numpy

Get the sources and build

mkdir -p lrauv_ws/src
cd lrauv_ws/src
git clone https://github.com/osrf/lrauv.git
cd -
colcon build

Developers may also want to build tests. Note that this will take longer:

colcon build --cmake-args "-DBUILD_TESTING=ON"

You can pass --cmake-args ' -DENABLE_PROFILER=1' to use the profiler.
See more on this tutorial

Using a containerized workspace

This is the recommended mechanism for development, as it ensures a consistent environment.

Make sure you have a recent version of Docker and nvidia-docker installed if so required by your Docker version. Then, simply run the following command:

wget https://raw.githubusercontent.com/osrf/lrauv/main/tools/setup/workspace.sh -O - | bash

It'll prompt for a workspace directory, or default to the current working directory if none is provided, and then proceed with the build of Docker images. Note this may take a while.

Once it's done with the build, run the ./enter script at the workspace root. When executed, this script will run the container, mount the workspace into it, and attach the terminal.

Now, you can build the workspace:

colcon build

To join in a separate terminal, simply ./enter the workspace again.

[hidmic]

Also, see https://github.com/osrf/lrauv/wiki/Work-environment.

[caguero]

docker build --target lrauv -t osrf/lrauv:latest -f tools/setup/Dockerfile https://github.com/osrf/lrauv.git#main

When running this command I get the following error:

unable to prepare context: unable to evaluate symlinks in Dockerfile path: lstat /tmp/docker-build-git693569966/tools/setup: no such file or directory

[hidmic]

@caguero that's because we haven't merged yet. Change the branch name at the end of the URL!

[hidmic]

Alright, in the interest of time, I will move forward with this PR.