Skip to content

Commit d391c72

Browse files
TedVanderfeenTedVanderfeen
committed
fixed some last typos and added clarity for pixi
1 parent a9d33a3 commit d391c72

File tree

1 file changed

+155
-151
lines changed

1 file changed

+155
-151
lines changed

‎docs/GettingStarted.md

Lines changed: 155 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,11 @@
11
# Getting Started
22

3-
RoboStack is a bundling of ROS for Linux, Mac and Windows using the [conda package manager](https://docs.conda.io/en/latest/), based on top of [conda-forge](https://conda-forge.org/).
4-
You can install Robostack using either Pixi or Mamba.
5-
=== "Pixi"
6-
[Pixi](https://prefix.dev/docs/pixi/overview) is a package management tool for developers that builds upon the conda ecosystem. [Here](https://pixi.sh/dev/switching_from/conda/) is a comparison of Pixi for those already familiar with Conda and Mamba.
7-
## Install Pixi
8-
To install `pixi` you can run the following command in your terminal:
9-
10-
=== "Linux & macOS"
11-
```bash
12-
curl -fsSL https://pixi.sh/install.sh | bash
13-
```
14-
15-
The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`.
16-
If this directory does not already exist, the script will create it.
17-
18-
The script will also update your `~/.bashrc` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere.
19-
20-
=== "Windows"
21-
```bash
22-
winget install prefix-dev.pixi
23-
```
24-
25-
The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`.
26-
If this directory does not already exist, the script will create it.
27-
28-
The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere.
29-
30-
!!! warning "PowerShell is not supported"
31-
At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported.
32-
33-
!!! tip "Prerequisites"
34-
- Windows users need Visual Studio (2019 or 2022) with C++ support
35-
- You can download them here: [https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160)
36-
37-
38-
!!! note
39-
After installation, you may need to restart your terminal for the `pixi` command to be available.
40-
41-
!!! warning "Do not source the system ROS environment"
42-
When there is an installation available of ros on the system, in non-conda environments, there will be interference with the environments. As the `PYTHONPATH` set in the setup script conflicts with the conda environment.
43-
44-
45-
## Install RoboStack using Pixi
46-
47-
Initialize a new project and navigate to the project directory.
48-
```shell
49-
pixi init robostack
50-
cd robostack
51-
```
52-
53-
Open the created pixi.toml in any text editor and paste the below configuration into the file (removing the configuration created by `pixi init`):
54-
``` bash title="pixi.toml"
55-
[project]
56-
name = "robostack"
57-
version = "0.1.0"
58-
description = "Development environment for RoboStack ROS packages"
59-
authors = ["Your Name <[email protected]>"]
60-
channels = ["https://prefix.dev/conda-forge"]
61-
platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"]
62-
63-
[target.win-64.dependencies]
64-
#vs2022_win-64 = "*" #Uncomment if using Visual Studio 2022
65-
66-
[dependencies]
67-
python = "==3.11"
68-
compilers = "*"
69-
cmake = "*"
70-
pkg-config = "*"
71-
make = "*"
72-
ninja = "*"
73-
74-
[environments]
75-
noetic = { features = ["noetic"] }
76-
humble = { features = ["humble"] }
77-
jazzy = { features = ["jazzy"] }
78-
79-
#noetic
80-
[feature.noetic]
81-
#channels = ["https://prefix.dev/robostack-noetic"]
82-
channels = ["https://prefix.dev/robostack-staging"] ##TODO Remove staging once robostack-noetic is available in the prefix.dev catalog
83-
84-
[feature.noetic.dependencies]
85-
ros-noetic-desktop = "*"
86-
catkin_tools = "*"
87-
rosdep = "*"
88-
89-
#humble
90-
[feature.humble]
91-
channels = ["https://prefix.dev/robostack-humble"]
92-
93-
[feature.humble.dependencies]
94-
ros-humble-desktop = "*"
95-
colcon-common-extensions = "*"
96-
rosdep = "*"
97-
98-
#jazzy
99-
[feature.jazzy]
100-
channels = ["https://prefix.dev/robostack-jazzy"]
101-
102-
[feature.jazzy.dependencies]
103-
ros-jazzy-desktop = "*"
104-
colcon-common-extensions = "*"
105-
rosdep = "*"
106-
```
107-
```bash
108-
#Save and exit
109-
#You can now start an environment with your desired robostack distribution using one of the below commands (must be in the project directory):
110-
111-
#ROS noetic
112-
pixi shell -e noetic
113-
114-
#ROS humble
115-
pixi shell -e humble
116-
117-
#ROS jazzy
118-
pixi shell -e jazzy
119-
120-
```
3+
RoboStack is a bundling of ROS for Linux, Mac and Windows using the [Conda package manager](https://docs.conda.io/en/latest/), based on top of [conda-forge](https://conda-forge.org/).
4+
We have also extended support to the [Pixi](https://pixi.sh/latest/) package manager, which builds upon the foundations of, and maintains compatabillity with the Conda ecosystem.
1215

6+
[Here](https://pixi.sh/dev/switching_from/conda/) is a comparison of how Pixi works when compared to Conda/Mamba
1227

8+
You can install Robostack using either Mamba or pixi.
1239
=== "Mamba"
12410
## Install Mamba
12511
To get started, you'll need a base conda installation. We recommend using the [`miniforge`](https://github.com/conda-forge/miniforge) installer.
@@ -140,7 +26,7 @@ You can install Robostack using either Pixi or Mamba.
14026

14127
!!! warning "PowerShell is not supported"
14228

143-
At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported.
29+
On Windows, Powershell is not supported, only the Command Prompt terminal is supported.
14430

14531
## Installing ros
14632
=== "Mamba"
@@ -155,7 +41,7 @@ You can install Robostack using either Pixi or Mamba.
15541
conda config --env --remove channels defaults
15642
```
15743
!!! note
158-
There are different channels depending on the version of ROS that you want to install:
44+
There are different channels depending on the version of ROS that you want to install, you must only install ONE version of ROS per environment:
15945
=== "ROS1 Noetic"
16046
```
16147
conda config --env --add channels robostack-noetic
@@ -208,7 +94,7 @@ You can install Robostack using either Pixi or Mamba.
20894
```
20995

21096

211-
## Installatiing tools for local development
97+
## Installing tools for local development
21298
=== "Mamba"
21399

214100
```bash title="Default tools to help with local development of ROS packages"
@@ -230,50 +116,128 @@ You can install Robostack using either Pixi or Mamba.
230116
mamba install vs2022_win-64
231117
```
232118

233-
## Testing installation
234-
After installation, you should test if you are able to run `rviz` and other ros tools.
119+
=== "Pixi"
120+
## Install Pixi
121+
To install `pixi` you can run the following command in your terminal:
235122

236-
!!! note
237-
The ROS environment activation is included automatically. There is no need to add a `source` command in the `~/.bashrc`
123+
=== "Linux & macOS"
124+
```bash
125+
curl -fsSL https://pixi.sh/install.sh | bash
126+
```
238127

239-
=== "Pixi"
240-
**ROS1**
241-
```bash title="First terminal"
242-
cd robostack
243-
pixi shell -e noetic
244-
roscore
245-
```
128+
The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`.
129+
If this directory does not already exist, the script will create it.
246130

247-
```bash title="Second terminal"
248-
cd robostack
249-
pixi shell -e noetic
250-
rviz
251-
```
131+
The script will also update your `~/.bashrc` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere.
132+
133+
=== "Windows"
134+
```bash
135+
winget install prefix-dev.pixi
136+
```
137+
138+
The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`.
139+
If this directory does not already exist, the script will create it.
140+
141+
The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere.
142+
143+
!!! warning "PowerShell is not supported"
144+
On Windows, Powershell is not supported, only the Command Prompt terminal is supported.
145+
146+
!!! tip "Prerequisites"
147+
- Windows users need Visual Studio (2019 or 2022) with C++ support
148+
- You can download them here: [https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160)
149+
- If you wish to use VS2022, you also need to uncomment the indicated line in the below pixi.toml file.
252150

253-
**ROS2**
254-
```bash title="Terminal"
255-
cd robostack
256-
pixi shell -e humble #OR jazzy
257-
rviz2
258-
```
259151

260152
!!! note
261-
Remember that Pixi environments can only be activated from within your project directory.
153+
After installation, you may need to restart your terminal for the `pixi` command to be available.
262154

263-
## Updating
264-
Updating all packages in your environment is as easy as:
155+
!!! warning "Do not source the system ROS environment"
156+
When there is an installation available of ROS on the system, in non-conda environments, there will be interference with the environments. As the `PYTHONPATH` set in the setup script conflicts with the conda environment.
265157

266-
```bash
158+
159+
## Install RoboStack using Pixi
160+
161+
Initialize a new project and navigate to the project directory.
162+
```shell
163+
pixi init robostack
267164
cd robostack
268-
pixi update
269165
```
270166

271-
## Deactivating
272-
You can just exit the current shell to deactivate the current environment.
167+
Open the newly created pixi.toml in your favourite text editor and paste the below configuration into the file (overwriting the configuration created by `pixi init`):
168+
``` bash title="pixi.toml"
169+
[project]
170+
name = "robostack"
171+
version = "0.1.0"
172+
description = "Development environment for RoboStack ROS packages"
173+
authors = ["Your Name <[email protected]>"]
174+
channels = ["https://prefix.dev/conda-forge"]
175+
platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"]
176+
177+
[target.win-64.dependencies]
178+
#vs2022_win-64 = "*" #Uncomment if using Visual Studio 2022
179+
180+
[dependencies]
181+
python = "==3.11"
182+
compilers = "*"
183+
cmake = "*"
184+
pkg-config = "*"
185+
make = "*"
186+
ninja = "*"
187+
188+
[environments]
189+
noetic = { features = ["noetic"] }
190+
humble = { features = ["humble"] }
191+
jazzy = { features = ["jazzy"] }
192+
193+
#noetic
194+
[feature.noetic]
195+
channels = ["https://prefix.dev/robostack-noetic"]
196+
197+
[feature.noetic.dependencies]
198+
ros-noetic-desktop = "*"
199+
catkin_tools = "*"
200+
rosdep = "*"
201+
202+
#humble
203+
[feature.humble]
204+
channels = ["https://prefix.dev/robostack-humble"]
205+
206+
[feature.humble.dependencies]
207+
ros-humble-desktop = "*"
208+
colcon-common-extensions = "*"
209+
rosdep = "*"
210+
211+
#jazzy
212+
[feature.jazzy]
213+
channels = ["https://prefix.dev/robostack-jazzy"]
214+
215+
[feature.jazzy.dependencies]
216+
ros-jazzy-desktop = "*"
217+
colcon-common-extensions = "*"
218+
rosdep = "*"
219+
```
273220
```bash
274-
exit # or press Ctrl+D
221+
#Save and exit pixi.toml
222+
#You can now start an environment with your desired robostack distribution using one of the below commands (must be in the project directory):
223+
224+
#ROS noetic
225+
pixi shell -e noetic
226+
227+
#ROS humble
228+
pixi shell -e humble
229+
230+
#ROS jazzy
231+
pixi shell -e jazzy
232+
275233
```
276234

235+
## Testing installation
236+
After installation, you should test if you are able to run `rviz` and other ros tools.
237+
238+
!!! note "Reminder"
239+
The ROS environment activation is included automatically. There is no need to add a `source` command in the `~/.bashrc`
240+
277241
=== "Mamba"
278242
=== "Mamba"
279243

@@ -352,6 +316,46 @@ After installation, you should test if you are able to run `rviz` and other ros
352316
```bash
353317
micromamba deactivate
354318
```
319+
=== "Pixi"
320+
321+
!!! note
322+
Remember that Pixi environments can only be activated from within your project directory.
323+
324+
**ROS1**
325+
```bash title="First terminal"
326+
cd robostack
327+
pixi shell -e noetic
328+
roscore
329+
```
330+
331+
```bash title="Second terminal"
332+
cd robostack
333+
pixi shell -e noetic
334+
rviz
335+
```
336+
337+
**ROS2**
338+
```bash title="Terminal"
339+
cd robostack
340+
pixi shell -e humble #OR jazzy
341+
rviz2
342+
```
343+
344+
If you run into any issues or for any frequently asked questions, you can check the [FAQ page](https://robostack.github.io/FAQ.html)
345+
346+
## Updating
347+
Updating all packages in your environment is as easy as:
348+
349+
```bash
350+
cd robostack
351+
pixi update
352+
```
353+
354+
## Deactivating
355+
You can just exit the current shell to deactivate the current environment.
356+
```bash
357+
exit # or press Ctrl+D
358+
```
355359

356360
## Why ROS and Conda?
357361
We tightly couple ROS with Conda, a cross-platform, language-agnostic package manager. We provide ROS binaries for Linux, macOS (Intel and Apple Silicon), Windows and ARM (Linux). Installing other recent packages via conda-forge side-by-side works easily, e.g. you can install TensorFlow/PyTorch in the same environment as ROS Noetic without any issues. As no system libraries are used, you can also easily install ROS Noetic on any recent Linux Distribution - including older versions of Ubuntu. As the packages are pre-built, it saves you from compiling from source, which is especially helpful on macOS and Windows. No root access is required, all packages live in your home directory. We have recently written up a paper and blog post with more information.

0 commit comments

Comments
 (0)