# `mix rclex.prep.ros2`
[🔗](https://github.com/rclex/rclex/blob/v0.13.2/lib/mix/tasks/rclex/prep/ros2.ex#L1)

Prepare ROS 2 resources for Nerves and hosts without a local ROS 2 installation.

`mix rclex.prep.ros2` prepares the ROS 2 resources that Nerves targets and
Linux hosts need when they run Rclex without a local ROS 2 installation.

The task copies the required ROS 2 files from a Docker image into the target
directory for the runtime environment. Before copying, it shows a confirmation
prompt and proceeds only when you answer yes.

## Prerequisites

- Docker must be available.
- `ROS_DISTRO` must be set.
- For Nerves, `MIX_TARGET` must be set.
- An `--arch` value must be provided.
  - Supported architectures are `arm64v8`, `amd64`, and `arm32v7`.

## Default Docker images

- `arm64v8`, `amd64`: `ARCH/ros:ROS_DISTRO-ros-core`
- `arm32v7`: `rclex/arm32v7_ros_docker_with_vendor_resources:ROS_DISTRO`

## Usage for Nerves

The following example uses `rpi4` and `jazzy`.

Prepare ROS 2 resources.

```
export MIX_TARGET=rpi4
export ROS_DISTRO=jazzy
mix rclex.prep.ros2 --arch arm64v8
# ROS 2 resources are copied under `rootfs_overlay/opt/ros/jazzy`.
```

See `USE_ON_NERVES.md` for more details.

## Usage for Linux host without ROS 2

The following example uses `amd64` and `jazzy`.

Prepare ROS 2 resources.

```
export ROS_DISTRO=jazzy
mix rclex.prep.ros2 --arch amd64
# ROS 2 resources are copied under `.ros2/resources/from-docker/amd64/opt/ros/jazzy`.
```

## --dockerfile option

You can also customize the Docker image with `--dockerfile`. This option is
supported for `arm64v8` and `amd64` only, not available for `arm32v7`.

- `--dockerfile PATH`: build the given Dockerfile and copy resources from the
  resulting image.
- The image architecture used by the Dockerfile must match the requested
  target architecture.

### Requirements

The built image must provide at least the following directories:

- `/opt/ros/$ROS_DISTRO/include`
- `/opt/ros/$ROS_DISTRO/lib`
- `/opt/ros/$ROS_DISTRO/share`

### Examples

Build a custom image from an arbitrary Dockerfile.

```
mix rclex.prep.ros2 --arch arm64v8 --dockerfile docker/ros2/Dockerfile
```

In this example, `docker/ros2/Dockerfile` is just a sample path.

---

*Consult [api-reference.md](api-reference.md) for complete listing*