# 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`: ```bash ./rvctl ``` Wrapper uruchamia: ```bash python3 rvctl.py "$@" ``` `rvctl.py` mozna tez uruchomic bezposrednio: ```bash ./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: ```bash ~/dev/workspace/rv ``` Minimalny uklad po starcie zawiera launcher, katalog tokenow i katalog na karty: ```text ~/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: ```bash 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: ```bash ./rvctl tokens sync remote r1 ./rvctl tokens update r1 ``` Po tym kroku workspace ma juz lokalny store: ```text ~/dev/workspace/rv ├── tools │ └── rv-launcher ├── tokens │ └── tokens.json └── series ``` Na koniec sprawdz, czy git remote i lokalny store widza ten sam token: ```bash ./rvctl tokens compare ``` Przykladowy wydruk: ```text tokens item server proto host org repo user remote token_ref token valid scope org repo ---- ------ ----- ------------------ --------- ----------- ---- ------ --------- ------------ ------- --------- ------ ------ 1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 * e59cc...13be forever wwwwwwwww +++++ ++++ ``` Najwazniejsze pola: - `remote` - nazwa git remota, tutaj `r1` - `token_ref` - lokalna nazwa tokena i marker zgodnosci po prawej stronie - `*` - token w remote i w `tokens.json` jest zgodny - `S` - token jest tylko w `tokens.json`; to jest normalne w trybie store-only - `R` - token jest tylko w git remote - `token` - zamaskowany sekret; `rvctl` nie wypisuje calego tokena - `valid`, `scope`, `org`, `repo` - metadane i uprawnienia pobrane przez `tokens update` Pelny opis tabeli tokenow jest w `doc/tokens.md`. ### Z `tokens.json` Jesli masz gotowy plik `tokens.json`, zacznij od lokalnego store tokenow: ```bash mkdir -p ~/dev/workspace/rv/tokens cp tokens.json ~/dev/workspace/rv/tokens/tokens.json chmod 600 ~/dev/workspace/rv/tokens/tokens.json ``` Opcja `git clone`: ```bash mkdir -p ~/dev/workspace/rv/tools cd ~/dev/workspace/rv/tools git clone http://77.90.8.171:3001/edu-tools/rv-launcher.git cd rv-launcher git remote rename origin r1 ``` Po klonie zmieniamy `origin` na `r1`, bo `tokens.json` jest mapowany na nazwy git remotes. Jesli `git clone` wymaga autoryzacji, uzyj standardowego sposobu Gita dla tego jednego kroku. Plik `tokens.json` zaczyna obslugiwac Git remotes dopiero wtedy, gdy masz juz lokalnie `rvctl`. Po wejsciu do repo launchera sprawdz store i wpisz credentials ze store do remota `r1`: ```bash ./rvctl tokens list store ./rvctl tokens sync store r1 ``` Na koniec odswiez metadane tokena i porownaj store z remote: ```bash ./rvctl tokens update r1 ./rvctl tokens compare ``` `compare` powinien pokazac `*` przy `r1`, jezeli remote i `tokens.json` sa zgodne. Po operacjach Git mozesz usunac sekret z `.git/config`, zostawiajac token tylko w store: ```bash ./rvctl tokens rm remote r1 ``` ### Po pobraniu kart pracy Karty trafiaja do `series` w workspace: ```text ~/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`: ```text ~/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: ```bash ./rvctl ./rvctl show-config ``` Typowy przeplyw pracy: ```bash ./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.