ros-project-generator

ros-project-generator creates a ROS 2 workspace skeleton and can optionally add a VS Code Dev Container configuration. It does not generate Docker images by itself.

Docker files are generated by robotics_dockers, which is included as a Git submodule under extern/robotics_dockers.

Responsibility Boundary

ros-project-generator owns project structure:

• workspace files such as README.md, pyproject.toml, .gitignore, and optional pre-commit config
• deps.repos
• src/0_deps
• starter ROS 2 packages such as bringup and simulation
• optional VS Code files under .devcontainer/, .vscode/, and ws.code-workspace

robotics_dockers owns Docker image generation:

• docker/Dockerfile
• docker/build.py
• docker/docker-compose.yaml
• docker/.resources/
• ROS installation scripts
• entrypoints
• image user setup
• image-level extra package mechanisms

This boundary is intentional. If a generated file controls how the Docker image is built, it belongs in robotics_dockers. If a generated file controls the ROS workspace or the editor experience, it belongs in ros-project-generator.

Clone

Clone the repository with submodules:

git clone --recurse-submodules git@gitlab.local.eurecat.org:robotics-automation/ros-project-generator.git
cd ros-project-generator

If the repository was cloned without submodules:

git submodule update --init --recursive

The submodule is configured to track the ros2 branch of robotics_dockers.

Local Development Install

These packages are not assumed to be published to PyPI. Install both local projects in editable mode:

python3 -m venv /tmp/ros-project-generator-venv
. /tmp/ros-project-generator-venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e extern/robotics_dockers
python -m pip install -e '.[dev]'

The editable install keeps Python imports linked to the working tree. Changes in either repository are visible without reinstalling the package.

Commands

Create a ROS 2 project:

ros-project new PROJECT_ID PROJECT_DIR BASE_IMAGE ROS_DISTRO [options]

Example:

ros-project new my_robot ~/workspaces/my_robot ros:jazzy jazzy \
  --img-id my_robot:jazzy

Create the same project without VS Code files:

ros-project new my_robot ~/workspaces/my_robot ros:jazzy jazzy \
  --img-id my_robot:jazzy \
  --no-vscode

Supported ROS distributions are listed by:

ros-project new -h

At the time this README was written, the project supports ROS 2 distributions only.

Generated Project

A normal generated project contains:

PROJECT_DIR/
  docker/                  # generated by robotics_dockers
  deps.repos
  pyproject.toml
  README.md
  src/
    0_deps/
    bringup/
    simulation/

If VS Code support is enabled, the project also contains:

PROJECT_DIR/
  .devcontainer/
    devcontainer.json
    docker-compose.yaml
  .vscode/
    c_cpp_properties.json
    tasks.json
  ws.code-workspace

Tests

Run the test suite from this repository root:

PYTHONPATH=src:extern/robotics_dockers/src pytest -q

The tests mock the Docker generation call where appropriate. They verify that ros-project-generator delegates Docker file creation to robotics_dockers, keeps project-level resources in this repository, and renders the VS Code templates without unresolved Jinja placeholders.

Development Notes

• Do not add Dockerfile, Docker build, ROS installation, entrypoint, or image-extra resources to this repository.
• Add those resources to robotics_dockers instead, after explicitly deciding to change that project.
• Keep deps.repos and src/0_deps; they describe the source workspace, not the Docker image.
• Keep ROS package templates here when they generate project packages such as bringup or simulation.