From 4852dfe49104f53b942a19ffa4833173fe0965c6 Mon Sep 17 00:00:00 2001 From: YuZhong-Chen Date: Thu, 22 Aug 2024 00:34:24 +0800 Subject: [PATCH] docs(template_ws): Update README.md --- template_ws/README.md | 36 +++++++++++++++++---------------- template_ws/docker/compose.yaml | 4 ++-- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/template_ws/README.md b/template_ws/README.md index acc7dd57..829323a2 100644 --- a/template_ws/README.md +++ b/template_ws/README.md @@ -12,12 +12,10 @@ ros2-essentials | └── create_workspace.sh ├── template_ws | ├── .devcontainer -| | ├── devcontainer.json -| | └── postCreateCommand.sh +| | └── devcontainer.json | ├── docker -| | ├── cache -| | | └── .gazebo | | ├── .bashrc +| | ├── .dockerignore | | ├── compose.yaml | | └── Dockerfile | ├── install @@ -34,7 +32,6 @@ ros2-essentials ``` - `build` / `install` / `log` folders will appear once you've built the packages. -- `minimal_pkg` is the ROS2 package used to create a publisher and subscriber in both Python and C++. You can remove it if you don't need it. ## 🚩 How to use this template 🚩 @@ -49,19 +46,21 @@ We have provided a script to create a new workspace. Please use it to avoid pote > To unify the naming style, we will modify the string `` in some files. -### 2. Configure Docker settings. +### 2. Configure settings. + +> To help you easily find where changes are needed, we have marked most of the areas you need to adjust with `# TODO:`. Usually, you only need to modify the configurations without removing anything. If you really need to remove something, make sure you clearly understand your goal and proceed with caution. - `docker/Dockerfile` - - Check whether the default Dockerfile meets your requirements. If not, feel free to modify the contents. In most cases, you may want to install additional tools for ROS packages. + - Add the packages you need according to the comments inside. - `docker/compose.yaml` + - By default, the Docker image is built according to your current computer's architecture. If you need to cross-compile, please modify the `platforms` parameter to your desired architecture and set up the basic environment. - If you want to access the GPU in the container, please uncomment the lines accordingly. - If you want to add any environment variables in the container, you can include them in the `environment` section, or you can use `export VARIABLE=/the/value` in `docker/.bashrc`. -- `.devcontainer/devcontainer.json` - - Update the `name` to match your project. - - Add any extensions you want in the `Vscode extensions`. - - If you change the service name in `compose.yaml`, please update the setting in the `service` section accordingly. -- `.devcontainer/postCreateCommand.sh` - - This script will be executed after the container-building process. Feel free to add any desired commands here. +- `docker/.bashrc` + - We will automatically compile the workspace in .bashrc. If you don't want this to happen, feel free to remove it. If you’re okay with it, remember to adjust the compilation commands according to your packages. +- `src` + - Add the ros packages you need here. + - `minimal_pkg` is the ROS2 package used to create a publisher and subscriber in both Python and C++. You can remove it if you don't need it. ### 3. Open the workspace folder using Visual Studio Code. @@ -70,13 +69,14 @@ We have provided a script to create a new workspace. Please use it to avoid pote > Please refer to the tutorial provided by Visual Studio Code first. > You can find it here: [https://code.visualstudio.com/docs/devcontainers/containers](https://code.visualstudio.com/docs/devcontainers/containers) -Spotting the workspace folder within your Explorer indicates that you've selected the wrong folder. -You should only observe the `.devcontainer`, `docker` and `src` folders there. +> We recommend using `VScode` + `devcontainer` for development. This plugin can significantly reduce development costs and can be used on local computers, remote servers, and even embedded systems. If you don't want to use `devcontainer`, you can still use Docker commands for development, such as `docker compose up` and `docker exec`. -**Note**: Alternatively, you can use `docker compose` instead of `devcontainer` if you are not using VSCode. +Open the workspace folder using Visual Studio Code, spotting the workspace folder within your Explorer indicates that you've selected the wrong folder. You should only observe the `.devcontainer`, `docker` and `src` folders there. ### 4. Build the container. +> We have pre-built some Docker images on Docker Hub. If the building time is too long, you might consider downloading them from Docker Hub instead. For more information, please refer to the `README.md` on the repository's main page. + Press `F1` and enter `> Dev Containers: Rebuild Container`. Building the images and container will take some time. Please be patient. @@ -86,6 +86,8 @@ You should see the output below. Done. Press any key to close the terminal. ``` +> For non-devcontainer users, please navigate to the `docker` folder and use `docker compose build` to build the container. We have moved all commands that need to be executed into the `.bashrc` file. No further action is needed after creating the Docker container. + ### 5. Start to develop with ROS. You've successfully completed all the instructions. @@ -94,5 +96,5 @@ Wishing you a productive and successful journey in your ROS development ! ## ⚠️ Warning ⚠️ - Do not place your files in any folder named `build`, `install`, or `log`. These folders will not be tracked by Git. -- If you encounter an error when opening Gazebo, consider closing the container and deleting the cache in the `docker/cache` directory. Please note that you should only delete the files inside the folder and not the entire cache folder. +- If you encounter an error when opening Gazebo, consider closing the container and reopen it. Alternatively, you can check the log output in `~/.gazebo`, which may contain relevant error messages. The most common issue is using a duplicate port, which prevents Gazebo from starting. You can use `lsof -i:11345` to identify which process is using the port and then use `kill -9` to terminate it. - `xhost +local:docker` is required if the container is not in privileged mode. diff --git a/template_ws/docker/compose.yaml b/template_ws/docker/compose.yaml index 43cd0c6a..00261058 100644 --- a/template_ws/docker/compose.yaml +++ b/template_ws/docker/compose.yaml @@ -3,7 +3,7 @@ services: build: context: . dockerfile: Dockerfile - # Specify the target platform to build the image, otherwise it will build for the host platform. + # TODO: Specify the target platform to build the image, otherwise it will build for the host platform. # Reference: https://docs.docker.com/compose/compose-file/build/#platforms # platforms: # - "linux/arm64" @@ -19,7 +19,7 @@ services: environment: # Set X11 server environment variable for existing display. - DISPLAY=$DISPLAY - # Set ros2 environment variables. + # TODO: Set ros2 environment variables. # References: # - https://docs.ros.org/en/humble/Concepts/Intermediate/About-Domain-ID.html # - https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html