Home

Project 소개

ROS_dev_template

우리는 ROS_dev_template라는 패키지를 사용해서 프로젝트를 진행하게 됩니다.

해당 패키지를 좀 더 잘 사용하고 불필요한 작업을 줄이기 위해서 우리는 다양한 소프트웨어 프로그램을 사용합니다.

따라서, 그러한 현업에서 사용하고 있는 소프트웨어 프로그램을 소개하고, 그러한 프로그램을 사용해서 어떠한 식으로 프로젝트를 관리하고 구성하면 좋을지에 대한 내용을 공유하려고 합니다.

대부분의 소프트웨어 프로그램들은 기본적으로 Web & App 개발자들이 주로 만들었기에, nodejs 등 Web&app 관련 프레임워크를 쉽게 사용하기 위해 구성되어있습니다. 우리는 그러한 프로그램들을 ROS2 개발을 쉽게 하기 위해 사용할 예정이고, 그에 맞게 커스터마이징 하여 사용하려 합니다.

Coding Style Guide는 따로 작성된 글을 보면 좀더 자세한 사용에 대한 내용을 얻을 수 있습니다.

이 글에서는 주로 docker, git hook, vscode extension, branch전략에 대한 내용을 좀더 자세히 다루겠습니다.

Docker

지능형로봇사업단 Git & Docker 스터디

기본적인 Docker의 대한 내용은 해당 스터디 내용에 자세하게 담아 놓았으니, 우리는 우리 프로젝트에 적용되어있는 dockerfile, docker-compose.yaml 에 대해서 다루고자 합니다.

dockerfile

# ROS distribution to use
ARG ROS_DISTRO=humble

########################################
# Base Image for gole Simulation #
########################################
FROM osrf/ros:${ROS_DISTRO}-desktop-full as base
ARG REPO
ENV ROS_DISTRO=${ROS_DISTRO}
SHELL ["/bin/bash", "-c"]

ARG DEBIAN_FRONTEND=noninteractive

# Install basic apt packages
RUN --mount=type=cache,target=/var/cache/apt,id=apt \
    apt-get update && apt-get upgrade -y \
    && apt-get install -q -y --no-install-recommends \
    build-essential \
    ccache \
    cmake \
    lld \
    python3-colcon-common-extensions \
    python3-colcon-coveragepy-result \
    python3-colcon-mixin \
    git libcanberra-gtk-module libcanberra-gtk3-module fuse3 libqt5svg5-dev \
    python3-pip python3-opencv python3-tk python3-pyqt5.qtwebengine \
    && rm -rf /var/lib/apt/lists/*

# Install additional Python modules
RUN pip3 install matplotlib transforms3d \
    pytest pytest-cov pytest-mock pytest-xdist

# Use Cyclone DDS as middleware and install ros2 packages
RUN apt-get update && apt-get install -y --no-install-recommends \
    ros-${ROS_DISTRO}-rmw-cyclonedds-cpp \
    ros-${ROS_DISTRO}-navigation2 \
    ros-${ROS_DISTRO}-nav2-bringup
ENV RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

# Create Colcon workspace with external dependencies
RUN mkdir -p /upstream_ws/src
WORKDIR /upstream_ws/src
COPY dependencies.repos .
RUN vcs import < dependencies.repos

# Build the base Colcon workspace, installing dependencies first.
WORKDIR /upstream_ws
RUN source /opt/ros/${ROS_DISTRO}/setup.bash \
    && rosdep update && apt-get update -y \
    && rosdep install --from-paths src --ignore-src --rosdistro ${ROS_DISTRO} -y \
    && rm -rf /var/lib/apt/lists/* \
    && colcon build --mixin release lld

# Download Groot2 AppImage and place it in the home folder.
# WORKDIR /root/
# RUN curl -o Groot2.AppImage https://s3.us-west-1.amazonaws.com/download.behaviortree.dev/groot2_linux_installer/Groot2-v1.0.1-x86_64.AppImage \
#     && chmod a+x Groot2.AppImage

# Remove display warnings
RUN mkdir /tmp/runtime-root
ENV XDG_RUNTIME_DIR "/tmp/runtime-root"
RUN chmod -R 0700 /tmp/runtime-root
ENV NO_AT_BRIDGE 1

# Set up the entrypoint
WORKDIR /upstream_ws
COPY ./docker/entrypoint.sh /
ENTRYPOINT [ "/entrypoint.sh" ]

###########################################
# Overlay Image for gole Simulation #
###########################################
FROM base AS overlay

# Create an overlay Colcon workspace
RUN mkdir -p /overlay_ws/src
WORKDIR /overlay_ws
COPY ./${REPO}/ ./src/${REPO}/
RUN source /upstream_ws/install/setup.bash \
    && rosdep install --from-paths src --ignore-src --rosdistro ${ROS_DISTRO} -y
# && colcon build --symlink-install

# Copy the VSCode settings
COPY ./.vscode /overlay_ws/.vscode

# Set up the entrypoint
COPY ./docker/entrypoint.sh /
ENTRYPOINT [ "/entrypoint.sh" ]
#####################
# Development Image #
#####################
FROM overlay as dev

# Dev container arguments
ARG USERNAME=devuser
ARG UID=${UID}
ARG GID=${GID}

# Install extra tools for development
RUN --mount=type=cache,target=/var/cache/apt,id=apt \
    apt-get update && apt-get install -y --no-install-recommends \
    gdb gdbserver nano \
    git \
    openssh-client \
    python3-pip \
    vim \
    wget \
    && rm -rf /var/lib/apt/lists/*

# install developer tools
RUN python3 -m pip install --no-cache-dir \
    pre-commit==3.0.4

# Create new user and home directory
RUN groupadd --gid $GID $USERNAME \
    && useradd --uid ${GID} --gid ${UID} --create-home ${USERNAME} \
    && echo ${USERNAME} ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/${USERNAME} \
    && chmod 0440 /etc/sudoers.d/${USERNAME} \
    && mkdir -p /home/${USERNAME} \
    && chown -R ${UID}:${GID} /home/${USERNAME}

# Set the ownership of the overlay workspace to the new user
RUN chown -R ${UID}:${GID} /overlay_ws/

# Set the user and source entrypoint in the user's .bashrc file
USER ${USERNAME}
RUN echo "source /entrypoint.sh" >> /home/${USERNAME}/.bashrc

기본적으로 우리가 사용할 docker는 이러한 형태를 띄고 있습니다.

우리는 총 dockerfile를 세개의 stage(Base, overlay, dev)로 나누어서 관리할 예정입니다.

multi-stage에 관련된 글 : docker multi-stage에 관련된 내용은 이 내용을 참고 바랍니다.

Base

Base stage는 ROS2 환경 setting에 관련된 설치가 전부 담겨져있는 stage입니다. 이 단계에서 하는 일을 list화 하겠습니다.

1. 기본적인 apt package 설치
2. 기본적인 python package 설치
3. ROS2에 관련된 추가적인 package 설치
4. upstream_ws에 추가적인 ros2 package설치(이때 해당 ros2 package에 관련된 내용은 [dependencies.repos](https://github.com/Kim-JeongHan/ROS_dev_template/blob/master/dependencies.repos)에 담겨있습니다.)
5. display 공유때 발생하는 warning제거
6. source등록(?)

이렇게 6가지가 될것 같습니다.

💡 추가적인 프로젝트 진행이 있을때, 이 6가지 해당 사항이 있는 경우 dockerfile에 추가한 뒤 `feat/architecture` branch를 통해서 pull request를 보내주시면 될것 같습니다.

overlay

여기는 우리가 주로 사용하는 overlay_ws에 관련된 내용이 담겨져 있습니다.

우리는 develop작업을 주로 overlay_ws에 진행하게 될텐데 이를 build하고 하는 작업이 주로 여기에 들어가있다고 생각하면 됩니다.

아마 프로젝트를 진행함에 있어서 이 부분에 대한 수정은 거의 없을 듯 싶습니다.

1. overlay_ws 구성 및 build

dev

보통 우리가 개발을 진행할 때 사용할 내용이 담겨있습니다. 특정 개발 testing을 하고 싶다. 예를 들어, apt package, python package, **센서 라이브러리**를 테스트 하고 싶은 경우 여기서 먼저 등록해서 build test를 진행하시면 됩니다.

여기에 추가하여 testing을 진행하고 꼭 필요하거나, 해당 작업이 앞으로도 필요하다면 base 단계로 올려주시면 됩니다.

보통 개발에 필요한 apt, pip3에 대한 내용이 여기에 담겨져 있습니다.

1. container arguement
2. 개발에 필요한 추가적인 tool
3. 개발에 필요한 python 패키지
4. 개발에 필요한 home directory group설정 및 권한 설정
5. 개발에 필요한 bashrc 설정

docker-compose.yaml

docker-compose.yaml은 docker에서 docker build, docker run등 GUI차원에서 지원하던 기능을 더 쉽게 사용하기 위해 만든 추가 기능 입니다.

관련된 내용이 궁금하시다면 해당 링크들을 읽어보길 바랍니다.

docker compose build : https://engineer-mole.tistory.com/221

docker compose : https://docs.docker.com/compose/

# Usage:
#
# To build the images:
#   docker compose build
#
# To start up a specific service by name:
#   docker compose up <service_name>
#
# To open an interactive shell to a running container:
#   docker exec -it <container_name> bash
version: "3.9"
services:
  # Base image containing dependencies.
  base:
    build:
      context: .
      dockerfile: docker/Dockerfile
      args:
        - REPO=${REPO}
        - ROS_DISTRO=${ROS_DISTRO}
      target: base
    image: ${REPO}-base:${ROS_DISTRO}
    # Interactive shell
    stdin_open: true
    tty: true
    # Networking and IPC for ROS 2
    network_mode: host
    ipc: host
    # Needed to display graphical applications
    privileged: True
    environment:
      # Allows graphical programs in the container.
      - DISPLAY=${DISPLAY}
      - QT_X11_NO_MITSHM=1
      - NVIDIA_DRIVER_CAPABILITIES=all
      # Needed to run ROS 2 nodes
      - ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-0}
      - TERM=xterm-256color
    volumes:
      # Allows graphical programs in the container.
      - /tmp/.X11-unix:/tmp/.X11-unix:rw
      - ${XAUTHORITY:-$HOME/.Xauthority}:/root/.Xauthority
      # Mount devices and configuration files
      - /dev:/dev
      # Mount ssh keys and git config
      - ~/.ssh:${HOME}/.ssh:ro
      - ~/.gitconfig:${HOME}/.gitconfig:ro
      # Mount group and passwd files for user permissions
      - /etc/group:/etc/group:ro
      - /etc/passwd:/etc/passwd:ro
      - /etc/shadow:/etc/shadow:ro
  # Overlay image containing the example source code.
  overlay:
    extends: base
    image: ${REPO}-overlay:${ROS_DISTRO}
    build:
      context: .
      dockerfile: docker/Dockerfile
      target: overlay

  # Developer container
  dev:
    extends: overlay
    image: ${REPO}-dev:${ROS_DISTRO}
    build:
      context: .
      dockerfile: docker/Dockerfile
      target: dev
      args:
        - UID=${UID:-1000}
        - GID=${UID:-1000}
        - USERNAME=${USERNAME:-devuser}
    volumes:
      # Mount the source code
      - ./${REPO}:/overlay_ws/src/${REPO}:rw
      # Mount colcon build artifacts for faster rebuilds
      - ./.colcon/build/:/overlay_ws/build/:rw
      - ./.colcon/install/:/overlay_ws/install/:rw
      - ./.colcon/log/:/overlay_ws/log/:rw
      # Mount docker directory for faster edits to Dockerfile
      - ./docker:/overlay_ws/docker:rw
      # Mount .devcontainer directory for faster edits to devcontainer.json
      - ./.devcontainer:/overlay_ws/.devcontainer:rw
    user: ${USERNAME:-devuser}
    container_name: ${USER}-${REPO}-dev
    command: bash -c "bash"

아까랑 비슷한 느낌입니다. 여기도 base, overlay, dev 세 가지로 크게 구성했습니다.

주의 깊게 생각 해야 될 부분은 base에 내용을 overlay는 상속을 받고 있고, dev는 overlay를 상속 받고 있다는 것입니다.

base

dockerfile base stage를 build하고 있습니다.

사실 여기도 dockerfile에서 추구하는 방향성과 똑같습니다. base, overlay,dev에서 공통적으로 적용 되어야 하는 것들은 전부 base쪽에 들어가 있습니다.

• 통신을 위한 setting
• volume mount
  • display를 위한 mount
  • permission공유를 위한 mount
  • device 공유를 위한 mount

overlay

별 내용은 없습니다. dockerfile overlay stage를 build하고 있습니다.

dev

dockerfile dev stage를 build하고 있습니다.

volume mount관련된 내용은 우리가 프로젝트를 진행하기 위한 내용을 주로 다루고 있습니다. container와 local 환경을 mount시켜서 좀 더 쉽게 프로젝트를 진행할 수 있게 도와줍니다.

• volume mount
  • source code
  • .colcon안에 있는 build, install, log파일을 container안에 있는 workspace와 mount하여 container를 나가더라도 빌드한 패키지를 재 빌드할 필요가 없습니다.
  • dockerfile를 mount하여 내부 container에서 dockerfile를 쉽게 수정할 수 있게 해줍니다.
  • .devcontainer를 mount하여 내부 container에서 dockerfile를 쉽게 수정할 수 있게 해줍니다.
  • 추가적으로 수정이 있을 예정입니다.

.env

이 파일은 docker-compose기능을 수행할 때 매개변수로 넣어줄 수 있습니다.

또한 vscode extension와도 관련이 있습니다.

REPO=gole
ROS_DISTRO=humble
PYTHONPATH=src:install/lib/python3.10/site-packages

pre-commit

.pre-commit-config관련한 내용입니다. 사실 이 부분은 자세하게 할 내용이 따로 없고 세미나 했던 내용을 참고하면 됩니다.

pre-commit 간단 세미나

중요한 것은 git clone을 진행한 다음에 pre-commit install 반드시 해줘야 활성화 된다는 것 입니다.

.devcontainer

devcontainer.json

이는 vscode를 해당 directory에서 키면 자동으로 docker-compose파일에 따라 build를 진행하고, 개발 container를 구성할수 있게 해주는 json파일입니다. 이때 local vscode extension중 선택적으로 꼭 필요한 부분을 공유할 수 있게 extension추가를 해 놓았습니다.

이 외에 추가했으면 하는 vscode extension같은 경우 update해주시면 pull-request를 통해 update하고 여기서 공유해주었으면 합니다.

// See https://aka.ms/vscode-remote/devcontainer.json for format details.
{
    "dockerComposeFile": "../docker-compose.yaml",
    "service": "dev",
    "workspaceFolder" : "/overlay_ws",
	// Set *default* container specific settings.json values on container create.
	"customizations": {
		"vscode": {
			"extensions": [
				"althack.ament-task-provider",
				"betwo.b2-catkin-tools",
				"DotJoshJohnson.xml",
				"ms-azuretools.vscode-docker",
				"ms-iot.vscode-ros",
				"ms-python.python",
				"ms-vscode.cpptools",
				"redhat.vscode-yaml",
				"smilerobotics.urdf",
				"streetsidesoftware.code-spell-checker",
				"twxs.cmake",
				"yzhang.markdown-all-in-one",
				"zachflower.uncrustify"
			]
		}
	}
}

저도 하나하나의 extension에 대한 내용을 알지 못하여 설명은 생략하겠습니다.

💡 만약 프로젝트를 진행하다 공유하고 싶은 extension이 있으면 추가한 뒤 간단한 설명을 써주시면 감사하겠습니다.

.vscode

launch.json

debug및 실행파일의 실행을 위해 setting해놓은 부분입니다.

F5를 통해 쉽게 debug할 수 있습니다.

• python : python debug이다. 이는 현재 내가 키고있는 python file을 debugging한다.
• gdb launch (merge-install) : [gdb debug에 대한 사용방법](https://jangpd007.tistory.com/54)
• ROS launch (merge-install) : launch.py에 대한 debug

저희가 주로 사용할 debug입니다.

따로 시간이 생긴다면 vscode extension debugging를 참고하여 추가적으로 설명하겠습니다.

settings.json

이 부분은 개발 container에서 python, yaml, xml, c++등을 편집할 때 좀 더 편리하게 볼 수 있게 하는 설정 정보를 포함하고 있습니다. 해당 부분이 마음에 들지 않는다면 수정하거나 해도 됩니다.

{
    "editor.tabSize": 8,
    "editor.rulers": [
        100
    ],
    "files.associations": {
        "*.repos": "yaml",
        "*.world": "xml",
        "*.xacro": "xml"
    },
    ///////////////////////////////////////////////////////
    //if you don't use humble, comment out the next line
    "python.analysis.extraPaths": [
        "/opt/ros/humble/lib/python3.10/site-packages/"
    ],
    // // Autocomplete from ros python packages
    "python.autoComplete.extraPaths": [
        "/opt/ros/humble/lib/python3.10/site-packages/"
    ],
    // // Environment file lets vscode find python files within workspace
    "python.envFile": "${workspaceFolder}/.env",
    // Use the system installed version of autopep8
    "python.formatting.autopep8Path": "/usr/bin/autopep8",
    "python.formatting.autopep8Args": [
        "--max-line-length=100"
    ],
    "C_Cpp.default.intelliSenseMode": "linux-gcc-x86",
    "C_Cpp.formatting": "disabled",
    "uncrustify.configPath.linux": "/opt/ros/humble/lib/python3.10/site-packages/ament_uncrustify/configuration/ament_code_style.cfg",
    "[cpp]": {
        "editor.defaultFormatter": "zachflower.uncrustify"
    },
    //comment out this line if you don't use humble
    ///////////////////////////////////////////////////////
    "search.exclude": {
        "**/node_modules": true,
        "**/bower_components": true,
        "**/*.code-search": true,
        "**/build": true,
        "**/install": true,
        "**/log": true
    },
    "cSpell.words": [
        "RTPS",
        "athackst",
        "autopep",
        "cmake",
        "cppcheck",
        "cpplint",
        "DCMAKE",
        "deque",
        "devcontainer",
        "ints",
        "noqa",
        "pytest",
        "rclcpp",
        "rclpy",
        "repos",
        "rosdep",
        "rosdistro",
        "rosidl",
        "RTPS",
        "uncrustify",
        "Wextra",
        "Wpedantic",
        "xmllint"
    ],
    "cSpell.allowCompoundWords": true,
    "cSpell.ignorePaths": [
        "**/package-lock.json",
        "**/node_modules/**",
        "**/vscode-extension/**",
        "**/.git/objects/**",
        ".vscode",
        ".vscode-insiders",
        ".devcontainer/devcontainer.json"
    ]
}

tasks.json

나만의 custom 공식을 만드는 곳 입니다.

.vscode의 tasks.json 이해해보기

Ctrl+alt+p 를 누르고 tasks를 검색하면 본인이 추가해놓은 tasks와 관련된 추가적인 자동 단축키를 사용할 수 있습니다.

Run task에 build, clean, debug등 다양한 기능을 추가해놓았습니다. 클릭하게 되면 자동으로 해당기능을 사용할 수 있습니다. 밑에서 수행하는 기능에대한 설명을 하나씩 설명하겠습니다.

build

./docker/build.sh를 실행시킵니다.

#!/bin/bash
set -e

# Choose build
# --symlink-install : symlink the package into the install space
# --merge-install : merge all packages into one install space

# Set the default build type
BUILD_TYPE=RelWithDebInfo
colcon build \
        --symlink-install \
        --cmake-args "-DCMAKE_BUILD_TYPE=$BUILD_TYPE" "-DCMAKE_EXPORT_COMPILE_COMMANDS=On" \
        -Wall -Wextra -Wpedantic

build --symlink-install과 --merge-install 방식중 선택할 수 있습니다.

저희는 주로 --symlink-install 방식을 주로 선택해서 사용할 예정입니다.

DCMAKE_BUILD_TYPE를 build로 선택합니다.

clean

빌드된 파일을 정리하고 초기 상태로 되돌리는 데 사용됩니다. **colcon**을 사용하여 빌드된 파일을 제거함으로써 다시 빌드할 때 깔끔하게 재 빌드할수 있습니다. "clean" 작업을 실행하면 프로젝트의 임시 및 생성된 파일을 정리하여 코드를 관리하기 좀 더 쉽게 만듭니다.

colcon build --cmake-target clean

debug

./docker/build.sh를 실행시킵니다.

DCMAKE_BUILD_TYPE를 debug로 선택합니다.

test

colcon test를 작동시킵니다.

해당 명령은 overlay_ws에서 작동시키는 것을 추천합니다.

fix, uncrustify

우리는 uncrustify에서 정의된 방식의 formatting방식을 사용할 예정입니다.

https://github.com/uncrustify/uncrustify

"uncrustify"는 코드 스타일을 재정렬하고 일관성 있게 유지하기 위한 code formatter 및 linter입니다. 코드 파일의 들여쓰기, 공백, 줄 바꿈 등을 일관성 있게 변경하여 일관된 코드 규칙을 유지하게 합니다.

linter의 개념에 대한 관련글을 첨부했습니다.

linter를 이용한 코딩스타일과 에러 체크하기

ROS프로그래밍 규칙에 대한 간단한 자료를 첨부했습니다.

Ros 프로그래밍 규칙

fix 주로 코드를 재정렬 및 가독성을 높이는데 사용합니다.

uncrustify 주로 코드 style 검사 및 code linting을 통해서 코드 형식문제를 찾아냅니다.

둘다 optional한 부분입니다.

lint all

본인이 수정하고 있는 c++, python 단일 파일을 검사하고 싶을 때 사용합니다. code linting을 통해서 형식문제를 찾아서 수정해줍니다.

install dependencies

해당 package를 사용하기위한 dependencies를 자동으로 찾아서 설치해줍니다. 이를 통해서 설치되는 파일들은 /opt/ros/humble 안에서 찾아보면 있습니다.

new ament_python package, new ament_cmake package

새로운 python이나 c++ 패키지를 만들때 사용합니다.

위치는 src/gole에 자동으로 생성됩니다.

c_cpp_properties.json

보다더 효과적인 c++개발을 위한 환경설정입니다.