diff --git a/docs/FAQ.md b/docs/FAQ.md index 579c090c..ef62efc0 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -80,3 +80,7 @@ linux = "5.15" ``` Note: Set the glibc version to match the oldest machine or robot that needs to run your project, not necessarily your personal machine. You can check a machine's version by running `ldd --version`. + +### 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. \ No newline at end of file diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 5ca7cbd9..fa79c452 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -1,511 +1,253 @@ # Getting Started -RoboStack is a bundling of ROS for Linux, macOS 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 compatability 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 packages using either [Pixi](https://pixi.sh/), [Micromamba](micromamba.md), or [conda](conda.md). +We recommend using **Pixi** for any new installations. -You can install Robostack using either Micromamba or Pixi. We recommend using Pixi for any new installations. -Note that the instructions for Conda and Micromamba are virtually identical apart from the installation. +## Install Pixi -=== "Micromamba" - ## Install Micromamba - ```bash - "${SHELL}" <(curl -L micro.mamba.pm/install.sh) - ``` - - For details, see the official [Micromamba Installation](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html#automatic-install) instructions. +To install `pixi` you can run the following command in your terminal: - By default, the installer will set up `conda-forge`, the prefix location at `~/micromamba`, and initialise shell variables in your `~/.bashrc`. To undo the changes to your `~/.bashrc`, run: - ```bash - micromamba shell deinit - ``` +=== "Linux & macOS" - Once installed, you can update micromamba with: ```bash - micromamba self-update - ``` + curl -fsSL https://pixi.sh/install.sh | bash - !!! important "Do not install ROS packages in the `base` environment" - 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. - - !!! important "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. - - ## Installing ROS - !!! note - There are different channels depending on the version of ROS that you wish to install, to add these channels and install your desired version, you can run the following: - === "ROS 1 Noetic" - ```bash - # Create a ros-noetic desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-noetic ros-noetic-desktop - # Activate the environment - micromamba activate ros_env - # Add the robostack channel to the environemnt - micromamba config append channels robostack-noetic --env - ``` - === "ROS 2 Humble" - ```bash - # 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 - # Add the robostack channel to the environemnt - micromamba config append channels robostack-humble --env - ``` - === "ROS 2 Jazzy" - ```bash - # 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 - # Add the robostack channel to the environemnt - micromamba config append channels robostack-jazzy --env - ``` - - === "ROS 2 Kilted" - ```bash - # Create a ros-kilted desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-kilted ros-kilted-desktop - # Activate the environment - micromamba activate ros_env - # Add the robostack channel to the environemnt - micromamba config append channels robostack-kilted --env - ``` - === "ROS 2 Lyrical" - ```bash - # Create a ros-lyrical desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-lyrical ros-lyrical-desktop - # Activate the environment - micromamba activate ros_env - # Add the robostack channel to the environemnt - micromamba config append channels robostack-lyrical --env - ``` - - === "ROS 2 Rolling" - ```bash - # Create a ros-rolling desktop environment - micromamba create -n ros_env -c conda-forge -c robostack-rolling ros-rolling-desktop - # Activate the environment - micromamba activate ros_env - # Add the robostack channel to the environemnt - micromamba config append channels robostack-rolling --env - ``` - - - ## Installing tools for local development - ```bash title="Default tools to help with local development of ROS packages" - micromamba activate ros_env - micromamba install -c conda-forge ros-dev-tools + # And restart the terminal ``` - !!! tip "Developing on Windows" - - Windows users also need Visual Studio 2022 with C++ support - - You can download them here: [https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170) - - -=== "Conda" - ## Install conda - To get started, you'll need a base conda installation. We recommend using the [Miniforge](https://github.com/conda-forge/miniforge) installer. - - On Debian- and RPM-based distributions, you can also use the [Debian and RPM repository for miniconda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/rpm-debian.html). To source the base environment: +=== "Windows" ```bash - source /opt/conda/etc/profile.d/conda.sh - ``` + winget install prefix-dev.pixi - !!! warning "Avoid using the `defaults` channel" - The packages from the `defaults` channel (https://www.anaconda.com), set up by Anaconda and Miniconda, are subject to the [Anaconda Terms of Service](https://www.anaconda.com/legal/terms/terms-of-service). See [Conda Package Repository and Channels](https://conda.org/blog/2024-08-14-conda-ecosystem-explained/#conda-package-repository-and-channels) for details. - - To avoid accidental violation of the Anaconda ToS, remove the `defaults` channel: - ```bash - conda config --env --remove channels defaults - ``` - - !!! important "Do not install ROS packages in the `base` environment" - 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. - - !!! important "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. - - ## Installing ROS - !!! note - There are different channels depending on the version of ROS that you wish to install, to add these channels and install your desired version, you can run the following: - === "ROS 1 Noetic" - ```bash - # Create a ros-noetic desktop environment - conda create -n ros_env -c conda-forge -c robostack-noetic ros-noetic-desktop - # Activate the environment - conda activate ros_env - # Add the robostack channel to the environemnt - conda config --env --add channels robostack-noetic - ``` - === "ROS 2 Humble" - ```bash - # Create a ros-humble desktop environment - conda create -n ros_env -c conda-forge -c robostack-humble ros-humble-desktop - # Activate the environment - conda activate ros_env - # Add the robostack channel to the environemnt - conda config --env --add channels robostack-humble - ``` - === "ROS 2 Jazzy" - ```bash - # Create a ros-jazzy desktop environment - conda create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop - # Activate the environment - conda activate ros_env - # Add the robostack channel to the environemnt - conda config --env --add channels robostack-jazzy - ``` - - === "ROS 2 Kilted" - ```bash - # Create a ros-kilted desktop environment - conda create -n ros_env -c conda-forge -c robostack-kilted ros-kilted-desktop - # Activate the environment - conda activate ros_env - # Add the robostack channel to the environemnt - conda config --env --add channels robostack-kilted - ``` - - === "ROS 2 Lyrical" - ```bash - # Create a ros-lyrical desktop environment - conda create -n ros_env -c conda-forge -c robostack-lyrical ros-lyrical-desktop - # Activate the environment - conda activate ros_env - # Add the robostack channel to the environemnt - conda config --env --add channels robostack-lyrical - ``` - - === "ROS 2 Rolling" - ```bash - # Create a ros-rolling desktop environment - conda create -n ros_env -c conda-forge -c robostack-rolling ros-rolling-desktop - # Activate the environment - conda activate ros_env - # Add the robostack channel to the environemnt - conda config --env --add channels robostack-rolling - ``` - - ## Installing tools for local development - ```bash title="Default tools to help with local development of ROS packages" - conda activate ros_env - conda install -c conda-forge ros-dev-tools + # And restart the terminal ``` - !!! tip "Developing on Windows" - - Windows users also need Visual Studio 2022 with C++ support + !!! tip "Prerequisites" + - Windows users need Visual Studio 2022 with C++ support - You can download them here: [https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170) +!!! warning "Do not source to existing `apt` installed ROS environments" + 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. -=== "Pixi" - ## 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. - - !!! tip "Prerequisites" - - Windows users need Visual Studio 2022 with C++ support - - You can download them here: [https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170) - +## Setup a workspace - !!! note - After installation, you may need to restart your terminal for the `pixi` command to be available. +Initialize a new project and navigate to the project directory. - !!! important "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. +```shell +pixi init ros_ws --channel https://prefix.dev/robostack-lyrical +cd ros_ws +``` +??? tip "What did just happen?" - ## Install RoboStack using Pixi + The `pixi init` command created a new directory called `ros_ws` and initialized a new workspace in it. It also created a `pixi.toml` file which contains the configuration for your workspace. - Initialize a new project and navigate to the project directory. - ```shell - pixi init robostack - cd robostack - ``` + The `pixi.toml` looks something like this: - 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`): - ```toml title="pixi.toml" + ```toml [workspace] - name = "robostack" - description = "Development environment for RoboStack ROS packages" - channels = ["https://prefix.dev/conda-forge"] - platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"] - - # This will automatically activate the ros workspace on activation - [target.win.activation] - scripts = ["install/setup.bat"] - - [target.unix.activation] - # For activation scripts, we use bash for Unix-like systems - scripts = ["install/setup.bash"] - - # To build you can use - `pixi run -e build ` - [feature.build.target.win-64.tasks] - build = "colcon build --merge-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DPython_FIND_VIRTUALENV=ONLY -DPython3_FIND_VIRTUALENV=ONLY" - - [feature.build.target.unix.tasks] - build = "colcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DPython_FIND_VIRTUALENV=ONLY -DPython3_FIND_VIRTUALENV=ONLY" - - # Dependencies used by all environments - [dependencies] - python = "*" - # Build tools - compilers = "*" - cmake = "*" - pkg-config = "*" - make = "*" - ninja = "*" - # ROS specific tools - rosdep = "*" - colcon-common-extensions = "*" - - [target.linux.dependencies] - libgl-devel = "*" - - # Define all the different ROS environments - # Each environment corresponds to a different ROS distribution - # and can be activated using the `pixi run/shell -e ` command. - [environments] - noetic = { features = ["noetic", "build"] } - humble = { features = ["humble", "build"] } - jazzy = { features = ["jazzy", "build"] } - kilted = { features = ["kilted", "build"] } - lyrical = { features = ["lyrical", "build"] } - rolling = { features = ["rolling", "build"] } - - ### ROS Noetic #### - [feature.noetic] - channels = ["https://prefix.dev/robostack-noetic"] - - [feature.noetic.dependencies] - ros-noetic-desktop = "*" - catkin_tools = "*" - - ### ROS Humble #### - [feature.humble] - channels = ["https://prefix.dev/robostack-humble"] - - [feature.humble.dependencies] - ros-humble-desktop = "*" - - ### ROS Jazzy #### - [feature.jazzy] - channels = ["https://prefix.dev/robostack-jazzy"] - - [feature.jazzy.dependencies] - ros-jazzy-desktop = "*" - - ### ROS Kilted #### - [feature.kilted] - channels = ["https://prefix.dev/robostack-kilted"] - - [feature.kilted.dependencies] - ros-kilted-desktop = "*" - - ### ROS Lyrical #### - [feature.lyrical] - channels = ["https://prefix.dev/robostack-lyrical"] - - [feature.lyrical.dependencies] - ros-lyrical-desktop = "*" - - ### ROS Rolling #### - [feature.rolling] - channels = ["https://prefix.dev/robostack-rolling"] - - [feature.rolling.dependencies] - ros-rolling-desktop = "*" + name = "ros_ws" + platforms = ["linux-64"] # Your platform + channels = ["https://prefix.dev/robostack-lyrical"] # The channel to use for the workspace ``` - ```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 (either executed from within the project directory or by appending `--manifest-path` and pointing to your project directory): - - # ROS noetic - pixi shell -e noetic - - # ROS humble - pixi shell -e humble - - # ROS jazzy - pixi shell -e jazzy +Now you can add the packages you need to your workspace: - # ROS kilted - pixi shell -e kilted - - # ROS lyrical - pixi shell -e lyrical - - # ROS rolling - pixi shell -e rolling - ``` +```shell +pixi add ros-lyrical-desktop +``` -## Testing installation -After installation, you should test if you are able to run `rviz`/`rviz2` and other ROS tools. +??? tip "What did just happen?" -!!! note "Reminder" - The ROS environment activation is included automatically. There is no need to add a `source` command in the `~/.bashrc` + This adds the `ros-lyrical-desktop` package to the `pixi.toml` and installs it directly. + It also created a `pixi.lock` lockfile which contains the exact versions of the packages that were installed. + Pixi adds dependencies with pinned version specifiers like `>=1.2.3,<2.0.0` which means that the lower bound is set to the version it installed but the upper bound is based on the next major version. + This is to ensure that you get the latest compatible version of the package the next time you run `pixi update`. -=== "Micromamba" - **ROS 1** - ```bash title="First terminal" - micromamba activate ros_env - roscore - ``` +Then test the installation by running: - ```bash title="Second terminal" - micromamba activate ros_env - rviz - ``` +```bash +pixi run ros2 +# OR +pixi run rviz2 +``` - **ROS 2** - !!! note - ROS 2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. +And try the talker and listener example: - ```bash title="Terminal" - micromamba activate ros_env - rviz2 - ``` +```bash title="First terminal" +pixi run ros2 run demo_nodes_cpp talker +``` - If you run into any issues or for any frequently asked questions, you can check the [FAQ page](FAQ.md) +```bash title="Second terminal" +pixi run ros2 run demo_nodes_cpp listener +``` - ## Updating - Updating all packages in your environment is as easy as: +??? tip "What did just happen?" - ```bash - micromamba update --all - ``` + `pixi run` activates the environment and runs the command you specified. + You can also use `pixi shell` to open a new shell with the environment activated. - ## 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. +## Developing local ROS packages - ```bash - micromamba deactivate - ``` +To develop ROS packages we'll need to add some development tools to the environment. +You can do this by running: -=== "Conda" - **ROS 1** - ```bash title="First terminal" - conda activate ros_env - roscore - ``` +```bash +pixi add ros-dev-tools +``` - ```bash title="Second terminal" - conda activate ros_env - rviz - ``` +Then to try this on a basic ROS package, you can create a new ROS package in the workspace and build it: - **ROS 2** - !!! note - ROS 2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. +```bash +pixi run ros2 pkg create --build-type ament_cmake --node-name my_node my_package +pixi run ros2 pkg create --build-type ament_python --node-name my_python_node my_python_package +``` - ```bash title="Terminal" - conda activate ros_env - rviz2 - ``` +```bash +pixi run colcon build +``` - If you run into any issues or for any frequently asked questions, you can check the [FAQ page](FAQ.md) +Add the `install/setup.bash` script to the activation scripts in your `pixi.toml` so that the ROS environment is automatically activated when you enter the workspace environment: - ## Updating - Updating all packages in your environment is as easy as: +=== "Linux & macOS" - ```bash - conda update --all + ```toml title="pixi.toml" + [target.unix.activation] + scripts = ["install/setup.bash"] ``` +=== "Windows" - ## 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. - - ```bash - conda deactivate + ```toml title="pixi.toml" + [target.win.activation] + scripts = ["install/setup.bat"] ``` -=== "Pixi" +After creating and building the new packages you can run the nodes in the packages: - !!! note - Remember if trying to activate the pixi from outside the project directory, provide the path to the pixi.toml with `--manifest-path`. +```bash +pixi run ros2 run my_package my_package_node +pixi run ros2 run my_python_package my_python_package_node +``` - **ROS 1** - ```bash title="First terminal" - cd robostack - pixi run -e noetic roscore - ``` - alternatively, - ```bash title="First terminal" - cd robostack - pixi shell -e noetic - roscore - ``` +## Multi ROS distro workspaces + +This workspace supports multiple ROS distros in the same workspace on multiple platforms. + +You can replace the previous `pixi.toml` or use `pixi init` to create a new workspace and then add the following content to the `pixi.toml` file: + +```toml title="pixi.toml" +[workspace] +name = "ros_ws" +description = "Development environment for RoboStack ROS packages" +channels = ["https://prefix.dev/conda-forge"] +platforms = ["linux-64", "win-64", "osx-64", "osx-arm64", "linux-aarch64"] + +# This will automatically activate the ros workspace on activation +[target.win.activation] +scripts = ["install/setup.bat"] + +[target.unix.activation] +# For activation scripts, we use bash for Unix-like systems +scripts = ["install/setup.bash"] + +# To build you can use - `pixi run -e build ` +[feature.build.target.win-64.tasks] +build = "colcon build --merge-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DPython_FIND_VIRTUALENV=ONLY -DPython3_FIND_VIRTUALENV=ONLY" + +[feature.build.target.unix.tasks] +build = "colcon build --symlink-install --cmake-args -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DPython_FIND_VIRTUALENV=ONLY -DPython3_FIND_VIRTUALENV=ONLY" + +# Dependencies used by all environments +[dependencies] +python = "*" +# Build tools +compilers = "*" +cmake = "*" +pkg-config = "*" +make = "*" +ninja = "*" +# ROS specific tools +rosdep = "*" +colcon-common-extensions = "*" + +[target.linux.dependencies] +libgl-devel = "*" + +# Define all the different ROS environments +# Each environment corresponds to a different ROS distribution +# and can be activated using the `pixi run/shell -e ` command. +[environments] +noetic = { features = ["noetic", "build"] } +humble = { features = ["humble", "build"] } +jazzy = { features = ["jazzy", "build"] } +kilted = { features = ["kilted", "build"] } +lyrical = { features = ["lyrical", "build"] } +rolling = { features = ["rolling", "build"] } + +### ROS Noetic #### +[feature.noetic] +channels = ["https://prefix.dev/robostack-noetic"] + +[feature.noetic.dependencies] +ros-noetic-desktop = "*" +catkin_tools = "*" + +### ROS Humble #### +[feature.humble] +channels = ["https://prefix.dev/robostack-humble"] + +[feature.humble.dependencies] +ros-humble-desktop = "*" + +### ROS Jazzy #### +[feature.jazzy] +channels = ["https://prefix.dev/robostack-jazzy"] + +[feature.jazzy.dependencies] +ros-jazzy-desktop = "*" + +### ROS Kilted #### +[feature.kilted] +channels = ["https://prefix.dev/robostack-kilted"] + +[feature.kilted.dependencies] +ros-kilted-desktop = "*" + +### ROS Lyrical #### +[feature.lyrical] +channels = ["https://prefix.dev/robostack-lyrical"] + +[feature.lyrical.dependencies] +ros-lyrical-desktop = "*" + +### ROS Rolling #### +[feature.rolling] +channels = ["https://prefix.dev/robostack-rolling"] + +[feature.rolling.dependencies] +ros-rolling-desktop = "*" +``` - ```bash title="Second terminal" - cd robostack - pixi run -e noetic rviz - ``` - alternatively, - ```bash title="Second terminal" - cd robostack - pixi shell -e noetic - rviz - ``` +```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 (either executed from within the project directory or by appending `--manifest-path` and pointing to your project directory): - **ROS 2** - ```bash title="Terminal" - cd robostack - pixi run -e humble rviz2 # OR jazzy, kilted, lyrical, rolling - ``` - alternatively, - ```bash title="Terminal" - cd robostack - pixi shell -e humble # OR jazzy, kilted, lyrical, rolling - rviz2 - ``` +# ROS noetic +pixi shell -e noetic - If you run into any issues or for any frequently asked questions, you can check the [FAQ page](FAQ.md) +# ROS humble +pixi shell -e humble - ## Updating - Updating all packages in your environment is as easy as: +# ROS jazzy +pixi shell -e jazzy - ```bash - cd robostack - pixi update - ``` +# ROS kilted +pixi shell -e kilted - ## Deactivating - You can just exit the current shell to deactivate the current environment. - ```bash - exit # or press Ctrl+D - ``` +# ROS lyrical +pixi shell -e lyrical -## 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 reference the following paper: -```bibtex -@article{FischerRAM2021, - title={A RoboStack Tutorial: Using the Robot Operating System Alongside the Conda and Jupyter Data Science Ecosystems}, - author={Tobias Fischer and Wolf Vollprecht and Silvio Traversaro and Sean Yen and Carlos Herrero and Michael Milford}, - journal={IEEE Robotics and Automation Magazine}, - year={2021}, - doi={10.1109/MRA.2021.3128367}, -} +# ROS rolling +pixi shell -e rolling ``` diff --git a/docs/conda.md b/docs/conda.md new file mode 100644 index 00000000..06d7904a --- /dev/null +++ b/docs/conda.md @@ -0,0 +1,144 @@ +# Install robostack packages with conda + +## First, install conda + +To get started, you'll need a base conda installation. We recommend using the [Miniforge](https://github.com/conda-forge/miniforge) installer. + +On Debian- and RPM-based distributions, you can also use the [Debian and RPM repository for miniconda](https://docs.conda.io/projects/conda/en/stable/user-guide/install/rpm-debian.html). To source the base environment: + +```bash +source /opt/conda/etc/profile.d/conda.sh +``` + +!!! warning "Avoid using the `defaults` channel" + The packages from the `defaults` channel (https://www.anaconda.com), set up by Anaconda and Miniconda, are subject to the [Anaconda Terms of Service](https://www.anaconda.com/legal/terms/terms-of-service). See [Conda Package Repository and Channels](https://conda.org/blog/2024-08-14-conda-ecosystem-explained/#conda-package-repository-and-channels) for details. + + To avoid accidental violation of the Anaconda ToS, remove the `defaults` channel: + ```bash + conda config --env --remove channels defaults + ``` + +!!! important "Do not install ROS packages in the `base` environment" + 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. + +!!! important "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. + +## Installing ROS + +!!! note + There are different channels depending on the version of ROS that you wish to install, to add these channels and install your desired version, you can run the following: +=== "ROS 1 Noetic" + ```bash + # Create a ros-noetic desktop environment + conda create -n ros_env -c conda-forge -c robostack-noetic ros-noetic-desktop + # Activate the environment + conda activate ros_env + # Add the robostack channel to the environemnt + conda config --env --add channels robostack-noetic + ``` +=== "ROS 2 Humble" + ```bash + # Create a ros-humble desktop environment + conda create -n ros_env -c conda-forge -c robostack-humble ros-humble-desktop + # Activate the environment + conda activate ros_env + # Add the robostack channel to the environemnt + conda config --env --add channels robostack-humble + ``` +=== "ROS 2 Jazzy" + ```bash + # Create a ros-jazzy desktop environment + conda create -n ros_env -c conda-forge -c robostack-jazzy ros-jazzy-desktop + # Activate the environment + conda activate ros_env + # Add the robostack channel to the environemnt + conda config --env --add channels robostack-jazzy + ``` + +=== "ROS 2 Kilted" + ```bash + # Create a ros-kilted desktop environment + conda create -n ros_env -c conda-forge -c robostack-kilted ros-kilted-desktop + # Activate the environment + conda activate ros_env + # Add the robostack channel to the environemnt + conda config --env --add channels robostack-kilted + ``` + +=== "ROS 2 Lyrical" + ```bash + # Create a ros-lyrical desktop environment + conda create -n ros_env -c conda-forge -c robostack-lyrical ros-lyrical-desktop + # Activate the environment + conda activate ros_env + # Add the robostack channel to the environemnt + conda config --env --add channels robostack-lyrical + ``` + +=== "ROS 2 Rolling" + ```bash + # Create a ros-rolling desktop environment + conda create -n ros_env -c conda-forge -c robostack-rolling ros-rolling-desktop + # Activate the environment + conda activate ros_env + # Add the robostack channel to the environemnt + conda config --env --add channels robostack-rolling + ``` + +## Installing tools for local development + +```bash title="Default tools to help with local development of ROS packages" +conda activate ros_env +conda install -c conda-forge ros-dev-tools +``` + +!!! tip "Developing on Windows" + - Windows users also need Visual Studio 2022 with C++ support + - You can download them here: [https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170) + +## Testing installation + +After installation, you should test if you are able to run `rviz`/`rviz2` 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` + +=== **ROS 1** + + ```bash title="First terminal" + conda activate ros_env + roscore + ``` + + ```bash title="Second terminal" + conda activate ros_env + rviz + ``` + +=== "ROS 2" + !!! note + ROS 2 has the benefit of not needing a `roscore`, so only a single terminal is needed to run a tool. + + ```bash title="Terminal" + conda 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: + +```bash +conda 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. + +```bash +conda deactivate +``` \ No newline at end of file diff --git a/docs/micromamba.md b/docs/micromamba.md new file mode 100644 index 00000000..33494a39 --- /dev/null +++ b/docs/micromamba.md @@ -0,0 +1,148 @@ +# Install RoboStack packages with micromamba + +## First, Install Micromamba + +```bash +"${SHELL}" <(curl -L micro.mamba.pm/install.sh) +``` + +For details, see the official [Micromamba Installation](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html#automatic-install) instructions. + +By default, the installer will set up `conda-forge`, the prefix location at `~/micromamba`, and initialise shell variables in your `~/.bashrc`. + +Once installed, you can update micromamba with: + +```bash +micromamba self-update +``` + +!!! important "Do not install ROS packages in the `base` environment" + 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. + +!!! important "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. + +## Installing ROS + +There are different channels depending on the version of ROS that you wish to install, to add these channels and install your desired version, you can run the following: + +=== "ROS 1 Noetic" + + ```bash + # Create a ros-noetic desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-noetic ros-noetic-desktop + # Activate the environment + micromamba activate ros_env + # Add the robostack channel to the environemnt + micromamba config append channels robostack-noetic --env + ``` + +=== "ROS 2 Humble" + + ```bash + # 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 + # Add the robostack channel to the environemnt + micromamba config append channels robostack-humble --env + ``` +=== "ROS 2 Jazzy" + + ```bash + # 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 + # Add the robostack channel to the environemnt + micromamba config append channels robostack-jazzy --env + ``` + +=== "ROS 2 Kilted" + + ```bash + # Create a ros-kilted desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-kilted ros-kilted-desktop + # Activate the environment + micromamba activate ros_env + # Add the robostack channel to the environemnt + micromamba config append channels robostack-kilted --env + ``` + +=== "ROS 2 Lyrical" + + ```bash + # Create a ros-lyrical desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-lyrical ros-lyrical-desktop + # Activate the environment + micromamba activate ros_env + # Add the robostack channel to the environemnt + micromamba config append channels robostack-lyrical --env + ``` + +=== "ROS 2 Rolling" + + ```bash + # Create a ros-rolling desktop environment + micromamba create -n ros_env -c conda-forge -c robostack-rolling ros-rolling-desktop + # Activate the environment + micromamba activate ros_env + # Add the robostack channel to the environemnt + micromamba config append channels robostack-rolling --env + ``` + +## Installing tools for local development + +```bash title="Default tools to help with local development of ROS packages" +micromamba activate ros_env +micromamba install -c conda-forge ros-dev-tools +``` + +!!! tip "Developing on Windows" + - Windows users also need Visual Studio 2022 with C++ support + - You can download them here: [https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-0-installation?view=msvc-170) + +## Testing installation + +After installation, you should test if you are able to run `rviz`/`rviz2` 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` + +=== "**ROS 1**" + ```bash title="First terminal" + micromamba activate ros_env + roscore + ``` + + ```bash title="Second terminal" + micromamba activate ros_env + rviz + ``` + +=== "**ROS 2**" + !!! note + ROS 2 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: + +```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. + +```bash +micromamba deactivate +``` diff --git a/zensical.toml b/zensical.toml index 9befed54..db38670b 100644 --- a/zensical.toml +++ b/zensical.toml @@ -18,8 +18,11 @@ extra_javascript = [ # The nav below only structures the documentation sidebar. nav = [ { "Overview" = "Overview.md" }, - # { "What's New" = "WhatsNew.md" }, { "Getting Started" = "GettingStarted.md" }, + { "Alternative to Pixi" = [ + { "Micromamba" = "micromamba.md" }, + { "Conda" = "conda.md" }, + ] }, { "Available Packages" = [ { "ROS1 Noetic" = "noetic.md" }, { "ROS2 Foxy" = "foxy.md" }, @@ -54,6 +57,7 @@ features = [ [project.markdown_extensions.pymdownx.inlinehilite] [project.markdown_extensions.pymdownx.snippets] [project.markdown_extensions.pymdownx.superfences] +[project.markdown_extensions.pymdownx.details] [project.markdown_extensions.pymdownx.highlight] anchor_linenums = true