From 9f7eadbab2fa102321e45c75e7f501afce8d2f65 Mon Sep 17 00:00:00 2001 From: catslashbin Date: Fri, 8 Dec 2023 09:52:32 +0800 Subject: [PATCH] Update README.md --- README.md | 126 ++++++++++++++++++++++++------------------------------ 1 file changed, 55 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 06d4d22..08dfb82 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ This template will get you set up using ROS2 with VSCode as your IDE. -A fork of [athackst/vscode_ros2_workspace](https://github.com/athackst/vscode_ros2_workspace) with better wsl GUI support. +A fork of [athackst/vscode_ros2_workspace](https://github.com/athackst/vscode_ros2_workspace) with better wsl2 support. -## Usage +## Setup Tutorial ### Prerequisite @@ -44,10 +44,49 @@ See [docker docs](https://docs.docker.com/engine/install/). - Windows: `wsl2` 分支 - Linux x86_64: `main` 分支 +### Open the repo in vscode + +1. 使用 vscode 打开本项目目录 + + Now that you've cloned your repo onto your computer, you can open it in VSCode (File->Open Folder). + +2. 安装 vscode 插件 `Dev Container` + + 按下快捷键 `Ctrl+P` 调出 Vscode Quick Open，输入： + ``` + ext install ms-vscode-remote.remote-containers + ``` + +3. 启动 DevContainer + + 按下快捷键 `Ctrl+Shift+P`，输入 `rebuild`，选择 `Dev Containers: Rebuild and Reopen in Container` + +> [!NOTE] +> 请在打开 DevContainer 时关闭代理软件的 TUN 模式。否则会导致 vscode 插件无法自动安装。 + +4. 等待启动。第一次启动需要构筑镜像，可能会花费长达 10 分钟。 + +If you open a terminal inside VSCode (Terminal->New Terminal), you should see that your username has been changed to `ros`, and the bottom left green corner should say "Dev Container" + +![template_container](https://user-images.githubusercontent.com/6098197/91332895-adbf1500-e781-11ea-8afc-7a22a5340d4a.png) + +### Update the template with your code + +1. Specify the repositories you want to include in your workspace in `src/ros2.repos` or delete `src/ros2.repos` and develop directly within the workspace. +2. If you are using a `ros2.repos` file, import the contents `Terminal->Run Task..->import from workspace file` +3. Install dependencies `Terminal->Run Task..->install dependencies` +4. (optional) Adjust scripts to your liking. These scripts are used both within tasks and CI. + * `setup.sh` The setup commands for your code. Default to import workspace and install dependencies. + * `build.sh` The build commands for your code. Default to `--merge-install` and `--symlink-install` + * `test.sh` The test commands for your code. +5. Develop! + +## Optional Setup + ### Configurate USB passthrough (WSL Only) -> [!TIP] -> Linux 系统不需要按照此部分操作。可直接使用 USB 设备。 +若你需要在开发容器中使用 USB 设备（如工业相机、串口等），请进行以下操作。 +Linux 系统不需要按照此部分操作。可直接使用 USB 设备。 > [!NOTE] > 需要更好的解决方案。Docker Desktop 运行于一个基于 Alpine 的 WSL 镜像 `docker-desktop`，而 usbipd-win 不支持直接 attach 到 `docker-desktop` 内。[此 issue](https://github.com/dorssel/usbipd-win/issues/669) 建议安装一个单独的 Ubuntu 22.04 镜像用于接入 USB。能用但不优雅。 @@ -87,61 +126,32 @@ See [docker docs](https://docs.docker.com/engine/install/). Persisted: GUID DEVICE ``` + 记住你期望在 Docker 中使用的设备的 BUSID。 + +4. 设置默认 WSL Distro + ```powershell + wsl --set-default Ubuntu-22.04 + ``` -4. 配置穿透设备 +5. 配置待穿透设备 ```powershell usbipd bind --busid= usbipd attach --wsl --busid= ``` - 将你需要在 Docker 环境中使用的设备 BUSID 替换掉以上的 ``。例如： + **将你需要在 Docker 环境中使用的设备 BUSID 替换掉命令中的 ``。** + 例如在上述 `usbipd list` 的输出示例中，你希望将 XiaoMi USB 2.0 Webcam 映射到 Docker 中： ```powershell usbipd bind --busid=3-1 ``` > [!TIP] -> 每次重启宿主机，你需要重新运行第 4 步。 +> 每次重启宿主机，你需要重新运行第 5 步。 ### Setup CUDA -在宿主机上安装普通 CUDA 即可。Docker 镜像中已内置 CUDA。 -不需要安装 CUDA for WSL2 或在 WSL2 中安装 CUDA。 -```powershell -winget install -e --id Nvidia.CUDA -v 11.8 -``` - -### Open the repo in vscode - -Now that you've cloned your repo onto your computer, you can open it in VSCode (File->Open Folder). - -> [!NOTE] -> 请在打开 DevContainer 时关闭代理软件的 TUN 模式。否则会导致 vscode 插件无法自动安装。 - -When you open it for the first time, you should see a little popup that asks you if you would like to open it in a container. Say yes! - -![template_vscode](https://user-images.githubusercontent.com/6098197/91332551-36898100-e781-11ea-9080-729964373719.png) - -If you don't see the pop-up, click on the little green square in the bottom left corner, which should bring up the container dialog - -![template_vscode_bottom](https://user-images.githubusercontent.com/6098197/91332638-5d47b780-e781-11ea-9fb6-4d134dbfc464.png) - -In the dialog, select "Remote Containers: Reopen in container" - -VSCode will build the dockerfile inside of `.devcontainer` for you. If you open a terminal inside VSCode (Terminal->New Terminal), you should see that your username has been changed to `ros`, and the bottom left green corner should say "Dev Container" - -![template_container](https://user-images.githubusercontent.com/6098197/91332895-adbf1500-e781-11ea-8afc-7a22a5340d4a.png) - -### Update the template with your code - -1. Specify the repositories you want to include in your workspace in `src/ros2.repos` or delete `src/ros2.repos` and develop directly within the workspace. -2. If you are using a `ros2.repos` file, import the contents `Terminal->Run Task..->import from workspace file` -3. Install dependencies `Terminal->Run Task..->install dependencies` -4. (optional) Adjust scripts to your liking. These scripts are used both within tasks and CI. - * `setup.sh` The setup commands for your code. Default to import workspace and install dependencies. - * `build.sh` The build commands for your code. Default to `--merge-install` and `--symlink-install` - * `test.sh` The test commands for your code. -5. Develop! - +Docker 镜像中已内置 CUDA。不需要进行任何手动配置。 +无需安装 CUDA for WSL2 或在 WSL 中安装 CUDA。 ## FAQ @@ -151,32 +161,6 @@ VSCode will build the dockerfile inside of `.devcontainer` for you. If you open 请使用 `wsl2` 分支。使用 `main` 分支会导致无法使用 GUI。 -#### I want to use vGPU - -If you want to access the vGPU through WSL2, you'll need to add additional components to the `.devcontainer/devcontainer.json` file in accordance to [these directions](https://github.com/microsoft/wslg/blob/main/samples/container/Containers.md) - -```jsonc - "runArgs": [ - "--network=host", - "--cap-add=SYS_PTRACE", - "--security-opt=seccomp:unconfined", - "--security-opt=apparmor:unconfined", - "--volume=/tmp/.X11-unix:/tmp/.X11-unix", - "--volume=/mnt/wslg:/mnt/wslg", - "--volume=/usr/lib/wsl:/usr/lib/wsl", - "--device=/dev/dxg", - "--gpus=all" - ], - "containerEnv": { - "DISPLAY": "${localEnv:DISPLAY}", // Needed for GUI try ":0" for windows - "WAYLAND_DISPLAY": "${localEnv:WAYLAND_DISPLAY}", - "XDG_RUNTIME_DIR": "${localEnv:XDG_RUNTIME_DIR}", - "PULSE_SERVER": "${localEnv:PULSE_SERVER}", - "LD_LIBRARY_PATH": "/usr/lib/wsl/lib", - "LIBGL_ALWAYS_SOFTWARE": "1" // Needed for software rendering of opengl - }, -``` - ### Repos are not showing up in VS Code source control This is likely because vscode doesn't necessarily know about other repositories unless you've added them directly.