Preamble

These instructions were written for Pixi version 0.63.2. You can find the version you are using by running:

pixi --version

Update Pixi

To update Pixi you can run:

pixi self-update

Get a specific Pixi version

To get a specific Pixi version run:

pixi self-update --version x.y.z

Clean Pixi workspace

After a while working in the same workspace, it can get messy with old, unused, files and whatnot. To clean a Pixi workspace, run

pixi clean

inside the workspace. This command basically deletes most things in the .pixi folder in your workspace/workspace.

There is also the command

pixi clean cache

which will also clean the system Pixi cache (usually located at ~/.pixi). This means that you will need to download the packages again when working inside a Pixi workspace.

Workspace structure

The structure of your ROS + Pixi workspace should look something like this:

workspace
├─ src
│  ├─ package_a
│  │  ├─ ...
│  │  └─ pixi.toml
│  ├─ package_b
│  │  ├─ ...
│  │  └─ pixi.toml
│  └─ meta_package
│     ├─ package_c1 
│     │  ├─ ...
│     │  └─ pixi.toml
│     └─ package_c2 
│        ├─ ...
│        └─ pixi.toml
├─ ...
├─ pixi.lock
└─ pixi.toml

In the root of the workspace, you have workspace pixi.toml that specifies how the workspace should be setup. What packages should be installed and built, what tasks should be created, what platforms should be supported, how environments should be setup, and so on.

The pixi.lock describes a specific state of the workspace such that it can be replicated without having to store the complete build of the workspace. More information on the lock file can be found on the Pixi pages.

The (ROS) packages should be stored in the src folder. They can be further nested into meta packages, to group packages together, if desired. Each package should have its own pixi.toml file that contain information on how to build the package, the dependencies of the package, when it should be automatically rebuilt, and so on. More information on the package pixi.toml file can be found on the pixi-build-ros pages.

Building the workspace

The Pixi workspace does not need to be manually built like a ROS workspace. Instead, every time you run one of the Pixi commands the workspace will be built if necessary. So if you have setup everything correctly, you should never have to manually call colcon build.

Adding dependencies

First, what is a dependency. A dependency can be another ROS package, for which you can find on the Robostack pages. It can also be PyPI (pip) packages, that can be found at pypi.org, Conda packages, found at anaconda.org, Git repository, to name some.

To ensure that a needed package is installed in the workspace, it should be added as a dependency. The recommended way of doing so is by using the command:

pixi add PACKAGES...

For example:

pixi add numpy open3d ros-jazzy-rqt-gui ros-jazzy-rviz2

PyPI dependencies can be installed by adding the --pypi flag.

Read the Pixi add page for more information and/or run pixi add --help.

Removing dependencies

There is a command that does the opposite of the pixi add command, named pixi remove. As you guess, it does the opposite of what the add command does. Read the pixi remove page for more information and/or run pixi remove --help.

Find available packages

To name a few:

Robostack for ROS packages.
Anaconda for Conda packages.
PyPI for PyPI packages.
Github and similar for repositories.

Creating a ROS package

You can create a ROS package the same way you do without Pixi. After creating the package, you need to add a pixi.toml file to the package with content similar to:

[package.build.backend]
channels = ["https://prefix.dev/conda-forge"]
name = "pixi-build-ros"
version = "*"

[package.build.config]
extra-input-globs = ["**/*.py",]

[package.host-dependencies]
ros2-distro-mutex = ">=0.13,<0.14"

[package.build-dependencies]
ros2-distro-mutex = ">=0.13,<0.14"

[package.run-dependencies]
ros2-distro-mutex = ">=0.13,<0.14"

Then in the workspace pixi.toml you need to add a dependency on this package under [dependencies]:

[dependencies]
ros-jazzy-my-python-ros-pkg = { path = "src/my_python_ros_pkg" }

The prefix ros-jazzy is added automatically and needs to be there.

More information can be found at the building a ROS package Pixi page.

Mutex

The mutex seen above (ros2-distro-mutex) is necessary to pin to make sure that all your packages can be built together. Pixi uses these mutex package to ensure ABI compatibility between packages, therefore all packages need to be built using the same mutex version in order to work together. We recommend that you add this mutex to all your pixi.toml files, even the workspace file, to ensure that they all work together.

Creating a ROS node

Same as in ROS without Pixi.

Handle your ROS package's build dependencies

In ROS, dependencies of a package is listed in the package.xml manifest file. It is a good idea to update this file properly. You can find information on this on the ROS pages. It is useful to distinguish between execute dependencies (<exec_depend>) and build dependencies (<build_depend>), (there are more than these two, for example <build_export_depend>, <doc_depend>, <test_depend>, and so on). A build dependency is something needed when building a package and an execute dependency is something needed when executing a piece of code. As you do not build Python code, you can specify only execute dependency in packages that only has Python code. However, if you have packages that with ROS message files, C++ code, or similar, then you need build dependencies. The <depend> is equal to adding both <exec_depend> and <build_depend>. The execute dependencies are less strict as they can be installed after the package is built, therefore, Pixi does not necessarily check these when building a package.

Some of the dependencies in the package.xml manifest Pixi will be able to figure out by itself. However, sometimes it needs help. For this, you can add mappings (in the package's pixi.toml file) from the name specified in the package.xml manifest to a Conda package, or something. For example:

[[package.build.config.extra-package-mappings]]
python3-tqdm = { conda = ["tqdm"] }

This will tell Pixi that python3-tqdm mentioned in package.xml can be found as tqdm at Conda.

Package in src that depends on other package in src

If one of your packages depend on another of the packages in your src folder. You need to specify where they are in the dependent package's pixi.toml file, for example:

[package.host-dependencies]
...
ros-jazzy-aruco = { path = "../aruco" }
ros-jazzy-aruco-msgs = { path = "../aruco_msgs" }

[package.build-dependencies]
...
ros-jazzy-aruco = { path = "../aruco" }
ros-jazzy-aruco-msgs = { path = "../aruco_msgs" }

[package.run-dependencies]
...
ros-jazzy-aruco = { path = "../aruco" }
ros-jazzy-aruco-msgs = { path = "../aruco_msgs" }

This says that the ros-jazzy-arcuo package can be found in the folder arcuo that is one folder above the current file.

Read more on the dependency types Pixi page.

Automatic rebuild on update

In your package's pixi.toml file you can add something called extra-input-globs, that trigger automatic rebuilding of the package when a file matching these globs are modified. For example, you can add:

[package.build.config]
extra-input-globs = ["**/*.py"]

to make sure the package is rebuilt whenever a file ending with .py (i.e., Python file) is modified.

Files that you would add these for are typically:

Launch files
Config files (Rviz, parameters, etc.)
C++ files
Interface files (msg, srv, action)
...

For example:

[package.build.config]
extra-input-globs = [
  "**/*.py",
  "config/*.yaml",
  "msgs/**/*.msg",
  "srvs/**/*.srv",
]

This would check for changes to any Python file (.py), any Yaml file (.yaml) inside the config folder, any Message file (.msg) inside the msgs folder or any subfolder, and any Service file (.srv) inside the srvs folder or any subfolder.

If you do not add extra-input-globs, the changes you do to your files will not take into affect when rerunning your code, as it will still run the old code that was present last time you built.

You can read more on these on the pixi-build-ros page.

Version control

Make sure to sync both the Pixi config (pixi.toml) and the lock file (pixi.lock) with your version control system. This ensures that you can go back to any commit and install the system as it was there. Using the --frozen argument for the Pixi commands, you tell Pixi to install the workspace exactly as it was described in the lock file (for example: pixi run --frozen rviz2).

Make sure that your version control system ignores the .pixi folder. That is where Pixi stores everything for necessary for the environment, meaning this is where your packages are being built and packages are installed. It can be millions of files, taking gigabyte of space.

Autocomplete

Pixi autocomplete can be setup by running:

Bash
- ```
eval "$(pixi completion --shell bash)"
```

Zsh

autoload -Uz compinit && compinit # This line is redundant with Oh My Zsh (the next line is needed)
eval "$(pixi completion --shell zsh)"

To automate this, you can add the line(s) to your ~/.bashrc, if using Bash, or ~/.zshrc, if using Zsh.

ROS autocomplete can be enabled by running:

eval "$(register-python-argcomplete ros2)"

inside a Pixi shell (i.e., after running pixi shell).

Course packages

It is a good idea to look at how the course packages have been setup and replicate it for your own packages.

FAQ

Please ask us questions so we can add them here with answers.