> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Installation

> Install the roboticks PyPI package and the roboticks_cpp ament_cmake package. ROS2 distro matrix, Python version matrix, optional extras.

# Installation

The SDK ships two packages. Install both, just one, or neither — depending on your test stack.

## Python: `pip install roboticks`

```bash theme={null}
pip install roboticks
```

For MCAP recording (optional, pulls in `mcap` and `mcap-ros2-support`):

```bash theme={null}
pip install 'roboticks[mcap]'
```

All extras:

| Extra  | What it adds                           | When                    |
| ------ | -------------------------------------- | ----------------------- |
| `mcap` | `mcap`, `mcap-ros2-support`            | You use `mcap_capture`  |
| `dev`  | `pytest`, `pytest-cov`, `ruff`, `mypy` | Contributing to the SDK |

The base install has no ROS2 dependency — see [ROS-version-agnostic](#ros-version-agnostic) below.

### In a colcon workspace

Add to your test package's `package.xml`:

```xml theme={null}
<test_depend>python3-roboticks-pip</test_depend>
```

…or, more pragmatically for a private workspace, install via `pip` into the colcon environment:

```bash theme={null}
source /opt/ros/humble/setup.bash
python3 -m pip install --user 'roboticks[mcap]'
```

### In a virtualenv

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
pip install 'roboticks[mcap]' pytest pytest-cov
```

The pytest plugin loads via the `pytest11` entry point — no `conftest.py` changes required. Verify with:

```bash theme={null}
pytest --trace-config 2>&1 | grep roboticks
# > active plugins: roboticks-0.1.0 at .../roboticks/pytest_plugin.py
```

## C++: ament\_cmake on `roboticks_cpp`

The C++ package is shipped via the ROS2 build farm (rosdep keys land on Humble, Iron, Rolling). For private workspaces, also vendor it as a submodule.

### Via rosdep

Add to `package.xml`:

```xml theme={null}
<test_depend>roboticks_cpp</test_depend>
```

Then:

```bash theme={null}
rosdep install --from-paths src --ignore-src -r -y
colcon build
```

### Vendored

```bash theme={null}
cd src/
git submodule add https://github.com/roboticks-io/roboticks-sdk.git roboticks-sdk
# expose the cpp/ subtree to colcon
ln -s roboticks-sdk/cpp roboticks_cpp
colcon build
```

### CMakeLists.txt

```cmake theme={null}
find_package(roboticks_cpp REQUIRED)

if(BUILD_TESTING)
  find_package(ament_cmake_gtest REQUIRED)
  ament_add_gtest(my_tests test/my_tests.cpp)
  target_link_libraries(my_tests roboticks_cpp::roboticks_cpp)
endif()
```

See [C++ reference](/sdk/cpp-reference) for the available targets (`roboticks_cpp::roboticks_cpp`, `roboticks_cpp::gtest_main`).

## ROS2 distro matrix

| ROS2 distro           | Python    | `roboticks`                 | `roboticks_cpp` |
| --------------------- | --------- | --------------------------- | --------------- |
| Humble (Ubuntu 22.04) | 3.10      | supported                   | supported       |
| Iron (Ubuntu 22.04)   | 3.10      | supported                   | supported       |
| Jazzy (Ubuntu 24.04)  | 3.12      | supported                   | supported       |
| Rolling               | 3.10–3.12 | supported                   | supported       |
| (none, plain host)    | 3.10–3.13 | supported (decorators only) | n/a             |

Foxy and earlier are end-of-life and not supported.

## Python version matrix

The Python package supports CPython 3.10 through 3.13. PyPy is not supported (rclpy bindings are CPython-only).

| Python | Supported | Notes                 |
| ------ | --------- | --------------------- |
| 3.9    | no        | Below the ROS2 floor  |
| 3.10   | yes       | Humble / Iron default |
| 3.11   | yes       |                       |
| 3.12   | yes       | Jazzy default         |
| 3.13   | yes       | Decorator-only path   |

## ROS-version-agnostic

The Python package's `pyproject.toml` does **not** declare rclpy as a dependency. Imports of rclpy live behind try-blocks; assertion helpers raise a clear `RuntimeError` at call time on hosts without rclpy:

```python theme={null}
# On macOS without rclpy:
from roboticks.assertions import assert_topic_published
assert_topic_published(...)
# RuntimeError: rclpy is not importable on this host.
#   Install ROS2 (Humble/Iron/Rolling) or run this test on a runner with ROS2.
```

This means:

* Linters and type-checkers run anywhere.
* Unit tests that don't touch rclpy can run on a Mac, in CI without a ROS2 base image, etc.
* The pytest plugin still emits properties; only the rclpy-touching code paths require ROS2.

## Verify

```bash theme={null}
python -c "import roboticks; print(roboticks.__version__)"
# > 0.1.0
```

For the C++ package:

```bash theme={null}
. install/setup.bash
ros2 pkg list | grep roboticks_cpp
# > roboticks_cpp
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="The pytest plugin doesn't seem to be loaded">
    Run `pytest --trace-config` and look for `roboticks` in the active plugins list. If absent: `pip install --force-reinstall roboticks` then re-run.
  </Accordion>

  <Accordion title="`ImportError: rclpy` when importing roboticks.assertions">
    The assertions module imports rclpy lazily at the top level. If you're on a non-ROS host and just want decorators, import from `roboticks` directly: `from roboticks import confirms` (no rclpy required).
  </Accordion>

  <Accordion title="colcon doesn't find roboticks_cpp">
    Source the right setup file: `source install/setup.bash` (not `setup.sh`). Confirm with `ros2 pkg list | grep roboticks_cpp`.
  </Accordion>

  <Accordion title="MCAP capture errors on import">
    The MCAP support is an extra. `pip install 'roboticks[mcap]'` adds `mcap` and `mcap-ros2-support`.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Decorators" icon="at" href="/sdk/decorators">
    First thing to import: `@confirms`.
  </Card>

  <Card title="Modules" icon="folder-tree" href="/sdk/modules">
    The full module map.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    From zero to first traced PR in ten minutes.
  </Card>

  <Card title="C++ reference" icon="code" href="/sdk/cpp-reference">
    `roboticks_cpp` API in full.
  </Card>
</CardGroup>