docs: adding a starting point for robotics users

crates/pixi_test_utils/Cargo.toml

@@ -10,10 +10,10 @@ version = "0.1.0"
 
 [dependencies]
 chrono = { workspace = true }
-pixi_consts = { workspace = true }
 fs-err = { workspace = true }
 itertools = { workspace = true }
 miette = { workspace = true, features = ["fancy-no-backtrace"] }
+pixi_consts = { workspace = true }
 rattler_conda_types = { workspace = true }
 rattler_digest = { workspace = true }
 rattler_package_streaming = { workspace = true }

docs/robotics.md

@@ -0,0 +1,209 @@
+# Pixi for Robotics
+
+**Pixi is not only for robotics**, but it's a great fit for it!
+
+Pixi is a fast, reproducible package manager built on the conda ecosystem, and a natural fit for robotics development.
+
+If you're familiar with the traditional ROS setup, here's the mental model:
+
+- **`apt`** installs **Debian packages** from the **Ubuntu distribution**. The **official ROS apt repository** (`packages.ros.org`) is an additional channel built on top of it.
+- **Pixi** installs **conda packages** from the **[conda-forge](https://conda-forge.org) distribution**, **[RoboStack](https://robostack.github.io/)** is an additional conda channel built on top of it in exactly the same way: it repackages the ROS ecosystem as conda packages, resolving all native dependencies against `conda-forge`.
+
+The structure is identical: a base distribution (`Ubuntu` / `conda-forge`) with a ROS channel layered on top (`packages.ros.org` / `robostack-<distro>`).
+The key difference is that conda packages are cross-platform and not tied to a specific OS, so the same `pixi.toml` can work on Linux, macOS, and Windows without a system-wide install.
+
+Pixi and RoboStack are currently a Tier 3 platform in the ROS ecosystem, which means they are community-supported but not officially supported by Open Robotics.
+[Open Robotics has communicated](https://www.openrobotics.org/technology-strategy-2026) that Pixi will be part of their strategy to expand accessibility and ease of use.
+So with your help, we can grow the community and make it a first-class way to use ROS on any platform.
+
+---
+
+## Quick Start
+
+Get ROS 2 Humble running in no time:
+
+```shell
+pixi init my_ros_ws -c https://prefix.dev/robostack-humble -c https://prefix.dev/conda-forge
+cd my_ros_ws
+pixi add ros-humble-desktop
+pixi run rviz2
+```
+
+ROS 2 is installed, isolated to this workspace, and reproducible on any machine with Pixi.
+A `pixi.toml` file is created with the dependencies and channels, and a `pixi.lock` file is generated to pin exact versions.
+Use `pixi run` or `pixi shell` to activate the environment and run ROS commands.
+
+---
+
+## Why Pixi for Robotics
+
+- [x] **No system-wide ROS installation** <br>
+    All dependencies live in the workspace. New team members clone the repo and run `pixi install`. No more additional setup instructions, no version incompatibilities.
+- [x] **[Reproducible environments](workspace/lockfile.md)** <br>
+    Pixi generates a lockfile (`pixi.lock`) that pins every dependency, including transitive ones. The same environment is guaranteed on your laptop, CI, and the robot itself.
+- [x] **[Works on Linux, macOS, and Windows](workspace/multi_platform_configuration.md)** <br>
+    RoboStack supports ROS packages for Linux, macOS and Windows. A single `pixi.toml` can declare support for all three platforms simultaneously.
+- [x] **[Built-in task runner](workspace/advanced_tasks.md)** <br>
+    Define your `colcon build`, launch files, and simulation commands as named tasks in `pixi.toml`, no Makefiles or shell scripts needed.
+- [x] **Mix ROS and non-ROS dependencies** <br>
+    Python libraries, OpenCV, PyTorch, compilers, GUI's and ROS packages all managed together.
+- [x] **[Package and distribute your own nodes](build/ros.md)** <br>
+    Build your ROS packages as conda packages with the [`pixi-build-ros`](build/backends/pixi-build-ros.md) backend and publish them to a private channel.
+
+---
+
+## How Pixi Compares
+
+|                                      | `apt` | `pip`    | Docker               | **Pixi** |
+|--------------------------------------|-------|----------|----------------------|----------|
+| Installs ROS                         | ✅     | ❌        | ✅                    | ✅        |
+| Works on macOS & Windows             | ❌     | ✅        | ✅                    | ✅        |
+| Reproducible lockfile                | ❌     | ❌        | ⚠️(pre-baked images) | ✅        |
+| Per-project isolation                | ❌     | ⚠️ venvs | ✅                    | ✅        |
+| Mix C++, Python, system libs         | ✅     | ❌        | ✅                    | ✅        |
+| Native performance (no VM/container) | ✅     | ✅        | ❌                    | ✅        |
+| GUI / hardware access out of the box | ✅     | ✅        | ⚠️ (requires setup)  | ✅        |
+| Single install command for new devs  | ❌     | ❌        | ⚠️                   | ✅        |
+
+- `apt` is Debian-only and install packages globally, making it hard to run different ROS versions side by side or reproduce the exact same setup across machines.
+- `pip` can't install ROS or non-Python system libraries at all.
+- Docker gives you isolation and improves cross-platform support but adds overhead, complicates GPU and hardware access, and requires a separate toolchain.
+- Pixi gives you the package isolation and reproducibility of Docker with the native performance and hardware access of a local install, on any platform.
+
+---
+
+## Guides
+
+| Guide | Description                                                           |
+|---|-----------------------------------------------------------------------|
+| [ROS 2 Tutorial](tutorials/ros2.md) | Set up a workspace, write Python and C++ nodes, use `pixi run` tasks. |
+| [Building a ROS Package](build/ros.md) | Package your ROS nodes as conda packages based on your `package.xml`  |
+| [pixi-build-ros Backend](build/backends/pixi-build-ros.md) | Backend reference for building ROS packages.                          |
+| [GitHub Actions](integration/ci/github_actions.md) | Run your ROS tests in CI.                                             |
+| [Distributing with Pixi Pack](deployment/pixi_pack.md) | Bundle a workspace for offline or embedded deployment.                |
+
+---
+
+## RoboStack
+
+[RoboStack](https://robostack.github.io/) is the community that maintains the conda ROS packages Pixi depends on.
+
+#### Finding packages 
+
+Browse available packages for each distribution on [prefix.dev](https://prefix.dev/channels/).
+Package names follow the pattern `ros-<distro>-<package-name>`, mirroring the apt naming convention.
+There are more packages on the `prefix.dev` channels so some might normally come from `apt` or `pip` instead, but they are all available in a single place for Pixi:
+
+| `pixi`                      | `apt`                          | `pip`                                                                               |
+|-----------------------------|--------------------------------|-------------------------------------------------------------------------------------|
+| `pixi add ros-humble-rviz2` | `apt install ros-humble-rviz2` | ❌                                                                                   |
+| `pixi add opencv`           | `apt install python3-opencv`   | `pip install opencv-python`                                                         |
+| `pixi add pytorch`          | ❌                              | `pip install torch --index-url https://download.pytorch.org/whl/cpu`    |
+
+#### What to do if a package is missing
+
+Not all ROS packages are available in RoboStack yet. If you need a package that is not in the channel:
+
+- Check the [RoboStack GitHub](https://github.com/RoboStack) to see if there is an open issue or PR for it.
+- Contribute to RoboStack to add it. See the [RoboStack contributing guide](https://robostack.github.io/Contributing.html).
+- Package it yourself with Pixi using the [`pixi-build-ros` backend](build/backends/pixi-build-ros.md) and publish it to your own conda channel.
+
+#### `rosdep` is not supported
+
+`rosdep` calls `apt` or `pip` under the hood, which bypasses Pixi's environment.
+Use `pixi add` to add any missing dependencies instead.
+
+#### `pixi-ros`
+
+[`pixi-ros`](https://github.com/ruben-arts/pixi-ros) can be used to quickstart a ROS workspace.
+This project can initialize a workspace with the correct RoboStack channels and ROS dependencies, and generate `pixi.toml` files for ROS packages.
+
+```shell
+# Install the pixi-ros CLI tool globally
+pixi global install pixi-ros
+# Move to your existing ros workspace that contains the src folder
+cd ros_ws
+# Initialize the workspace
+pixi ros init
+```
+
+This will initialize a `pixi.toml` based on the `package.xml` files in your `src` folder, and add the necessary RoboStack channel automatically.
+
+---
+
+## Common Patterns
+
+### Multi-machine workspace
+
+Share the exact same environment across development machines and the robot:
+
+```toml title="pixi.toml"
+[workspace]
+channels = ["https://prefix.dev/robostack-humble", "https://prefix.dev/conda-forge"]
+platforms = ["linux-64", "osx-arm64"]
+
+[dependencies]
+ros-humble-desktop = "*"
+colcon-common-extensions = "*"
+```
+
+### Using Pixi with colcon
+Assuming you have a workspace with a `src` folder containing your ROS packages, you can define the following manifest in the root of your workspace:
+```toml title="pixi.toml"
+[workspace]
+channels = ["https://prefix.dev/robostack-humble", "https://prefix.dev/conda-forge"]
+platforms = ["linux-64", "osx-arm64", "win-64"]
+
+[dependencies]
+ros-humble-desktop = "*"
+colcon-common-extensions = "*"
+
+[tasks]
+# A simple colcon build task
+build = "colcon build --symlink-install"
+
+[activation]
+# After you use colcon to build your workspace, Pixi has to source the setup script to make the new packages available in the environment
+scripts = ["install/setup.sh"]
+```
+
+The activation scripts will be run on `pixi run` or `pixi shell`, so after the first build, you can run your ROS nodes with `pixi run` without needing to source the setup script manually.
+
+
+### Automate your workflow with tasks
+
+```toml title="pixi.toml"
+[tasks]
+# A simple alias for running the turtlesim simulator
+sim   = "ros2 run turtlesim turtlesim_node"
+# Use inputs to cache the build task and only rerun it when files in src change
+build = {cmd = "colcon build --symlink-install", inputs = ["src"]}
+# A task that depends on the build task, so it will only run after a successful build
+run   = {cmd = "ros2 run my_package my_node", depends-on = ["build"]}
+```
+
+```shell
+pixi run sim
+pixi run run
+```
+`run` runs both the `build` and `run` commands in sequence, but if you run it again without changing any files in `src`, it will skip the build step since the inputs haven't changed.
+
+### Mixing ROS with Python ML libraries
+
+```shell
+# Tell pixi that it can install CUDA dependencies in this workspace
+pixi workspace system-requirements add cuda 12
+
+# (re)install ROS and your ML dependencies together
+pixi add ros-humble-desktop pytorch torchvision opencv
+```
+
+---
+
+## Community & Support
+
+- [Pixi Discord](https://discord.gg/kKV8ZxyzY4): get help and share your projects
+- [conda-forge](https://conda-forge.org/): the conda distribution Pixi is built on, with thousands of packages
+- [RoboStack](https://robostack.github.io/): the conda channel that packages ROS for Pixi
+- [Pixi GitHub](https://github.com/prefix-dev/pixi): report issues, contribute, and follow development
+

mkdocs.yml

@@ -105,6 +105,7 @@ extra:
 
 nav:
   - Home: index.md
+  - Robotics: robotics.md
   - Getting Started:
       - Installation: installation.md
       - First Workspace: first_workspace.md
@@ -310,6 +311,7 @@ plugins:
           - installation.md
           - getting_started.md
           - first_workspace.md
+          - robotics.md
         Tutorials documentation:
           - python/*.md
           - tutorials/*.md