# 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 ``` Najpierw utworz tylko katalog bazowy workspace i wejdz do niego: ```bash mkdir -p ~/dev/workspace/rv cd ~/dev/workspace/rv ``` Po tym kroku workspace istnieje, ale nie ma jeszcze katalogow narzedzi, tokenow ani kart: ```text ~/dev/workspace/rv ``` Potem wybierz jedna z dwoch drog startu. ### Bez `tokens.json` Ten wariant jest dla sytuacji, w ktorej token jest podany w URL-u git remota, a plik `tokens.json` ma powstac dopiero lokalnie. Etap 1: utworz katalog launchera i wejdz do niego: ```bash mkdir -p ~/dev/workspace/rv/tools/rv-launcher cd ~/dev/workspace/rv/tools/rv-launcher ``` Etap 2: utworz puste repo, dodaj remote `r1` z tokenem, pobierz branch i ustaw lokalny `main`: ```bash 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 ``` `r1` jest nazwa remota, z ktorego startujemy. `--track` ustawia lokalny branch `main` tak, aby sledzil `r1/main`, dzieki czemu pozniejsze `git pull` i `git push` wiedza, z ktorym branchem zdalnym pracuja. Po tym kroku w workspace jest juz repo launchera: ```text ~/dev/workspace/rv └── tools └── rv-launcher ``` Etap 3: utworz katalog store i wczytaj token z remota do lokalnego store: ```bash cd ~/dev/workspace/rv/tools/rv-launcher mkdir -p ~/dev/workspace/rv/tokens ./rvctl tokens sync remote r1 ./rvctl tokens update r1 ``` Po tym kroku workspace ma juz `tokens.json`: ```text ~/dev/workspace/rv ├── tools │ └── rv-launcher └── tokens └── tokens.json ``` Etap 4: 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` Ten wariant jest dla sytuacji, w ktorej masz juz gotowy plik `tokens.json`. Etap 1: skopiuj token store do workspace: ```bash mkdir -p ~/dev/workspace/rv/tokens cd ~/dev/workspace/rv cp /sciezka/do/tokens.json tokens/tokens.json chmod 600 tokens/tokens.json ``` Po tym kroku workspace ma store tokenow, ale nie ma jeszcze launchera: ```text ~/dev/workspace/rv └── tokens └── tokens.json ``` Etap 2: wejdz do katalogu narzedzi i sklonuj `rv-launcher`: ```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 ``` Etap 3: zmien nazwe remota z `origin` na `r1`: ```bash git remote rename origin r1 ``` `tokens.json` jest mapowany na nazwy git remotes, dlatego repo launchera ma uzywac remota `r1`. Po `git clone` workspace wyglada tak: ```text ~/dev/workspace/rv ├── tools │ └── rv-launcher └── tokens └── tokens.json ``` Etap 4: sprawdz store i wpisz credentials ze store do remota `r1`: ```bash ./rvctl tokens list store ./rvctl tokens sync store r1 ``` `list store` powinien pokazac token ze store: ```text tokens item source kind server proto host org repo user remote token valid ---- ------ ---- ------ ----- ---------------- --------- ----------- ---- ------ ------------ ------- 1 store auth gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 e59cc...13be forever ``` `sync store r1` wpisuje credentials do git remota: ```text repo_root /home/user/dev/workspace/rv/tools/rv-launcher remote r1 server http://77.90.8.171:3001 user u1 id r1 status updated url http://77.90.8.171:3001/edu-tools/rv-launcher.git ``` Etap 5: 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: ```text tokens item server proto host org repo user remote token_ref token valid ---- ------ ----- ---------------- --------- ----------- ---- ------ --------- ------------ ------- 1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 * e59cc...13be forever ``` Etap 6: po operacjach Git mozesz usunac sekret z `.git/config`, zostawiajac token tylko w store: ```bash ./rvctl tokens rm remote r1 ./rvctl tokens compare ``` Po usunieciu remota `compare` pokazuje marker `S`, czyli token jest tylko w store: ```text tokens item server proto host org repo user remote token_ref token valid ---- ------ ----- ---------------- --------- ----------- ---- ------ --------- ------------ ------- 1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 S e59cc...13be forever ``` ### 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.