stem-launcher/README.md

RV Launcher

Repo rv-launcher zawiera narzedzie do pracy z workspace RISC-V. W pierwszej kolejnosci sluzy ono do zarzadzania tokenami; pozostale funkcje obejmuja prace z kartami pracy i uruchamianie srodowiska kontenerowego.

Wlasciwym skryptem CLI jest wykonywalny plik rvctl.py. To on implementuje zarzadzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i start kontenera.

Publicznym entrypointem dla uzytkownika jest krotki wrapper rvctl:

./rvctl

Wrapper uruchamia:

python3 rvctl.py "$@"

rvctl.py mozna tez uruchomic bezposrednio:

./rvctl.py

Sciezki i domyslne ustawienia sa trzymane w workspace.json.

Co robi narzedzie

rvctl porzadkuje prace w trzech obszarach.

1. Zarzadzanie tokenami

   Narzedzie obsluguje lokalny store tokens/tokens.json, porownuje go z git remotes i potrafi synchronizowac token w obie strony. Szczegoly modelu, format pliku i opis komend sa w doc/tokens.md.

2. Listowanie i pobieranie kart pracy

   rvctl czyta serie, karty i zadania z workspace, pomaga wybrac material do pracy oraz przygotowuje remotes potrzebne do repo odpowiedzi. Docelowy model namespace series, cards i tasks jest w doc/series.md.

3. Uruchamianie srodowiska programistycznego w kontenerach

   Dla wybranej karty rvctl uruchamia sesje tmux i kontener z przygotowanym srodowiskiem developerskim. Docelowy model namespace containers jest w doc/containers.md.

Model katalogow

Podstawowym miejscem pracy uzytkownika jest workspace:

~/dev/workspace/rv

Minimalny uklad po starcie zawiera launcher, katalog tokenow i katalog na karty:

~/dev/workspace/rv
├── tools
│   └── rv-launcher
├── tokens
└── series

Sa dwie drogi startu.

Bez tokens.json

Jesli nie masz jeszcze pliku z tokenem albo tokenami, zacznij od pustego repo launchera i remota z tokenem:

mkdir -p ~/dev/workspace/rv/tools/rv-launcher
cd ~/dev/workspace/rv/tools/rv-launcher
git init
git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git
git fetch r1 main
git switch --track -c main r1/main

Potem wczytaj token z remota do lokalnego store:

./rvctl tokens sync remote r1
./rvctl tokens update r1
./rvctl tokens compare

Po tym kroku workspace ma juz lokalny store:

~/dev/workspace/rv
├── tools
│   └── rv-launcher
├── tokens
│   └── tokens.json
└── series

Z tokens.json

Jesli masz gotowy plik tokens.json, zacznij od skopiowania go do workspace:

mkdir -p ~/dev/workspace/rv/tokens
cp tokens.json ~/dev/workspace/rv/tokens/tokens.json
chmod 600 ~/dev/workspace/rv/tokens/tokens.json

Nastepnie pobierz albo przygotuj rv-launcher w:

~/dev/workspace/rv/tools/rv-launcher

Po wejsciu do repo launchera sprawdz store tokenow:

./rvctl tokens list store
./rvctl tokens compare
./rvctl tokens update r1

Po pobraniu kart pracy

Karty trafiaja do series w workspace:

~/dev/workspace/rv
├── tools
│   └── rv-launcher
├── tokens
│   └── tokens.json
└── series
    └── inf
        └── 03

rvctl pracuje na kartach z series_root, czyli na katalogu ~/dev/workspace/rv/series.

Po uruchomieniu srodowiska kontenerowego

Repo rv32i-hazard3-env jest potrzebne dopiero przy uruchamianiu srodowiska kontenerowego. Wtedy pojawia sie pod tools:

~/dev/workspace/rv
├── tools
│   ├── rv-launcher
│   └── rv32i-hazard3-env
├── tokens
│   └── tokens.json
└── series
    └── inf
        └── 03

Repozytoria zrodlowe poza workspace, na przyklad ~/dev/edu/repos/rv, sa zapleczem dla autora materialow albo fallbackiem dla narzedzi. Nie sa wymagane do zwyklej pracy w workspace.

Szybki start

Najpierw zobacz konfiguracje i dostepne komendy:

./rvctl
./rvctl show-config

Typowy przeplyw pracy:

./rvctl tokens compare
./rvctl list-series
./rvctl list-cards inf
./rvctl tmux-container inf 03 --dry-run
./rvctl tmux-container inf 03 --session rv-inf03 --attach
./rvctl submission inf 03 --class 4i --nick u1

--dry-run jest przydatny przy sprawdzaniu planu uruchomienia lub konfiguracji repo, zanim narzedzie cos zmieni.

Dokumentacja

• doc/rvctl.md - techniczna dokumentacja CLI: wszystkie komendy, argumenty i przelaczniki
• doc/tokens.md - model tokenow, synchronizacja remote <-> store
• doc/series.md - docelowy model komend dla serii i kart pracy
• doc/containers.md - docelowy model komend dla srodowisk kontenerowych
• doc/tokens.schema.json - schemat tokens/tokens.json
• doc/workspace.md - krotki opis konfiguracji workspace

README jest tylko mapa projektu. Szczegoly operacyjne trzymamy w doc/, zeby nie dublowac instrukcji w kilku miejscach.