> For the complete documentation index, see [llms.txt](https://carec.gitbook.io/carec-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://carec.gitbook.io/carec-docs/documentation/simulation/environment-setup.md).

# Environment Setup

CAREC uses one common development architecture across supported contributor hosts. **Ubuntu 24.04 + ROS 2 Jazzy is the canonical runtime**, while the Dev Container keeps project dependencies and tooling consistent.

```
Ubuntu 24.04 ─┐
Windows 11 ───┼──> Git + VS Code + Docker/WSL2 as applicable
macOS ────────┘                    |
                                  v
                       CAREC Dev Container
                       Ubuntu / ROS 2 Jazzy
                       Gazebo / Nav2 / SLAM
                       C++ / Python / tools
                                  |
                                  v
                         Build -> Test -> Simulate
```

## Common workflow

```bash
git clone https://github.com/vinodkumar1947/CAREC-Project.git
cd CAREC-Project
code .
```

In VS Code run **Dev Containers: Reopen in Container**. The current container runs:

```bash
./scripts/bootstrap.sh --check
```

Baseline verification:

```bash
./scripts/bootstrap.sh --check
python3 -m pytest tests/obstacle_test.py tests/unit -v
```

{% hint style="warning" %}
The container is an early project baseline. Headless build and tests are the portable contract. Gazebo/RViz graphics, GPU acceleration, device passthrough, and HIL behavior must be validated on each host before being marked verified.
{% endhint %}

## Ubuntu 24.04

Ubuntu is the reference host for CI parity, robotics integration, sensor work, HIL, and native troubleshooting. Install Git, Docker, VS Code, and the Dev Containers extension, then use the common workflow. Maintainers and hardware engineers may use a native ROS/Gazebo installation when required, but ordinary contributors should prefer the project container.

## Windows 11

Use WSL2 with Ubuntu 24.04. Enable Docker Desktop WSL2 integration and install the VS Code WSL and Dev Containers extensions. Configure Git inside WSL and keep the repository in the Linux filesystem when possible. WSLg can support graphical applications, but Gazebo/RViz graphics remain a platform verification item.

## macOS

Install Git, Docker Desktop, VS Code, and the Dev Containers extension, then use the common workflow. macOS contributors can work on C++, Python, ROS interfaces, unit tests, documentation, algorithms, and headless workflows. Apple Silicon uses ARM64, so simulator and package compatibility must be verified rather than assumed. Unsupported simulator/GPU workloads should run on an Ubuntu environment while preserving the same repository interfaces and tests.

## Portable project operations

The intended common operations are bootstrap verification, workspace build, formatting/linting, C++ and Python unit tests, headless smoke tests, scenario/regression tests, ROS package/interface work, logs/test artifacts, and pull-request validation.

## Host-dependent operations

Graphical simulation, GPU acceleration, USB/sensor passthrough, HIL, real-time behavior, and vendor-specific drivers remain host-dependent.

## Support policy

| Host                 | Code/unit/headless target                 | GUI simulation | HIL                      | Advanced simulation     |
| -------------------- | ----------------------------------------- | -------------- | ------------------------ | ----------------------- |
| Ubuntu 24.04 x86\_64 | Supported target                          | Reference      | Final integration target | NVIDIA/Isaac workstream |
| Windows 11 + WSL2    | Supported target                          | Validate       | Ubuntu final integration | Ubuntu/NVIDIA           |
| macOS Intel          | Supported target; headless validate       | Best effort    | Ubuntu final integration | Not standard            |
| macOS Apple Silicon  | Supported target; ARM64 headless validate | Best effort    | Ubuntu final integration | Not standard            |

A **supported target** is an intended project contract. A target becomes **verified** only after the corresponding smoke tests pass.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://carec.gitbook.io/carec-docs/documentation/simulation/environment-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.