edu/stem-launcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update launcher README overview

Browse Source
This commit is contained in:
mpabi
2026-04-29 00:33:21 +02:00
parent 78fb9daf2f
commit 8655a97347
2 changed files with 68 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+68 -267
View File
@@ -1,22 +1,55 @@
# RV Launcher
Launcher do workspace `rv`.
`rv-launcher` jest narzedziem do pracy z workspace RISC-V. Wlasciwym skryptem
CLI jest wykonywalny plik `rvctl.py`; to on implementuje listowanie serii i
kart, obsluge tokenow, przygotowanie repo odpowiedzi i start kontenera.
- `workspace.json` trzyma sciezki repo oryginalnych, workspace i tools
- `rvctl.py` zawiera implementacje CLI
- `rvctl` listuje serie i karty
- szczegolowy opis CLI jest w `doc/rvctl.md`
- model tokenow i synchronizacji repo <-> store jest w `doc/tokens.md`
Publicznym entrypointem dla uzytkownika jest krotki wrapper:
```bash
./rvctl
```
Wrapper uruchamia `python3 rvctl.py "$@"`. `rvctl.py` mozna tez uruchomic
bezposrednio:
```bash
./rvctl.py
```
Sciezki i domyslne ustawienia sa trzymane w `workspace.json`.
## Co robi narzedzie
CLI 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.py` czyta serie i karty z workspace, pomaga wybrac material do pracy
oraz przygotowuje remotes potrzebne do repo odpowiedzi. Szczegoly komend
`list-series`, `list-cards` i `submission` sa w `doc/rvctl.md`.
3. Uruchamianie srodowiska programistycznego w kontenerach
Dla wybranej karty `rvctl.py` uruchamia sesje tmux i kontener z przygotowanym
srodowiskiem developerskim. Szczegoly komendy `tmux-container` sa w
`doc/rvctl.md`.
## Model katalogow
Repo oryginalne trzymamy poza workspace:
Repozytoria zrodlowe trzymamy poza workspace:
```bash
~/dev/edu/repos/rv
```
Workspace sluzy do klonow roboczych i cwiczen:
Workspace sluzy do klonow roboczych, cwiczen, tokenow i socketow:
```bash
~/dev/workspace/rv
@@ -31,273 +64,41 @@ Typowy uklad:
~/dev/workspace/rv/tools/rv-launcher
~/dev/workspace/rv/tools/rv32i-hazard3-env
~/dev/workspace/rv/series/<seria>/<karta>
```
Launcher szuka `rv32i-hazard3-env` najpierw w workspace, a jesli nie znajdzie
klona roboczego, moze uzyc repo oryginalnego z `~/dev/edu/repos/rv`.
Karty pracy tez sa rozdzielone:
- `~/dev/edu/repos/rv/series/...` to checkouty zrodlowe, nad ktorymi pracujemy
- `~/dev/workspace/rv/series/...` to klony testowe pobierane z Gitea
Launcher wykonuje `list-series`, `list-cards`, `submission` i `tmux-container`
na kartach z workspace, nie na repo zrodlowych.
## Przygotowanie katalogu
Repo treningowe launchera trzymaj pod:
```bash
~/dev/workspace/rv/tools/rv-launcher
```
Bootstrap bez `git clone`:
```bash
mkdir -p ~/dev/workspace/rv/tools
mkdir -p ~/dev/workspace/rv/tools/rv-launcher
cd ~/dev/workspace/rv/tools/rv-launcher
git init
```
Glowne pliki CLI:
```bash
./rvctl
rvctl.py
```
`rvctl` jest jedynym publicznym entrypointem. `rvctl.py` jest implementacja
uruchamiana przez wrapper i nie wymaga osobnego wywolywania przez ucznia.
Uruchomienie bez argumentow pokazuje tabelaryczny skrot komend:
```bash
./rvctl
./rvctl tokens
```
## Autoryzacja
Masz dwie drogi.
### Droga 1: remote `r1` z tokenem w URL
To jest wariant dydaktyczny, jesli uczen ma cwiczyc reczne dodawanie remota z
tokenem do konkretnego zdalnego endpointu. Jesli launcher zobaczy URL w formacie
`http://LOGIN:TOKEN@...`, mozesz zapisac ten token lokalnie komenda
`tokens sync remote r1`.
Przyklad:
```bash
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
```
### Droga 2: lokalny `tokens/tokens.json`
To jest wariant alternatywny, wygodniejszy wtedy, gdy launcher ma sam wykonywac
`clone`, `fetch` i `push`, albo gdy uzytkownik po zajeciach chce pracowac juz na
wlasnych repo bez wpisywania tokena do kazdego remota.
Przed operacjami wymagajacymi autoryzacji dodaj lokalny token do:
```bash
~/dev/workspace/rv/tokens/tokens.json
```
Minimalny format:
`rvctl.py` pracuje na kartach z `series_root` w workspace. Repo zrodlowe w
`~/dev/edu/repos/rv` sa punktem odniesienia i fallbackiem dla narzedzi.
```json
{
"version": 3,
"tokens": [
{
"id": "r1",
"value": "TU_WSTAW_TOKEN",
"server": {
"type": "gitea",
"endpoint": "http://77.90.8.171:3001",
"scheme": "http",
"host": "77.90.8.171",
"port": 3001
},
"user": "u1",
"org": "edu-tools",
"repo": "rv-launcher"
}
]
}
```
## Szybki start
Pelny schemat pliku jest w `doc/tokens.schema.json`.
Plik powinien byc lokalny, niewersjonowany i miec prawa `600`.
Przyklad:
```bash
mkdir -p ~/dev/workspace/rv/tokens
chmod 700 ~/dev/workspace/rv/tokens
chmod 600 ~/dev/workspace/rv/tokens/tokens.json
```
Jesli token jest trzymany tylko w `tokens/tokens.json`, remote `r1` moze
byc zapisany bez sekretu:
```bash
git remote add r1 http://77.90.8.171:3001/edu-tools/rv-launcher.git
```
Podstawowe komendy tokenow:
```bash
./rvctl tokens scan
./rvctl tokens compare
./rvctl tokens list store
./rvctl tokens list remote
./rvctl tokens sync remote r1
./rvctl tokens update r1
./rvctl tokens sync store r1
./rvctl tokens remove store r1
./rvctl tokens remove remote r1
./rvctl tokens add r1
./rvctl tokens read
./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
```
`tokens scan` wypisuje diagnostyczny skan git remotes i niczego nie zapisuje:
pokazuje URL-e typu `auth`, `plain` i `unsupported`.
`tokens compare` wypisuje tabele `tokens` i niczego nie zapisuje: jeden wiersz
na logiczny remote tokena.
`tokens list store|remote|both` wypisuje jedno zrodlo bez porownywania.
`tokens.json` synchronizujemy z repo `rv-launcher`; remotes kart pracy i
odpowiedzi sa generowane jako pochodne tego ustawienia.
`token_ref` laczy nazwe tokena z markerem po prawej stronie: `*` oznacza, ze
remote i `tokens.json` sa zgodne, `R` oznacza token tylko w remote, a `S`
token tylko w `tokens.json`. Kolumny `scope`, `org` i `repo` sa maskami
uprawnien; bez zgodnego wpisu maja wartosc `?????????`, `?????` albo `????`.
Zapis z remote do `tokens.json` robi `tokens sync remote r1`.
Odczyt `valid` i uprawnien z API robi `tokens update r1`.
Zapis z `tokens.json` do remota robi `tokens sync store r1`.
Usuniecie wpisu robi `tokens remove store r1`, a usuniecie git remota
`tokens remove remote r1`.
Kolumna `valid` oznacza, czy token zostal zaakceptowany przez API teraz.
Jesli przy tokenie w `tokens.json` zapiszesz `expires_at`, `valid` moze pokazac
date wygasniecia; bez daty poprawny token pokazuje `forever`.
## Fetch i switch
Domyslna galaz launchera to `main`.
Wariant preferowany przez `r1`:
```bash
git fetch r1 main
git switch --track -c main r1/main
git pull --ff-only r1 main
```
Jesli repo bylo sklonowane klasycznie i pracujesz przez `origin`, odpowiednikiem
jest:
```bash
git fetch origin main
git switch main
git pull --ff-only origin main
```
Jesli chcesz wejsc na inna galaz, na przyklad `feat/x`, uzyj:
```bash
git fetch r1 feat/x
git switch --track -c feat/x r1/feat/x
```
Wariant przez `origin`:
```bash
git fetch origin feat/x
git switch --track -c feat/x origin/feat/x
```
## Repo odpowiedzi kart pracy
Model pracy kart jest taki:
- `r1` wskazuje repo z materialem z `edu-inf`
- `a1` wskazuje wspolne repo odpowiedzi w `zsl-inf`
- kazdy uczen wysyla swoja prace na branch o nazwie swojego nicku
Repo odpowiedzi nie zawiera nicku w nazwie. Launcher buduje je w formacie:
```text
zsl-inf/<repo_z_edu-inf>-<klasa>-<data>
```
Przyklad:
```text
zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
```
Przyklad planu dla ucznia `u1`:
```bash
./rvctl submission inf 03 --class 4i --nick u1
```
Przyklad konfiguracji remote'ow w repo karty:
```bash
./rvctl submission inf 03 --class 4i --nick u1 --apply
```
Launcher wtedy:
- czyta URL zrodlowego repo z `origin` aktualnej karty i ustawia go jako `r1`
- bierze basename tego repo z `edu-inf` i z niego buduje nazwe repo odpowiedzi
- wylicza repo odpowiedzi w `zsl-inf` i ustawia je jako `a1`
- proponuje branch ucznia, na przyklad `u1`
Typowy wynik to:
```text
source_repo edu-inf/lab-rv32i-strlen-bss-data-stack
source_remote r1
answer_remote a1
answer_repo zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
student_branch u1
```
## Wariant alternatywny: `git clone`
Jesli celem nie jest cwiczenie `remote add` i `fetch`, repo treningowe mozna
tez sklonowac klasycznie:
```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
```
## Podstawowe komendy
Przyklady:
Najpierw zobacz konfiguracje i dostepne komendy:
```bash
./rvctl
./rvctl show-config
./rvctl list-series
./rvctl list-cards inf
./rvctl tokens
./rvctl submission inf 03 --class 4i --nick u1
./rvctl tmux-container inf 03 --dry-run
./rvctl tmux-container inf 03 --session rv-inf03 --attach
```
Skrypt nie trzyma listy kart w JSON-ie. Czyta `series/*/*` z `series_root`.
Typowy przeplyw pracy:
```bash
./rvctl tokens scan
./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` - komendy CLI, przelaczniki i przyklady uzycia
- `doc/tokens.md` - model tokenow, synchronizacja remote <-> store
- `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.
rvctl.py
Regular → Executable
View File