diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 089f4d8b..dde9093c 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -1,209 +1,368 @@ # 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 +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. -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. +[Here](https://pixi.sh/dev/switching_from/conda/) is a comparison of how Pixi works when compared to Conda/Mamba -When you already have a conda installation you can install mamba with: -```bash -conda install mamba -c conda-forge -``` +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. -!!! warning "Do not install ROS packages in the `base` environment" + 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. - 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. + When you already have a conda installation you can install mamba with: + ```bash + conda install mamba -c conda-forge + ``` -!!! warning "PowerShell is not supported" + !!! warning "Do not install ROS packages in the `base` environment" - At the moment on Windows only the Command Prompt terminal is supported, while Powershell is not supported. - -## Installation ros -=== "Mamba" + 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="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 - ``` + !!! warning "PowerShell is not supported" + On Windows, Powershell is not supported, only the Command Prompt terminal is supported. + + ## Installing 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 + # 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, you must only install ONE version of ROS per environment: + === "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 + + ```bash title="Deactivate and reactivate the environment to initialize the configured ROS environment" + mamba deactivate + mamba activate ros_env + ``` - # Install ros-humble into the environment (ROS2 Humble) - mamba install ros-humble-desktop + === "Micromamba" - # Install ros-jazzy into the environment (ROS2 Jazzy) - mamba install ros-jazzy-desktop - ``` + When you only have micromamba available use the following commands: - ```bash title="Reactivate the environment to initialize the ros env" - mamba deactivate - mamba activate ros_env - ``` + === "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 -=== "Micromamba" + # 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 - When you only have micromamba available use the following commands: + # 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 - ```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 + ``` - # 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 + ## Installing tools for local development + === "Mamba" - ```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="Default tools to help with local development of ROS packages" + mamba install compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep + ``` - # Activate the environment - micromamba activate ros_env - ``` + === "Micromamba" -## Installation tools for local development -=== "Mamba" + ```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="Default tools to help with local development of ROS packages" - mamba install compilers cmake pkg-config make ninja colcon-common-extensions catkin_tools rosdep - ``` + !!! 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) + + If you use Visual Studio 2022, you must also install the command line tool (pre-included included for VS2019): + ``` + mamba install vs2022_win-64 + ``` - ```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 +=== "Pixi" + ## Install Pixi + To install `pixi` you can run the following command in your terminal: - # 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 - ``` + === "Linux & macOS" + ```bash + curl -fsSL https://pixi.sh/install.sh | bash + ``` -=== "Micromamba" + 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="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 - ``` + The script will also update your `~/.bashrc` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere. - ```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 + === "Windows" + ```bash + winget install prefix-dev.pixi + ``` - # 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 - ``` + 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. -## Testing installation -After installation you are able to run `rviz` and other ros tools. + !!! warning "PowerShell is not supported" + On Windows, Powershell is not supported, only the Command Prompt terminal is supported. -In the conda environment activation is the ROS activation included. There is no need to add a `source` command in the `~/.bashrc` + !!! 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. -=== "Mamba" - **ROS1** - ```bash title="First terminal" - mamba activate ros_env - roscore + !!! 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 ``` - ```bash title="Second terminal" - mamba activate ros_env - rviz + 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://fast.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 + #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): - **ROS2** - !!! note + #ROS noetic + pixi shell -e noetic - ROS2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. + #ROS humble + pixi shell -e humble + + #ROS jazzy + pixi shell -e jazzy - ```bash title="Terminal" - mamba activate ros_env - rviz2 ``` -=== "Micromamba" +## 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" + + **ROS1** + ```bash title="First terminal" + mamba activate ros_env + roscore + ``` + + ```bash title="Second terminal" + mamba activate ros_env + rviz + ``` + + **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" + mamba activate ros_env + rviz2 + ``` + + === "Micromamba" + + **ROS1** + ```bash title="First terminal" + micromamba activate ros_env + roscore + ``` + + ```bash title="Second terminal" + micromamba activate ros_env + rviz + ``` + + **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 + ``` +=== "Pixi" + !!! note + Remember that Pixi environments can only be activated from within your project directory. + **ROS1** ```bash title="First terminal" - micromamba activate ros_env + cd robostack + pixi shell -e noetic roscore ``` ```bash title="Second terminal" - micromamba activate ros_env + cd robostack + pixi shell -e noetic rviz ``` **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 + 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: - -=== "Mamba" - ```bash - mamba update --all - ``` + If you run into any issues or for any frequently asked questions, you can check the [FAQ page](https://robostack.github.io/FAQ.html) -=== "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. + ## Updating + Updating all packages in your environment is as easy as: -=== "Mamba" - ```bash - mamba deactivate + cd robostack + pixi update ``` -=== "Micromamba" - + ## Deactivating + You can just exit the current shell to deactivate the current environment. ```bash - micromamba deactivate + 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. ## 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}, 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