Getting Started

First, clone this repo (including submodules) to a valid ROS 2 workspace.

mkdir -p ~/roboplan_ws/src
cd ~/roboplan_ws/src
git clone --recursive https://github.com/open-planning/roboplan.git
cd roboplan

There are currently 3 supported ways to work with RoboPlan.

—

Vanilla CMake

One of the design points of this library is that it should be portable, and therefore compiles with “vanilla” CMake.

We do not recommend using this workflow; it’s more of an exercise in making sure the software can compile without any dependencies that lock it into a particular ecosystem.

If you do want to use regular CMake, you should take a look at the Dockerfile under .docker/ubuntu. Alternatively, you can try it for yourself.

export UBUNTU_VERSION=24.04
docker compose build ubuntu

Once the Docker image is built, you can try running the code in the image.

docker compose run ubuntu bash

Inside the shell, you can try different commands, such as.

./build/roboplan_examples/cpp/example_scene
python3 roboplan_examples/python/example_ik.py

To run the unit tests, you can do:

scripts/run_tests.bash

—

Pixi

Another way to manage the environment is with the Pixi package management tool.

First, install Pixi using these instructions.

Once set up, you can use the pixi verbs as follows.

# Build all packages, including Python bindings
pixi run build_all

# Install all packages
pixi run install_all

# This will only build the package (You must have built the dependencies first)
pixi run build PACKAGE_NAME

# This will only install the package
pixi run install PACKAGE_NAME

Once built, you can use the Pixi shell to run specific examples.

pixi shell
./build/roboplan_examples/cpp/example_scene
python3 roboplan_examples/python/example_ik.py

To run the unit tests:

# Test all packages
pixi run test_all

# Test a specific package
pixi run test PACKAGE_NAME

To lint the code:

pixi run lint

Build with AddressSanitizer (ASan)

pixi run build_asan PACKAGE_NAME

Build with compilation time report

pixi run build_timetrace PACKAGE_NAME

—

ROS 2 (colcon)

If you are using ROS 2, you can build RoboPlan with the colcon build system.

Source your favorite ROS distro and compile the package.

source /opt/ros/rolling/setup.bash
cd ~/roboplan_ws
rosdep install --from-paths src -y --ignore-src
colcon build

NOTE: To compile tests, you may also need to install GTest and GMock:

sudo apt install libgtest-dev libgmock-dev

Now you should be able to run a basic example.

source install/setup.bash
ros2 run roboplan_examples example_scene
ros2 run roboplan_examples example_ik.py

At this point, you should also be able to use roboplan as a Python package!

python3
>>> import roboplan

To run the unit tests, you can simply use colcon:

colcon test
colcon test --packages-select roboplan --event-handlers console_direct+