Skip to content
This repository was archived by the owner on May 18, 2024. It is now read-only.

Commit ce44c57

Browse files
eomielanDFriend01patrick-5546
authored
Create docs page for workspace setup (#93)
* Created setup page * Added workspace index page * Added navigation items for setup page * Install prerequisites instructions re-organized * Update workspace title * Added newline to end of file * Fix links to workspace repo * Ignore distrowatch links * Changed Windows 11 logo * Make links open in new tab * Proof reading and reformatting * Fix line-length issue * Put in current project tab * Update with changes to README * Revamped setup and run pages * Add note on updating sailbot_workspace * Proofread * Proofread * Minor readability improvements * Add explanation Co-authored-by: DFriend01 <devon.fri.2000@gmail.com> Co-authored-by: Patrick Creighton <pcreighton429@gmail.com>
1 parent cfa0fde commit ce44c57

File tree

7 files changed

+271
-0
lines changed

7 files changed

+271
-0
lines changed

‎.markdown-link-check.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@
55
},
66
{
77
"pattern": "^https://docs.github.com*"
8+
},
9+
{
10+
"pattern": "^https://distrowatch.com*"
811
}
912
]
1013
}

‎.vscode/cspell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
"srcnew",
2222
"struct",
2323
"Structs",
24+
"uncrustify",
2425
"virtualenv"
2526
],
2627
// flagWords - list of words to be always considered incorrect

‎docs/current/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Current Project

‎docs/current/sailbot_workspace/overview.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Sailbot Workspace
2+
3+
This repository will get you set up to develop UBCSailbot's software on VS Code. It is based on athackst's
4+
[vscode_ros2_workspace](https://github.com/athackst/vscode_ros2_workspace){target=_blank}.
5+
See their [write-up](https://www.allisonthackston.com/articles/vscode_docker_ros2.html){target=_blank} for a more
6+
in-depth look on how this workspace functions.
7+
8+
## Features
9+
10+
### Style
11+
12+
ROS2-approved formatters are included in the IDE.
13+
14+
- **C++** uncrustify; config from `ament_uncrustify`
15+
- **Python** autopep8; vscode settings consistent with the [style guide](https://index.ros.org/doc/ros2/Contributing/Code-Style-Language-Versions/){target=_blank}
16+
17+
### Tasks
18+
19+
There are many pre-defined tasks. See
20+
[our workspace file](https://github.com/UBCSailbot/sailbot_workspace/blob/main/.devcontainer/config/sailbot_workspace.code-workspace){target=_blank}
21+
for a complete listing. Bring up the task menu by typing "Tasks: Run Task" in the command pallete, or creating a keyboard
22+
shortcut for `workbench.action.tasks.runTask`.
23+
24+
### Debugging ([WIP](https://github.com/UBCSailbot/sailbot_workspace/issues/6){target=_blank})
25+
26+
This repository has debug configurations for Python files and C++ programs. See
27+
[our workspace file](https://github.com/UBCSailbot/sailbot_workspace/blob/main/.devcontainer/config/sailbot_workspace.code-workspace){target=_blank}
28+
for configuration details.
29+
Bring up the debug configurations menu by typing "debug " in the command palette without the ">" prefix, or select one
30+
from the Run and Debug view.
31+
32+
### Continuous Integration
33+
34+
This repository also has continuous integration that lints and tests our code.
35+
See [`.github/workflows/`](https://github.com/UBCSailbot/sailbot_workspace/tree/main/.github/workflows){target=_blank}
36+
for the configuration files.
37+
38+
### Configured Terminal Commands and Aliases
39+
40+
| ROS 2 Command | ROS 1 Command | Function |
41+
| ------------- | ------------- | -------- |
42+
| `srcnew` | `srcraye` | Source ROS workspace overlay |
43+
| `colcon_cd` | `roscd` | Navigate to ROS workspace |

‎docs/current/sailbot_workspace/run.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Run Instructions
2+
3+
## Source the ROS workspace overlay
4+
5+
=== "ROS 2"
6+
7+
```
8+
srcnew
9+
```
10+
11+
=== "ROS 1"
12+
13+
```
14+
srcraye
15+
```
16+
17+
## Build
18+
19+
!!! note ""
20+
21+
This step is not necessary if no modifications to C++ code or custom msgs were made.
22+
23+
=== "ROS 2"
24+
25+
Run the "Build" VS Code task, which has the keyboard shortcut ++ctrl+shift+b++.
26+
27+
=== "ROS 1"
28+
29+
```
30+
roscd
31+
catkin_make
32+
```
33+
34+
## Run the ROS program
35+
36+
!!! tip "Running GUI applications"
37+
38+
For the operating systems that need additional software to run GUI applications like Windows 10 and MacOS,
39+
ensure that they are running beforehand.
40+
41+
=== "ROS 2"
42+
43+
`ros2 launch ...` or `ros2 run ...`
44+
45+
=== "ROS 1"
46+
47+
`roslaunch ...` or `rosrun ...`

‎docs/current/sailbot_workspace/setup.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Setup Instructions
2+
3+
This workspace can be set up on most operating systems, but it performs the best and requires the least setup on
4+
Ubuntu and [its derivatives](https://distrowatch.com/search.php?basedon=Ubuntu){target=_blank}.
5+
6+
## Install and configure prerequisites
7+
8+
### Docker
9+
10+
=== ":material-microsoft-windows: Windows"
11+
12+
1. [Install Docker Desktop](https://docs.docker.com/desktop/install/windows-install/){target=_blank}
13+
with the WSL 2 backend
14+
15+
2. Configure [WSL](https://learn.microsoft.com/en-us/windows/wsl/about){target=_blank}
16+
1. Run the commands below in an **administrator** PowerShell window
17+
18+
```powershell
19+
wsl --install --distribution Ubuntu
20+
wsl --set-default Ubuntu
21+
wsl --set-version Ubuntu 2
22+
```
23+
24+
2. Run `whoami` in the Ubuntu terminal; if it outputs `root`, create a non-root user with sudo privileges
25+
and give it full permissions to Docker
26+
1. [Create a non-root user with sudo privileges](https://www.digitalocean.com/community/tutorials/how-to-add-and-delete-users-on-ubuntu-20-04){target=_blank}
27+
2. Change the default Ubuntu user to the one you just created by entering the following command in Powershell:
28+
`ubuntu config --default-user <username>`, where `<username>` is the name of the user
29+
3. [Add the user to the Docker group](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user){target=_blank}
30+
31+
=== ":material-apple: MacOS"
32+
33+
1. [Install Docker Desktop](https://docs.docker.com/engine/install/){target=_blank}
34+
35+
=== ":material-linux: Linux"
36+
37+
1. [Install Docker Engine](https://docs.docker.com/engine/install/){target=_blank}
38+
2. [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user){target=_blank}
39+
3. [Configure Docker to start on boot](https://docs.docker.com/engine/install/linux-postinstall/#configure-docker-to-start-on-boot){target=_blank}
40+
41+
### VS Code
42+
43+
- [VS Code](https://code.visualstudio.com/){target=_blank}
44+
1. [Install VS Code](https://code.visualstudio.com/download){target=_blank}
45+
- For Arch Linux, make sure install the official Microsoft distribution;
46+
the one from Pacman doesn't work with Microsoft plugins
47+
2. [Install VS Code Remote Development Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack){target=_blank}
48+
49+
## Additional configuration to run GUI applications
50+
51+
=== ":material-microsoft-windows: Windows"
52+
53+
=== ":simple-windows11: Windows 11"
54+
55+
GUI applications work without additional configuration,
56+
**but if you upgraded from Windows 10 make sure to update the WSL kernel:** `wsl --update`
57+
in an **administrator** PowerShell window
58+
59+
=== ":material-microsoft-windows: Windows 10"
60+
61+
1. Follow [this guide](https://techcommunity.microsoft.com/t5/windows-dev-appconsult/running-wsl-gui-apps-on-windows-10/ba-p/1493242){target=_blank}
62+
up to, but not including setting the `DISPLAY` variable
63+
2. Zsh configuration
64+
1. Run the command below in your Ubuntu terminal
65+
66+
```bash
67+
echo "export DISPLAY=\"`grep nameserver /etc/resolv.conf | sed 's/nameserver //'`:0\"" >> ~/.bashrc
68+
echo 'export WIN10_DOCKER_DISPLAY_END="${DISPLAY:1}"' >> ~/.bashrc
69+
```
70+
71+
3. If VS Code is open, then restart it
72+
73+
=== ":material-apple: MacOS"
74+
75+
1. XQuartz configuration
76+
77+
1. Follow [this guide](https://gist.github.com/sorny/969fe55d85c9b0035b0109a31cbcb088){target=_blank} to setup
78+
XQuartz
79+
2. Copy the default xinitrc to your home directory
80+
81+
```zsh
82+
cp /opt/X11/etc/X11/xinit/xinitrc ~/.xinitrc
83+
```
84+
85+
3. Add `xhost +localhost` to `~/.xinitrc` after its first line
86+
4. If XQuartz is open, then restart it
87+
88+
2. Zsh configuration
89+
90+
1. Run the commands below in your MacOS terminal
91+
92+
```zsh
93+
echo 'export MAC_DOCKER_LOCALHOST="docker.for.mac.host.internal"' >> ~/.zshrc
94+
echo 'export DISPLAY=:0' >> ~/.zshrc
95+
```
96+
97+
2. If VS Code is open, then restart it
98+
99+
=== ":material-linux: Linux"
100+
101+
=== ":material-ubuntu: Ubuntu and its derivatives"
102+
103+
GUI applications should work without additional configuration.
104+
105+
=== ":material-linux: Other"
106+
107+
=== ":material-arch: Arch Linux"
108+
109+
1. Set up X11 forwarding
110+
111+
1. Install xhost
112+
113+
```bash
114+
sudo pacman -S xorg-xhost
115+
```
116+
117+
2. Run the commands below in your Linux terminal
118+
119+
```bash
120+
echo 'export DISPLAY=0.0' >> ~/.bashrc
121+
cp /etc/X11/xinit/xinitrc ~/.xinitrc
122+
```
123+
124+
3. Add `xhost +local:docker` to `~/.xinitrc` after its first line
125+
126+
??? bug "ROS 1 not working"
127+
128+
The system has trouble resolving the local hostname; run the commands below in your VS Code terminal
129+
130+
```bash
131+
echo 'export ROS_HOSTNAME=localhost' >> ~/.bashrc
132+
echo 'export ROS_MASTER_URI=http://localhost:11311' >> ~/.bashrc
133+
```
134+
135+
## Clone sailbot_workspace
136+
137+
!!! notes "Note for Windows"
138+
139+
Run the command below in the Ubuntu terminal to clone sailbot_workspace in the WSL filesystem.
140+
141+
```sh
142+
git clone https://github.com/UBCSailbot/sailbot_workspace.git
143+
```
144+
145+
## Open sailbot_workspace in VS Code
146+
147+
```sh
148+
code sailbot_workspace
149+
```
150+
151+
## Open sailbot_workspace in a Dev Container
152+
153+
1. Make sure that Docker is running
154+
2. Run the "Dev Containers: Reopen in Container" command in the VS Code command pallete
155+
156+
## Open the sailbot_workspace VS Code workspace
157+
158+
1. Open the file `.devcontainer/config/sailbot_workspace.code-workspace` in VS Code
159+
2. Click "Open Workspace"
160+
161+
## Run the VS Code task named "setup"
162+
163+
This imports the ROS packages and install their dependencies.
164+
165+
## Updating sailbot_workspace
166+
167+
When changes to the Dev container are made (any file in `.devcontainer/`), it needs to be rebuilt.
168+
This may happen when you pull the latest commits from a branch or switch branches.
169+
170+
1. Run the "Dev Containers: Rebuild Container" command in the VS Code command palette

‎mkdocs.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,12 @@ markdown_extensions:
9595
# Page tree
9696
nav:
9797
- Home: index.md
98+
- Current Project:
99+
- current/index.md
100+
- Sailbot Workspace:
101+
- Overview: current/sailbot_workspace/overview.md
102+
- Setup: current/sailbot_workspace/setup.md
103+
- Run: current/sailbot_workspace/run.md
98104
- Reference:
99105
- reference/index.md
100106
- C++:

0 commit comments

Comments
 (0)