mpabi
344 lines
8.9 KiB
Markdown
344 lines
8.9 KiB
Markdown
# 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.
|