Skip to content

Commit a9d33a3

Browse files
TedVanderfeenTedVanderfeen
committed
almost done. Just tweaking some commands/processes
1 parent 8ceff1c commit a9d33a3

File tree

1 file changed

+127
-88
lines changed

1 file changed

+127
-88
lines changed

‎docs/GettingStarted.md

Lines changed: 127 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,45 @@
22

33
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/).
44
You can install Robostack using either Pixi or Mamba.
5-
=== "Using Pixi"
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.
67
## Install Pixi
7-
[Pixi](https://prefix.dev/docs/pixi/overview) is a package management tool for developers. It allows the developer to install libraries and applications in a reproducible way. Here's how to install it on your system:
8+
To install `pixi` you can run the following command in your terminal:
89

9-
=== "Linux/macOS"
10+
=== "Linux & macOS"
1011
```bash
11-
# Install using the official installer script
1212
curl -fsSL https://pixi.sh/install.sh | bash
13-
14-
# Verify the installation
15-
pixi --version
1613
```
1714

18-
=== "Windows"
19-
```powershell
20-
# Install using Windows installer script
21-
irm https://pixi.sh/install.ps1 | iex
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.
2217

23-
# Verify the installation
24-
pixi --version
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
2523
```
2624

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+
2738
!!! note
2839
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.
2943

30-
!!! tip "Prerequisites"
31-
- Windows users need Visual Studio (2019 or 2022) with C++ support
32-
- You can download them here: https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160
3344

3445
## Install RoboStack using Pixi
3546

@@ -50,9 +61,7 @@ You can install Robostack using either Pixi or Mamba.
5061
platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"]
5162

5263
[target.win-64.dependencies]
53-
# if using Windows, uncomment ONE Visual Studio version:
54-
#vs2019_win-64 = "*" # For VS 2019
55-
#vs2022_win-64 = "*" # For VS 2022
64+
#vs2022_win-64 = "*" #Uncomment if using Visual Studio 2022
5665

5766
[dependencies]
5867
python = "==3.11"
@@ -109,14 +118,9 @@ You can install Robostack using either Pixi or Mamba.
109118
pixi shell -e jazzy
110119

111120
```
112-
113-
## Testing installation
114-
After installation you are able to run `rviz` and other ros tools.
115121

116-
In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc`
117122

118-
119-
=== "Using Mamba"
123+
=== "Mamba"
120124
## Install Mamba
121125
To get started, you'll need a base conda installation. We recommend using the [`miniforge`](https://github.com/conda-forge/miniforge) installer.
122126

@@ -147,27 +151,29 @@ You can install Robostack using either Pixi or Mamba.
147151

148152
# this adds the conda-forge channel to the new created environment configuration
149153
conda config --env --add channels conda-forge
150-
# and the robostack-staging channel
151-
conda config --env --add channels robostack-staging
152-
# if you want to use Jazzy, also add its own channel:
153-
conda config --env --add channels robostack-jazzy
154154
# remove the defaults channel just in case, this might return an error if it is not in the list which is ok
155155
conda config --env --remove channels defaults
156156
```
157+
!!! note
158+
There are different channels depending on the version of ROS that you want to install:
159+
=== "ROS1 Noetic"
160+
```
161+
conda config --env --add channels robostack-noetic
162+
mamba install ros-noetic-desktop
163+
```
164+
=== "ROS2 Humble"
165+
```
166+
conda config --env --add channels robostack-humble
167+
mamba install ros-humble-desktop
168+
```
169+
=== "ROS2 Jazzy"
170+
```
171+
conda config --env --add channels robostack-jazzy
172+
mamba install ros-jazzy-desktop
173+
```
157174

158-
159-
```bash title="Install ROS1 or ROS2"
160-
# Install ros-noetic into the environment (ROS1)
161-
mamba install ros-noetic-desktop
162-
163-
# Install ros-humble into the environment (ROS2 Humble)
164-
mamba install ros-humble-desktop
165-
166-
# Install ros-jazzy into the environment (ROS2 Jazzy)
167-
mamba install ros-jazzy-desktop
168-
```
169-
170-
```bash title="Reactivate the environment to initialize the ros env"
175+
176+
```bash title="Deactivate and reactivate the environment to initialize the configured ROS environment"
171177
mamba deactivate
172178
mamba activate ros_env
173179
```
@@ -176,66 +182,99 @@ You can install Robostack using either Pixi or Mamba.
176182

177183
When you only have micromamba available use the following commands:
178184

179-
```bash title="ROS1 Noetic"
180-
# Create a ros-noetic desktop environment
181-
micromamba create -n ros_env -c conda-forge -c robostack-staging ros-noetic-desktop python=3.11
182-
183-
# Activate the environment
184-
micromamba activate ros_env
185-
```
186-
187-
```bash title="ROS2 Humble"
188-
# Create a ros-humble desktop environment
189-
micromamba create -n ros_env -c conda-forge -c robostack-staging ros-humble-desktop
190-
191-
```bash title="ROS2 Jazzy"
192-
# Create a ros-jazzy desktop environment
193-
micromamba create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop
194-
195-
# Activate the environment
196-
micromamba activate ros_env
197-
```
198-
199-
## Installation tools for local development
185+
=== "ROS1 Noetic"
186+
```
187+
# Create a ros-noetic desktop environment
188+
micromamba create -n ros_env -c conda-forge -c robostack-noetic ros-noetic-desktop python=3.11
189+
190+
# Activate the environment
191+
micromamba activate ros_env
192+
```
193+
=== "ROS2 Humble"
194+
```
195+
# Create a ros-humble desktop environment
196+
micromamba create -n ros_env -c conda-forge -c robostack-humble ros-humble-desktop
197+
198+
# Activate the environment
199+
micromamba activate ros_env
200+
```
201+
=== "ROS2 Jazzy"
202+
```
203+
# Create a ros-jazzy desktop environment
204+
micromamba create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop
205+
206+
# Activate the environment
207+
micromamba activate ros_env
208+
```
209+
210+
211+
## Installatiing tools for local development
200212
=== "Mamba"
201213

202214
```bash title="Default tools to help with local development of ROS packages"
203215
mamba install compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep
204216
```
205217

206-
```bash title="Additional dependencies for developing on windows"
207-
# Install Visual Studio 2017, 2019 or 2022 with C++ support
208-
# see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160
209-
210-
# Install the Visual Studio command prompt - if you use Visual Studio 2019:
211-
mamba install vs2019_win-64
212-
213-
# Install the Visual Studio command prompt - if you use Visual Studio 2022:
214-
mamba install vs2022_win-64
215-
```
216-
217218
=== "Micromamba"
218219

219220
```bash title="Default tools to help with local development of ROS packages"
220221
micromamba install -c conda-forge compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep
221222
```
222223

223-
```bash title="Additional dependencies for developing on windows"
224-
# Install Visual Studio 2017 or 2019 with C++ support
225-
# see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160
226-
227-
# Install the Visual Studio command prompt - if you use Visual Studio 2019:
228-
micromamba install vs2019_win-64
224+
!!! tip "Developing on Windows"
225+
- Windows users also need Visual Studio (2019 or 2022) with C++ support
226+
- 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)
229227
230-
# Install the Visual Studio command prompt - if you use Visual Studio 2022:
231-
micromamba install vs2022_win-64
228+
If you use Visual Studio 2022, you must also install the command line tool (pre-included included for VS2019):
229+
```
230+
mamba install vs2022_win-64
232231
```
233232

234-
## Testing installation
235-
After installation you are able to run `rviz` and other ros tools.
233+
## Testing installation
234+
After installation, you should test if you are able to run `rviz` and other ros tools.
235+
236+
!!! note
237+
The ROS environment activation is included automatically. There is no need to add a `source` command in the `~/.bashrc`
238+
239+
=== "Pixi"
240+
**ROS1**
241+
```bash title="First terminal"
242+
cd robostack
243+
pixi shell -e noetic
244+
roscore
245+
```
246+
247+
```bash title="Second terminal"
248+
cd robostack
249+
pixi shell -e noetic
250+
rviz
251+
```
236252

237-
In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc`
253+
**ROS2**
254+
```bash title="Terminal"
255+
cd robostack
256+
pixi shell -e humble #OR jazzy
257+
rviz2
258+
```
259+
260+
!!! note
261+
Remember that Pixi environments can only be activated from within your project directory.
262+
263+
## Updating
264+
Updating all packages in your environment is as easy as:
265+
266+
```bash
267+
cd robostack
268+
pixi update
269+
```
270+
271+
## Deactivating
272+
You can just exit the current shell to deactivate the current environment.
273+
```bash
274+
exit # or press Ctrl+D
275+
```
238276

277+
=== "Mamba"
239278
=== "Mamba"
240279

241280
**ROS1**
@@ -314,11 +353,11 @@ You can install Robostack using either Pixi or Mamba.
314353
micromamba deactivate
315354
```
316355

317-
## Why ROS and Conda?
318-
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.
356+
## Why ROS and Conda?
357+
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.
319358

320359
## Attribution
321-
If you use RoboStack in your academic work, please refer to the following paper:
360+
If you use RoboStack in your academic work, please reference the following paper:
322361
```bibtex
323362
@article{FischerRAM2021,
324363
title={A RoboStack Tutorial: Using the Robot Operating System Alongside the Conda and Jupyter Data Science Ecosystems},

0 commit comments

Comments
 (0)