From a88b108b01818faffa19c8c86600748f04d1a070 Mon Sep 17 00:00:00 2001 From: Ted Vanderfeen <32367500+TedVanderfeen@users.noreply.github.com> Date: Wed, 12 Feb 2025 08:50:34 +1000 Subject: [PATCH 1/6] Update GettingStarted.md Changed installation > installing for clarity --- docs/GettingStarted.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 089f4d8b..e4082fde 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -1,7 +1,7 @@ # Getting Started 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/). -## Installation mamba +## Installating mamba To get started with conda (or mamba) as package managers, you need to have a base conda installation. Please do _not_ use the Anaconda installer, but rather start with [`miniforge`](https://github.com/conda-forge/miniforge) that is much more "minimal" installer. This installer will create a "base" environment that contains the package managers conda and mamba. After this installation is done, you can move on to the next steps. @@ -21,7 +21,7 @@ conda install mamba -c conda-forge At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported. -## Installation ros +## Installating ros === "Mamba" ```bash title="Prepare an environment to use the correct channels" From fc5934e8dfd3ab4da934a5e57bcac39c755dc5a2 Mon Sep 17 00:00:00 2001 From: Ted Date: Wed, 12 Feb 2025 18:25:24 +1000 Subject: [PATCH 2/6] fixed mkdocs serve not running because of changes made to the Emoji syntax --- mkdocs.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 39b66459..3e1d3db2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,9 +39,10 @@ markdown_extensions: - attr_list - pymdownx.tabbed: alternate_style: true - - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + use_directory_urls: false strict: true From 8ceff1c2d4061c91288ac35d9718b1f59d828b89 Mon Sep 17 00:00:00 2001 From: Ted Date: Wed, 12 Feb 2025 18:44:01 +1000 Subject: [PATCH 3/6] initial restructuring --- docs/GettingStarted.md | 419 ++++++++++++++++++++++++++--------------- 1 file changed, 267 insertions(+), 152 deletions(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index e4082fde..e37da9e9 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -1,206 +1,321 @@ # Getting Started -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/). -## Installating mamba +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/). +You can install Robostack using either Pixi or Mamba. +=== "Using Pixi" + ## Install Pixi + [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: -To get started with conda (or mamba) as package managers, you need to have a base conda installation. Please do _not_ use the Anaconda installer, but rather start with [`miniforge`](https://github.com/conda-forge/miniforge) that is much more "minimal" installer. This installer will create a "base" environment that contains the package managers conda and mamba. After this installation is done, you can move on to the next steps. + === "Linux/macOS" + ```bash + # Install using the official installer script + curl -fsSL https://pixi.sh/install.sh | bash -When you already have a conda installation you can install mamba with: -```bash -conda install mamba -c conda-forge -``` + # Verify the installation + pixi --version + ``` -!!! warning "Do not install ROS packages in the `base` environment" + === "Windows" + ```powershell + # Install using Windows installer script + irm https://pixi.sh/install.ps1 | iex - Make sure to _not_ install the ROS packages in your base environment as this leads to issues down the track. On the other hand, conda and mamba must not be installed in the `ros_env`, they should only be installed in base. - -!!! warning "Do not source the system ROS environment" - 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. - -!!! warning "PowerShell is not supported" - - At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported. - -## Installating ros -=== "Mamba" - - ```bash title="Prepare an environment to use the correct channels" - mamba create -n ros_env python=3.11 - mamba activate ros_env - - # this adds the conda-forge channel to the new created environment configuration - conda config --env --add channels conda-forge - # and the robostack-staging channel - conda config --env --add channels robostack-staging - # if you want to use Jazzy, also add its own channel: - conda config --env --add channels robostack-jazzy - # remove the defaults channel just in case, this might return an error if it is not in the list which is ok - conda config --env --remove channels defaults - ``` + # Verify the installation + pixi --version + ``` + !!! note + After installation, you may need to restart your terminal for the `pixi` command to be available. - ```bash title="Install ROS1 or ROS2" - # Install ros-noetic into the environment (ROS1) - mamba install ros-noetic-desktop + !!! tip "Prerequisites" + - Windows users need Visual Studio (2019 or 2022) with C++ support + - You can download them here: https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 - # Install ros-humble into the environment (ROS2 Humble) - mamba install ros-humble-desktop + ## Install RoboStack using Pixi - # Install ros-jazzy into the environment (ROS2 Jazzy) - mamba install ros-jazzy-desktop + Initialize a new project and navigate to the project directory. + ```shell + pixi init robostack + cd robostack ``` - ```bash title="Reactivate the environment to initialize the ros env" - mamba deactivate - mamba activate ros_env + Open the created pixi.toml in any text editor and paste the below configuration into the file (removing the configuration created by `pixi init`): + ``` bash title="pixi.toml" + [project] + name = "robostack" + version = "0.1.0" + description = "Development environment for RoboStack ROS packages" + authors = ["Your Name "] + channels = ["https://prefix.dev/conda-forge"] + platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"] + + [target.win-64.dependencies] + # if using Windows, uncomment ONE Visual Studio version: + #vs2019_win-64 = "*" # For VS 2019 + #vs2022_win-64 = "*" # For VS 2022 + + [dependencies] + python = "==3.11" + compilers = "*" + cmake = "*" + pkg-config = "*" + make = "*" + ninja = "*" + + [environments] + noetic = { features = ["noetic"] } + humble = { features = ["humble"] } + jazzy = { features = ["jazzy"] } + + #noetic + [feature.noetic] + #channels = ["https://prefix.dev/robostack-noetic"] + channels = ["https://prefix.dev/robostack-staging"] ##TODO Remove staging once robostack-noetic is available in the prefix.dev catalog + + [feature.noetic.dependencies] + ros-noetic-desktop = "*" + catkin_tools = "*" + rosdep = "*" + + #humble + [feature.humble] + channels = ["https://prefix.dev/robostack-humble"] + + [feature.humble.dependencies] + ros-humble-desktop = "*" + colcon-common-extensions = "*" + rosdep = "*" + + #jazzy + [feature.jazzy] + channels = ["https://prefix.dev/robostack-jazzy"] + + [feature.jazzy.dependencies] + ros-jazzy-desktop = "*" + colcon-common-extensions = "*" + rosdep = "*" ``` + ```bash + #Save and exit + #You can now start an environment with your desired robostack distribution using one of the below commands (must be in the project directory): -=== "Micromamba" + #ROS noetic + pixi shell -e noetic - When you only have micromamba available use the following commands: + #ROS humble + pixi shell -e humble - ```bash title="ROS1 Noetic" - # Create a ros-noetic desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-staging ros-noetic-desktop python=3.11 + #ROS jazzy + pixi shell -e jazzy - # Activate the environment - micromamba activate ros_env ``` + + ## Testing installation + After installation you are able to run `rviz` and other ros tools. - ```bash title="ROS2 Humble" - # Create a ros-humble desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-staging ros-humble-desktop + In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc` - ```bash title="ROS2 Jazzy" - # Create a ros-jazzy desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop - # Activate the environment - micromamba activate ros_env - ``` +=== "Using Mamba" + ## Install Mamba + To get started, you'll need a base conda installation. We recommend using the [`miniforge`](https://github.com/conda-forge/miniforge) installer. -## Installation tools for local development -=== "Mamba" + To get started with conda (or mamba) as package managers, you need to have a base conda installation. Please do _not_ use the Anaconda installer, but rather start with [`miniforge`](https://github.com/conda-forge/miniforge) that is much more "minimal" installer. This installer will create a "base" environment that contains the package managers conda and mamba. After this installation is done, you can move on to the next steps. - ```bash title="Default tools to help with local development of ROS packages" - mamba install compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep - ``` - - ```bash title="Additional dependencies for developing on windows" - # Install Visual Studio 2017, 2019 or 2022 with C++ support - # see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 - - # Install the Visual Studio command prompt - if you use Visual Studio 2019: - mamba install vs2019_win-64 - - # Install the Visual Studio command prompt - if you use Visual Studio 2022: - mamba install vs2022_win-64 + When you already have a conda installation you can install mamba with: + ```bash + conda install mamba -c conda-forge ``` -=== "Micromamba" + !!! warning "Do not install ROS packages in the `base` environment" - ```bash title="Default tools to help with local development of ROS packages" - micromamba install -c conda-forge compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep - ``` + Make sure to _not_ install the ROS packages in your base environment as this leads to issues down the track. On the other hand, conda and mamba must not be installed in the `ros_env`, they should only be installed in base. + + !!! warning "Do not source the system ROS environment" + 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. - ```bash title="Additional dependencies for developing on windows" - # Install Visual Studio 2017 or 2019 with C++ support - # see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 + !!! warning "PowerShell is not supported" - # Install the Visual Studio command prompt - if you use Visual Studio 2019: - micromamba install vs2019_win-64 + At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported. - # Install the Visual Studio command prompt - if you use Visual Studio 2022: - micromamba install vs2022_win-64 - ``` - + ## Installing ros + === "Mamba" -## Testing installation -After installation you are able to run `rviz` and other ros tools. + ```bash title="Prepare an environment to use the correct channels" + mamba create -n ros_env python=3.11 + mamba activate ros_env -In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc` + # this adds the conda-forge channel to the new created environment configuration + conda config --env --add channels conda-forge + # and the robostack-staging channel + conda config --env --add channels robostack-staging + # if you want to use Jazzy, also add its own channel: + conda config --env --add channels robostack-jazzy + # remove the defaults channel just in case, this might return an error if it is not in the list which is ok + conda config --env --remove channels defaults + ``` -=== "Mamba" - **ROS1** - ```bash title="First terminal" - mamba activate ros_env - roscore - ``` + ```bash title="Install ROS1 or ROS2" + # Install ros-noetic into the environment (ROS1) + mamba install ros-noetic-desktop - ```bash title="Second terminal" - mamba activate ros_env - rviz - ``` + # Install ros-humble into the environment (ROS2 Humble) + mamba install ros-humble-desktop - **ROS2** - !!! note + # Install ros-jazzy into the environment (ROS2 Jazzy) + mamba install ros-jazzy-desktop + ``` - ROS2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. + ```bash title="Reactivate the environment to initialize the ros env" + mamba deactivate + mamba activate ros_env + ``` - ```bash title="Terminal" - mamba activate ros_env - rviz2 - ``` + === "Micromamba" + + When you only have micromamba available use the following commands: -=== "Micromamba" - - **ROS1** - ```bash title="First terminal" - micromamba activate ros_env - roscore - ``` + ```bash title="ROS1 Noetic" + # Create a ros-noetic desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-staging ros-noetic-desktop python=3.11 - ```bash title="Second terminal" - micromamba activate ros_env - rviz - ``` + # Activate the environment + micromamba activate ros_env + ``` - **ROS2** - !!! note + ```bash title="ROS2 Humble" + # Create a ros-humble desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-staging ros-humble-desktop - ROS2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. + ```bash title="ROS2 Jazzy" + # Create a ros-jazzy desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop - ```bash title="Terminal" - micromamba activate ros_env - rviz2 - ``` + # Activate the environment + micromamba activate ros_env + ``` -If you run into any issues or for any frequently asked questions, you can check the [FAQ page](https://robostack.github.io/FAQ.html) + ## Installation tools for local development + === "Mamba" -## Updating -Updating all packages in your environment is as easy as: + ```bash title="Default tools to help with local development of ROS packages" + mamba install compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep + ``` -=== "Mamba" - - ```bash - mamba update --all - ``` + ```bash title="Additional dependencies for developing on windows" + # Install Visual Studio 2017, 2019 or 2022 with C++ support + # see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 + + # Install the Visual Studio command prompt - if you use Visual Studio 2019: + mamba install vs2019_win-64 + + # Install the Visual Studio command prompt - if you use Visual Studio 2022: + mamba install vs2022_win-64 + ``` + + === "Micromamba" + + ```bash title="Default tools to help with local development of ROS packages" + micromamba install -c conda-forge compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep + ``` + + ```bash title="Additional dependencies for developing on windows" + # Install Visual Studio 2017 or 2019 with C++ support + # see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 + + # Install the Visual Studio command prompt - if you use Visual Studio 2019: + micromamba install vs2019_win-64 + + # Install the Visual Studio command prompt - if you use Visual Studio 2022: + micromamba install vs2022_win-64 + ``` + + ## Testing installation + After installation you are able to run `rviz` and other ros tools. + + In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc` + + === "Mamba" + + **ROS1** + ```bash title="First terminal" + mamba activate ros_env + roscore + ``` + + ```bash title="Second terminal" + mamba activate ros_env + rviz + ``` + + **ROS2** + !!! note -=== "Micromamba" - - ```bash - micromamba update --all - ``` + ROS2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. + ```bash title="Terminal" + mamba activate ros_env + rviz2 + ``` -## Deactivating -The (de)activation of the ros workspace goes in together with the conda environment. So running the corresponding (de)activation command will also (un)source the ros environment. + === "Micromamba" + + **ROS1** + ```bash title="First terminal" + micromamba activate ros_env + roscore + ``` -=== "Mamba" - - ```bash - mamba deactivate - ``` + ```bash title="Second terminal" + micromamba activate ros_env + rviz + ``` -=== "Micromamba" - - ```bash - micromamba deactivate - ``` + **ROS2** + !!! note + + ROS2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. + + ```bash title="Terminal" + micromamba activate ros_env + rviz2 + ``` + + If you run into any issues or for any frequently asked questions, you can check the [FAQ page](https://robostack.github.io/FAQ.html) + + ## Updating + Updating all packages in your environment is as easy as: + + === "Mamba" + + ```bash + mamba update --all + ``` + + === "Micromamba" + + ```bash + micromamba update --all + ``` + + ## Deactivating + The (de)activation of the ros workspace goes in together with the conda environment. So running the corresponding (de)activation command will also (un)source the ros environment. + + === "Mamba" + + ```bash + mamba deactivate + ``` + + === "Micromamba" + + ```bash + micromamba deactivate + ``` -## Why ROS and Conda? -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. + ## Why ROS and Conda? + 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. ## Attribution If you use RoboStack in your academic work, please refer to the following paper: From a9d33a37cc83f79b7b180a19cfd6eba16e07f0ad Mon Sep 17 00:00:00 2001 From: Ted Date: Thu, 13 Feb 2025 17:32:40 +1000 Subject: [PATCH 4/6] almost done. Just tweaking some commands/processes --- docs/GettingStarted.md | 215 ++++++++++++++++++++++++----------------- 1 file changed, 127 insertions(+), 88 deletions(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index e37da9e9..40e23c07 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -2,34 +2,45 @@ 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/). You can install Robostack using either Pixi or Mamba. -=== "Using Pixi" +=== "Pixi" + [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. ## Install Pixi - [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: + To install `pixi` you can run the following command in your terminal: - === "Linux/macOS" + === "Linux & macOS" ```bash - # Install using the official installer script curl -fsSL https://pixi.sh/install.sh | bash - - # Verify the installation - pixi --version ``` - === "Windows" - ```powershell - # Install using Windows installer script - irm https://pixi.sh/install.ps1 | iex + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`. + If this directory does not already exist, the script will create it. - # Verify the installation - pixi --version + The script will also update your `~/.bashrc` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere. + + === "Windows" + ```bash + winget install prefix-dev.pixi ``` + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`. + If this directory does not already exist, the script will create it. + + The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere. + + !!! warning "PowerShell is not supported" + At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported. + + !!! tip "Prerequisites" + - Windows users need Visual Studio (2019 or 2022) with C++ support + - 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) + + !!! note After installation, you may need to restart your terminal for the `pixi` command to be available. + + !!! warning "Do not source the system ROS environment" + 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. - !!! tip "Prerequisites" - - Windows users need Visual Studio (2019 or 2022) with C++ support - - You can download them here: https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 ## Install RoboStack using Pixi @@ -50,9 +61,7 @@ You can install Robostack using either Pixi or Mamba. platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"] [target.win-64.dependencies] - # if using Windows, uncomment ONE Visual Studio version: - #vs2019_win-64 = "*" # For VS 2019 - #vs2022_win-64 = "*" # For VS 2022 + #vs2022_win-64 = "*" #Uncomment if using Visual Studio 2022 [dependencies] python = "==3.11" @@ -109,14 +118,9 @@ You can install Robostack using either Pixi or Mamba. pixi shell -e jazzy ``` - - ## Testing installation - After installation you are able to run `rviz` and other ros tools. - In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc` - -=== "Using Mamba" +=== "Mamba" ## Install Mamba To get started, you'll need a base conda installation. We recommend using the [`miniforge`](https://github.com/conda-forge/miniforge) installer. @@ -147,27 +151,29 @@ You can install Robostack using either Pixi or Mamba. # this adds the conda-forge channel to the new created environment configuration conda config --env --add channels conda-forge - # and the robostack-staging channel - conda config --env --add channels robostack-staging - # if you want to use Jazzy, also add its own channel: - conda config --env --add channels robostack-jazzy # remove the defaults channel just in case, this might return an error if it is not in the list which is ok conda config --env --remove channels defaults ``` + !!! note + There are different channels depending on the version of ROS that you want to install: + === "ROS1 Noetic" + ``` + conda config --env --add channels robostack-noetic + mamba install ros-noetic-desktop + ``` + === "ROS2 Humble" + ``` + conda config --env --add channels robostack-humble + mamba install ros-humble-desktop + ``` + === "ROS2 Jazzy" + ``` + conda config --env --add channels robostack-jazzy + mamba install ros-jazzy-desktop + ``` - - ```bash title="Install ROS1 or ROS2" - # Install ros-noetic into the environment (ROS1) - mamba install ros-noetic-desktop - - # Install ros-humble into the environment (ROS2 Humble) - mamba install ros-humble-desktop - - # Install ros-jazzy into the environment (ROS2 Jazzy) - mamba install ros-jazzy-desktop - ``` - - ```bash title="Reactivate the environment to initialize the ros env" + + ```bash title="Deactivate and reactivate the environment to initialize the configured ROS environment" mamba deactivate mamba activate ros_env ``` @@ -176,66 +182,99 @@ You can install Robostack using either Pixi or Mamba. When you only have micromamba available use the following commands: - ```bash title="ROS1 Noetic" - # Create a ros-noetic desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-staging ros-noetic-desktop python=3.11 - - # Activate the environment - micromamba activate ros_env - ``` - - ```bash title="ROS2 Humble" - # Create a ros-humble desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-staging ros-humble-desktop - - ```bash title="ROS2 Jazzy" - # Create a ros-jazzy desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop - - # Activate the environment - micromamba activate ros_env - ``` - - ## Installation tools for local development + === "ROS1 Noetic" + ``` + # Create a ros-noetic desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-noetic ros-noetic-desktop python=3.11 + + # Activate the environment + micromamba activate ros_env + ``` + === "ROS2 Humble" + ``` + # Create a ros-humble desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-humble ros-humble-desktop + + # Activate the environment + micromamba activate ros_env + ``` + === "ROS2 Jazzy" + ``` + # Create a ros-jazzy desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop + + # Activate the environment + micromamba activate ros_env + ``` + + + ## Installatiing tools for local development === "Mamba" ```bash title="Default tools to help with local development of ROS packages" mamba install compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep ``` - ```bash title="Additional dependencies for developing on windows" - # Install Visual Studio 2017, 2019 or 2022 with C++ support - # see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 - - # Install the Visual Studio command prompt - if you use Visual Studio 2019: - mamba install vs2019_win-64 - - # Install the Visual Studio command prompt - if you use Visual Studio 2022: - mamba install vs2022_win-64 - ``` - === "Micromamba" ```bash title="Default tools to help with local development of ROS packages" micromamba install -c conda-forge compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep ``` - ```bash title="Additional dependencies for developing on windows" - # Install Visual Studio 2017 or 2019 with C++ support - # see https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-160 - - # Install the Visual Studio command prompt - if you use Visual Studio 2019: - micromamba install vs2019_win-64 + !!! tip "Developing on Windows" + - Windows users also need Visual Studio (2019 or 2022) with C++ support + - 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) - # Install the Visual Studio command prompt - if you use Visual Studio 2022: - micromamba install vs2022_win-64 + If you use Visual Studio 2022, you must also install the command line tool (pre-included included for VS2019): + ``` + mamba install vs2022_win-64 ``` - ## Testing installation - After installation you are able to run `rviz` and other ros tools. +## Testing installation +After installation, you should test if you are able to run `rviz` and other ros tools. + +!!! note + The ROS environment activation is included automatically. There is no need to add a `source` command in the `~/.bashrc` + +=== "Pixi" + **ROS1** + ```bash title="First terminal" + cd robostack + pixi shell -e noetic + roscore + ``` + + ```bash title="Second terminal" + cd robostack + pixi shell -e noetic + rviz + ``` - In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc` + **ROS2** + ```bash title="Terminal" + cd robostack + pixi shell -e humble #OR jazzy + rviz2 + ``` + + !!! note + Remember that Pixi environments can only be activated from within your project directory. + + ## Updating + Updating all packages in your environment is as easy as: + + ```bash + cd robostack + pixi update + ``` + + ## Deactivating + You can just exit the current shell to deactivate the current environment. + ```bash + exit # or press Ctrl+D + ``` +=== "Mamba" === "Mamba" **ROS1** @@ -314,11 +353,11 @@ You can install Robostack using either Pixi or Mamba. micromamba deactivate ``` - ## Why ROS and Conda? - 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. +## Why ROS and Conda? +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. ## Attribution -If you use RoboStack in your academic work, please refer to the following paper: +If you use RoboStack in your academic work, please reference the following paper: ```bibtex @article{FischerRAM2021, title={A RoboStack Tutorial: Using the Robot Operating System Alongside the Conda and Jupyter Data Science Ecosystems}, From d391c720cfc5778588d7c397ebe5e3a6166da719 Mon Sep 17 00:00:00 2001 From: Ted Date: Thu, 13 Feb 2025 18:00:48 +1000 Subject: [PATCH 5/6] fixed some last typos and added clarity for pixi --- docs/GettingStarted.md | 306 +++++++++++++++++++++-------------------- 1 file changed, 155 insertions(+), 151 deletions(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 40e23c07..1e777f43 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -1,125 +1,11 @@ # Getting Started -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/). -You can install Robostack using either Pixi or Mamba. -=== "Pixi" - [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. - ## Install Pixi - To install `pixi` you can run the following command in your terminal: - - === "Linux & macOS" - ```bash - curl -fsSL https://pixi.sh/install.sh | bash - ``` - - The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`. - If this directory does not already exist, the script will create it. - - The script will also update your `~/.bashrc` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere. - - === "Windows" - ```bash - winget install prefix-dev.pixi - ``` - - The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`. - If this directory does not already exist, the script will create it. - - The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere. - - !!! warning "PowerShell is not supported" - At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported. - - !!! tip "Prerequisites" - - Windows users need Visual Studio (2019 or 2022) with C++ support - - 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) - - - !!! note - After installation, you may need to restart your terminal for the `pixi` command to be available. - - !!! warning "Do not source the system ROS environment" - 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. - - - ## Install RoboStack using Pixi - - Initialize a new project and navigate to the project directory. - ```shell - pixi init robostack - cd robostack - ``` - - Open the created pixi.toml in any text editor and paste the below configuration into the file (removing the configuration created by `pixi init`): - ``` bash title="pixi.toml" - [project] - name = "robostack" - version = "0.1.0" - description = "Development environment for RoboStack ROS packages" - authors = ["Your Name "] - channels = ["https://prefix.dev/conda-forge"] - platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"] - - [target.win-64.dependencies] - #vs2022_win-64 = "*" #Uncomment if using Visual Studio 2022 - - [dependencies] - python = "==3.11" - compilers = "*" - cmake = "*" - pkg-config = "*" - make = "*" - ninja = "*" - - [environments] - noetic = { features = ["noetic"] } - humble = { features = ["humble"] } - jazzy = { features = ["jazzy"] } - - #noetic - [feature.noetic] - #channels = ["https://prefix.dev/robostack-noetic"] - channels = ["https://prefix.dev/robostack-staging"] ##TODO Remove staging once robostack-noetic is available in the prefix.dev catalog - - [feature.noetic.dependencies] - ros-noetic-desktop = "*" - catkin_tools = "*" - rosdep = "*" - - #humble - [feature.humble] - channels = ["https://prefix.dev/robostack-humble"] - - [feature.humble.dependencies] - ros-humble-desktop = "*" - colcon-common-extensions = "*" - rosdep = "*" - - #jazzy - [feature.jazzy] - channels = ["https://prefix.dev/robostack-jazzy"] - - [feature.jazzy.dependencies] - ros-jazzy-desktop = "*" - colcon-common-extensions = "*" - rosdep = "*" - ``` - ```bash - #Save and exit - #You can now start an environment with your desired robostack distribution using one of the below commands (must be in the project directory): - - #ROS noetic - pixi shell -e noetic - - #ROS humble - pixi shell -e humble - - #ROS jazzy - pixi shell -e jazzy - - ``` +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/). +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. +[Here](https://pixi.sh/dev/switching_from/conda/) is a comparison of how Pixi works when compared to Conda/Mamba +You can install Robostack using either Mamba or pixi. === "Mamba" ## Install Mamba 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. !!! warning "PowerShell is not supported" - At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported. + On Windows, Powershell is not supported, only the Command Prompt terminal is supported. ## Installing ros === "Mamba" @@ -155,7 +41,7 @@ You can install Robostack using either Pixi or Mamba. conda config --env --remove channels defaults ``` !!! note - There are different channels depending on the version of ROS that you want to install: + 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: === "ROS1 Noetic" ``` conda config --env --add channels robostack-noetic @@ -208,7 +94,7 @@ You can install Robostack using either Pixi or Mamba. ``` - ## Installatiing tools for local development + ## Installing tools for local development === "Mamba" ```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. mamba install vs2022_win-64 ``` -## Testing installation -After installation, you should test if you are able to run `rviz` and other ros tools. +=== "Pixi" + ## Install Pixi + To install `pixi` you can run the following command in your terminal: -!!! note - The ROS environment activation is included automatically. There is no need to add a `source` command in the `~/.bashrc` + === "Linux & macOS" + ```bash + curl -fsSL https://pixi.sh/install.sh | bash + ``` -=== "Pixi" - **ROS1** - ```bash title="First terminal" - cd robostack - pixi shell -e noetic - roscore - ``` + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`. + If this directory does not already exist, the script will create it. - ```bash title="Second terminal" - cd robostack - pixi shell -e noetic - rviz - ``` + The script will also update your `~/.bashrc` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere. + + === "Windows" + ```bash + winget install prefix-dev.pixi + ``` + + The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`. + If this directory does not already exist, the script will create it. + + The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere. + + !!! warning "PowerShell is not supported" + On Windows, Powershell is not supported, only the Command Prompt terminal is supported. + + !!! tip "Prerequisites" + - Windows users need Visual Studio (2019 or 2022) with C++ support + - 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) + - If you wish to use VS2022, you also need to uncomment the indicated line in the below pixi.toml file. - **ROS2** - ```bash title="Terminal" - cd robostack - pixi shell -e humble #OR jazzy - rviz2 - ``` !!! note - Remember that Pixi environments can only be activated from within your project directory. + After installation, you may need to restart your terminal for the `pixi` command to be available. - ## Updating - Updating all packages in your environment is as easy as: + !!! warning "Do not source the system ROS environment" + 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. - ```bash + + ## Install RoboStack using Pixi + + Initialize a new project and navigate to the project directory. + ```shell + pixi init robostack cd robostack - pixi update ``` - ## Deactivating - You can just exit the current shell to deactivate the current environment. + 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`): + ``` bash title="pixi.toml" + [project] + name = "robostack" + version = "0.1.0" + description = "Development environment for RoboStack ROS packages" + authors = ["Your Name "] + channels = ["https://prefix.dev/conda-forge"] + platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"] + + [target.win-64.dependencies] + #vs2022_win-64 = "*" #Uncomment if using Visual Studio 2022 + + [dependencies] + python = "==3.11" + compilers = "*" + cmake = "*" + pkg-config = "*" + make = "*" + ninja = "*" + + [environments] + noetic = { features = ["noetic"] } + humble = { features = ["humble"] } + jazzy = { features = ["jazzy"] } + + #noetic + [feature.noetic] + channels = ["https://prefix.dev/robostack-noetic"] + + [feature.noetic.dependencies] + ros-noetic-desktop = "*" + catkin_tools = "*" + rosdep = "*" + + #humble + [feature.humble] + channels = ["https://prefix.dev/robostack-humble"] + + [feature.humble.dependencies] + ros-humble-desktop = "*" + colcon-common-extensions = "*" + rosdep = "*" + + #jazzy + [feature.jazzy] + channels = ["https://prefix.dev/robostack-jazzy"] + + [feature.jazzy.dependencies] + ros-jazzy-desktop = "*" + colcon-common-extensions = "*" + rosdep = "*" + ``` ```bash - exit # or press Ctrl+D + #Save and exit pixi.toml + #You can now start an environment with your desired robostack distribution using one of the below commands (must be in the project directory): + + #ROS noetic + pixi shell -e noetic + + #ROS humble + pixi shell -e humble + + #ROS jazzy + pixi shell -e jazzy + ``` +## Testing installation +After installation, you should test if you are able to run `rviz` and other ros tools. + +!!! note "Reminder" + The ROS environment activation is included automatically. There is no need to add a `source` command in the `~/.bashrc` + === "Mamba" === "Mamba" @@ -352,6 +316,46 @@ After installation, you should test if you are able to run `rviz` and other ros ```bash micromamba deactivate ``` +=== "Pixi" + + !!! note + Remember that Pixi environments can only be activated from within your project directory. + + **ROS1** + ```bash title="First terminal" + cd robostack + pixi shell -e noetic + roscore + ``` + + ```bash title="Second terminal" + cd robostack + pixi shell -e noetic + rviz + ``` + + **ROS2** + ```bash title="Terminal" + cd robostack + pixi shell -e humble #OR jazzy + rviz2 + ``` + + If you run into any issues or for any frequently asked questions, you can check the [FAQ page](https://robostack.github.io/FAQ.html) + + ## Updating + Updating all packages in your environment is as easy as: + + ```bash + cd robostack + pixi update + ``` + + ## Deactivating + You can just exit the current shell to deactivate the current environment. + ```bash + exit # or press Ctrl+D + ``` ## Why ROS and Conda? 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. From 1429f9a3eb04927fa3bac1411411fa2109e60867 Mon Sep 17 00:00:00 2001 From: Ted Date: Thu, 13 Feb 2025 18:23:09 +1000 Subject: [PATCH 6/6] forgot the pixi install command... --- docs/GettingStarted.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 1e777f43..dde9093c 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -171,7 +171,7 @@ You can install Robostack using either Mamba or pixi. version = "0.1.0" description = "Development environment for RoboStack ROS packages" authors = ["Your Name "] - channels = ["https://prefix.dev/conda-forge"] + channels = ["https://fast.prefix.dev/conda-forge"] platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"] [target.win-64.dependencies] @@ -219,6 +219,7 @@ You can install Robostack using either Mamba or pixi. ``` ```bash #Save and exit pixi.toml + pixi install #You can now start an environment with your desired robostack distribution using one of the below commands (must be in the project directory): #ROS noetic @@ -320,7 +321,7 @@ After installation, you should test if you are able to run `rviz` and other ros !!! note Remember that Pixi environments can only be activated from within your project directory. - + **ROS1** ```bash title="First terminal" cd robostack