# Kontenery i debug

`rvctl` integruje workspace z narzędziem `rv32i-hazard3-student-env`.
Środowisko ma dwa profile kontenerów:

- `rv32i` - docelowe środowisko RISC-V/Hazard3 z `nvim`, `tmux`,
  `gdb-multiarch`, toolchainem RISC-V i symulatorem Hazard3.
- `host` - natywne środowisko na architekturze hosta z `clang`, `gcc`, `gdb`,
  opcjonalnie `lldb`, `valgrind`, `nvim` i `tmux`.

Profile są uruchamiane jako oddzielne usługi `docker compose`, więc zależności
RISC-V i zależności natywnego debugowania nie mieszają się ze sobą.

## Szybki przepływ

```bash
./rvctl env list
./rvctl env sync
./rvctl env build rv32i
./rvctl env build host

./rvctl debug rv32i inf bss 1
./rvctl debug host inf bss 1
./rvctl run host inf bss 1
./rvctl shell rv32i inf bss
./rvctl shell host inf bss
```

Jeżeli `workspace.json` ma ustawione domyślne wartości `defaults.series`,
`defaults.card` i `defaults.task`, można używać krótszych komend:

```bash
./rvctl debug rv32i
./rvctl debug host
./rvctl debug rv32i 4
./rvctl debug host 4
```

## `env list`

Pokazuje dostępne profile i bieżący katalog narzędzia:

```bash
./rvctl env list
```

Typowy wynik:

```text
profile  service  image                               status  purpose
rv32i    env      edu-inf/rv32i-hazard3-env:latest     ready   RV32I/Hazard3 nvim + gdb-multiarch
host     host     edu-inf/rv32i-hazard3-host-env:latest ready   native host clang/gcc + gdb/lldb
```

## `env sync`

Klonuje albo aktualizuje repo środowiska do:

```text
~/dev/workspace/rv/tools/rv32i-hazard3-student-env
```

Komenda:

```bash
./rvctl env sync
./rvctl env sync --dry-run
```

Jeżeli tego repo jeszcze nie ma w workspace, `rvctl` używa fallbacku z
`~/dev/edu/repos/rv/rv32i-hazard3-env`, o ile jest dostępny.

## `env build`

Buduje wybrany profil kontenera:

```bash
./rvctl env build rv32i
./rvctl env build host
```

Wariant `--dry-run` pokazuje dokładną komendę bez uruchamiania Dockera:

```bash
./rvctl env build host --dry-run
```

## `debug`

Uruchamia debugowanie zadania w wybranym profilu.

```bash
./rvctl debug rv32i inf bss 1
./rvctl debug host inf bss 1
```

W profilu `rv32i` startuje środowisko Hazard3: symulator, `gdb-multiarch` i
`nvim` w sesji `tmux`.

W profilu `host` wybrane źródło C jest kompilowane natywnie z debug info, a
potem uruchamiane w `gdb` obok `nvim`.
Ten profil jest przeznaczony dla tasków C z funkcją `main`; taski czysto
asemblerskie nadal debugujemy w profilu `rv32i`.

Przydatne warianty:

```bash
./rvctl debug rv32i bss 4
./rvctl debug host bss 4
./rvctl debug host 4 --editor vim
./rvctl debug host 4 --instance host-bss-t4
./rvctl debug host 4 --dry-run
```

## `run`

Na razie `run` jest wdrożone dla profilu `host`. Buduje wybrany task natywnie i
uruchamia wynikowy program:

```bash
./rvctl run host inf bss 1
./rvctl run host 4
```

Dla profilu `rv32i` używamy obecnie `debug rv32i`, bo przepływ RISC-V zakłada
symulator Hazard3 i GDB.

## `shell`

Otwiera shell w wybranym profilu kontenera z podmontowaną kartą:

```bash
./rvctl shell rv32i inf bss
./rvctl shell host inf bss
```

## Selektory

Komendy `debug`, `run` i `shell` używają tych samych skrótów co `tasks`:

```bash
./rvctl debug host 1
./rvctl debug host bss 1
./rvctl debug host inf bss 1
```

`rvctl` rozwiązuje `1` do właściwego zadania, na przykład
`task1_bss`, na podstawie plików w `src/tasks`.

## Starsza komenda

`tmux-container` zostaje jako alias kompatybilności dla starszego trybu
shellowego. Nowe przykłady powinny używać `debug`, `run`, `shell` i `env`.