Metadata-Version: 2.4
Name: pixi-ros
Version: 0.1.2
Summary: Pixi extension for ROS package management
Project-URL: Homepage, https://github.com/ruben-arts/pixi-ros
Project-URL: Repository, https://github.com/ruben-arts/pixi-ros
Author-email: Ruben Arts <ruben@prefix.dev>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: lxml>=5.0.0
Requires-Dist: pathspec>=0.11.0
Requires-Dist: py-rattler>=0.6.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomlkit>=0.12.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# pixi-ros

**Bridge your ROS workspace to the modern conda/Pixi ecosystem**

pixi-ros helps ROS developers transition from `rosdep` to [Pixi](https://pixi.sh) for package management.
It automatically reads your ROS workspace's `package.xml` files and generates a `pixi.toml` manifest with all dependencies resolved from conda channels (primarily [robostack](https://robostack.org/)).

## Why pixi-ros?

If you're a ROS developer, you're probably familiar with `rosdep` managing dependencies.
`pixi-ros` gives you access to a more modern package management ecosystem:

- **Reproducible environments**: Lock files ensure everyone on your team has identical dependencies
- **Cross-platform**: Works seamlessly on Linux, macOS, and Windows
- **Fast and reliable**: Uses rattler (Rust implementation of conda) for speed
- **No system dependencies**: Everything isolated in project environments

## Quick Start

### Installation

Install pixi first if you haven't already:

```bash
curl -fsSL https://pixi.sh/install.sh | bash
```

Or follow instructions at https://pixi.sh/latest/installation/

Install pixi-ros globally using pixi:

```bash
pixi global install pixi-ros
```

### Initialize Your ROS Workspace

Navigate to your ROS workspace and run:

```bash
pixi-ros init --distro humble
```

This will:
1. Discover all ROS packages in your workspace (by finding `package.xml` files)
2. Read dependencies from each `package.xml`
3. Map ROS package names to conda packages
4. Generate/update `pixi.toml` with proper channels and dependencies
5. Check package availability and warn about missing packages
6. Create helpful build/test/clean tasks

### Install and Build

After initialization, use standard pixi commands:

```bash
# Install all dependencies
pixi install

# Build your workspace
pixi run build

# Run tests
pixi run test

# Activate environment for direct ROS commands
pixi shell
```

## How It Works

### Dependency Mapping

`pixi-ros` reads all dependency types from `package.xml` files. 
It then does a best effort mapping of ROS package names to conda packages.

- **ROS packages**: `ros-{distro}-{package}` from robostack channels (e.g., `ros-humble-rclcpp`)
- **System packages**: Mapped to conda-forge equivalents (e.g., `cmake`, `eigen`)

After the mapping, it validates package availability in the configured channels. This starts a connection with `https://prefix.dev` to check if packages exist.

### Example

Given a `package.xml` with:

```xml
<depend>rclcpp</depend>
<build_depend>ament_cmake</build_depend>
<exec_depend>std_msgs</exec_depend>
```

`pixi-ros init --distro humble` generates a `pixi.toml` with:

```toml
[dependencies]
ros-humble-ament-cmake = "*"
ros-humble-rclcpp = "*"
ros-humble-std-msgs = "*"
```

## Supported ROS Distributions

- ROS 2 Humble: https://prefix.dev/robostack-humble
- ROS 2 Iron: https://prefix.dev/robostack-iron
- ROS 2 Jazzy: https://prefix.dev/robostack-jazzy
- ROS 2 Rolling: https://prefix.dev/robostack-rolling

## Command Reference

### `pixi-ros init`

Initialize or update a ROS workspace's `pixi.toml`.

```bash
pixi-ros init --distro <ros_distro>
pixi-ros init
```

**Options:**
- `--distro`, `-d`: ROS distribution (optional)

**What it does:**
- Scans workspace for `package.xml` files
- Reads all dependency types (build, exec, test)
- Maps ROS dependencies to conda packages
- Configures robostack channels
- Checks package availability
- Creates build tasks using colcon
- Generates helpful `README_PIXI.md`

**Running multiple times:**
The command is idempotent - you can run it multiple times to update dependencies as your workspace changes.

## Philosophy

`pixi-ros` aims to be a quick **gateway drug**. It:

- Respects existing ROS conventions (package.xml as source of truth)
- Uses standard ROS build tools (colcon)
- Focuses only on dependency management and environment setup
- Doesn't replace `ros2` CLI or other ROS tooling
- Should eventually become unnecessary as the ecosystem matures

Think of it as a "gateway" to help ROS developers benefit from modern package management while keeping familiar workflows.

## Project Structure

After initialization, your workspace will have:

```
workspace/
├── src/                    # Your ROS packages
│   └── my_package/
│       ├── package.xml    # ROS package manifest (source of truth)
│       └── ...
├── pixi.toml              # Generated pixi manifest
├── pixi.lock              # Locked dependencies (commit this!)
└── README_PIXI.md         # Generated usage guide
```

## Troubleshooting

### Package Not Found

If pixi-ros marks packages as "NOT FOUND":

1. Check if the package exists in robostack: https://prefix.dev/channels/robostack-{distro}
2. Check for typos in `package.xml`
3. Some packages may have different names - check mapping files
4. Consider adding the package to your workspace instead of depending on it

### Different Package Names

pixi-ros includes mapping files for system packages (e.g., `cmake` → `cmake`, `eigen` → `eigen`). You can override mappings by creating `pixi-ros/*.yaml` files in your workspace or `~/.pixi-ros/`.

### Platform-Specific Issues

Some packages have platform-specific mappings. pixi-ros handles this automatically, but you can test different platforms using the internal API with `platform_override`.

## Contributing

Contributions welcome! Feel free to open issues or PRs on GitHub.

## Learn More

- **Pixi**: https://pixi.sh
- **RoboStack**: https://robostack.org/
- **Conda**: https://docs.conda.io/
- **ROS 2**: https://docs.ros.org/

## Disclaimer

This tool is build with heavy use of AI assistance and is under active development. Please report issues or contribute on GitHub!

I (Ruben) hope `pixi-ros` can die ASAP, as all of the workflows this tool provides should ideally be native to Pixi itself. But until then, I hope this initialization tool helps you get started!
