# Install and check

## Get access

Request heliaEstimator through your Ambiq contact. These instructions assume access to the supplied repository; the tool is not offered here as a public download.

## Choose a host

| Host | Vela-only compilation | Full FVP runs |
| --- | --- | --- |
| Linux x86_64 | Native | Native |
| macOS with Apple silicon | Native or dev container | FVP in Docker with either option |
| Windows | Native | Use the supplied dev container |

The supplied dev container is also an option on Linux and macOS. It requires Docker and a compatible editor such as VS Code with Dev Containers.

## Option 1: native host tools

Install Python 3.12 and uv, then open the repository supplied to you:

```bash
cd helia-estimator
uv sync
uv run helx --version
uv run helx doctor
```

`uv run` invokes the installed CLI without activating a virtual environment. `doctor` reports available tools and provides hints for missing dependencies.

## Prepare for simulation

Linux builds need Git, CMake, Ninja and GNU make. On Apple silicon, install Docker Desktop with x86_64 emulation and the native build tools:

```bash
brew install make cmake ninja
```

When you are ready to simulate:

```bash
uv run helx setup
```

Setup presents Arm's FVP licence for acceptance before installing the FVP and records that acceptance locally. The FVP remains subject to Arm's licence. The Vela-only first experiment can run without this step.

## Option 2: the supplied dev container

This option keeps Python, Vela, the build tools and the FVP together in a `linux/amd64` environment. On Apple silicon, enable **Use Rosetta for x86_64/amd64 emulation** in Docker Desktop. The FVP does not run natively on macOS in either option.

1. Install Docker Desktop and VS Code with the Dev Containers extension.
2. Open your supplied helia-estimator checkout in VS Code.
3. Select **Dev Containers: Reopen in Container**. The post-create step installs the Python environment with `uv sync`.
4. In the container terminal, check the environment and run the first example:

```bash
uv run helx doctor
uv run helx run --config examples/at110/kws_vela_only.yaml
uv run helx setup
uv run helx run --config examples/at110/getting_started.yaml
```

Setup still requires acceptance of Arm's FVP licence. Results are written into the mounted checkout. The container's Python environment lives in `~/.venvs/helia-estimator`, separate from the host's `.venv`; dependency caches are retained in Docker volumes.

If you prefer the Dev Containers CLI:

```bash
npx @devcontainers/cli up --workspace-folder .
npx @devcontainers/cli exec --workspace-folder . bash
```

### Which macOS option should I choose?

| | Native host tools + FVP container | Full dev container |
| --- | --- | --- |
| helx and Vela | Run on macOS | Run in Linux container |
| Runner build | macOS tools fetched by setup | Linux tools in container |
| FVP and FVP installer | Linux container | Linux container |
| Host setup | Python, uv, native build tools and Docker | Docker and Dev Containers |
| Python environment | Checkout `.venv` | Separate container environment |

Choose the full dev container for a contained tool environment. Choose native host tools if you want to work directly from your macOS terminal. Both paths need Docker for FVP execution on Apple silicon.

## Recognize a ready environment

An abbreviated **illustrative** doctor response looks like this. Versions, paths and individual checks depend on your installation:

```text
$ helx doctor
Compile (every run)
           Check                 Detail
ok         vela executable       <installed version and path>
ok         Shipped platforms     <available platform definitions>

FVP run
           Check                 Detail
ok         Host for the FVP       <native Linux or Docker launcher>
...
Ready: Vela-only runs and FVP runs on <target>.
```

If only compilation is ready, the final line names the missing simulation dependencies. Follow those hints before running the full example.