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

Use Polish diacritics in docs

Browse Source
This commit is contained in:
mpabi
2026-04-29 02:09:30 +02:00
parent dedde573f7
commit b67c5b5204
6 changed files with 326 additions and 321 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+72 -70
View File
@@ -1,14 +1,14 @@
# 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.
Repo `rv-launcher` zawiera narzędzie do pracy z workspace RISC-V. W pierwszej
kolejności służy ono do zarządzania tokenami; pozostałe funkcje obejmują pracę
z kartami pracy i uruchamianie środowiska kontenerowego.
Wlasciwym skryptem CLI jest wykonywalny plik `rvctl.py`. To on implementuje
zarzadzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i
Właściwym skryptem CLI jest wykonywalny plik `rvctl.py`. To on implementuje
zarządzanie tokenami, listowanie serii i kart, przygotowanie repo odpowiedzi i
start kontenera.
Publicznym entrypointem dla uzytkownika jest krotki wrapper `rvctl`:
Publicznym entrypointem dla użytkownika jest krótki wrapper `rvctl`:
```bash
./rvctl
@@ -20,73 +20,73 @@ Wrapper uruchamia:
python3 rvctl.py "$@"
```
`rvctl.py` mozna tez uruchomic bezposrednio:
`rvctl.py` można też uruchomić bezpośrednio:
```bash
./rvctl.py
```
Sciezki i domyslne ustawienia sa trzymane w `workspace.json`.
Ścieżki i domyślne ustawienia są trzymane w `workspace.json`.
## Co robi narzedzie
## Co robi narzędzie
`rvctl` porzadkuje prace w trzech obszarach.
`rvctl` porządkuje pracę w trzech obszarach.
1. Zarzadzanie tokenami
1. Zarządzanie 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`.
Narzędzie obsługuje lokalny store `tokens/tokens.json`, porównuje go z git
remotes i potrafi synchronizować token w obie strony. Szczegóły modelu,
format pliku i opis komend są w `doc/tokens.md`.
2. Listowanie i pobieranie kart pracy
`rvctl` czyta serie, karty i zadania z workspace, pomaga wybrac material do
`rvctl` czyta serie, karty i zadania z workspace, pomaga wybrać materiał 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
3. Uruchamianie środowiska programistycznego w kontenerach
Dla wybranej karty `rvctl` uruchamia sesje tmux i kontener z przygotowanym
srodowiskiem developerskim. Docelowy model namespace `containers` jest w
Dla wybranej karty `rvctl` uruchamia sesję tmux i kontener z przygotowanym
środowiskiem developerskim. Docelowy model namespace `containers` jest w
`doc/containers.md`.
## Model katalogow
## Model katalogów
Podstawowym miejscem pracy uzytkownika jest workspace:
Podstawowym miejscem pracy użytkownika jest workspace:
```bash
~/dev/workspace/rv
```
Najpierw utworz tylko katalog bazowy workspace i wejdz do niego:
Najpierw utwórz tylko katalog bazowy workspace i wejdź 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:
Po tym kroku workspace istnieje, ale nie ma jeszcze katalogów narzędzi,
tokenów ani kart:
```text
~/dev/workspace/rv
```
Potem wybierz jedna z dwoch drog startu.
Potem wybierz jedną z dwóch dróg 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.
Ten wariant jest dla sytuacji, w której token jest podany w URL-u git remota,
a plik `tokens.json` ma powstać dopiero lokalnie.
Etap 1: utworz katalog launchera i wejdz do niego:
Etap 1: utwórz katalog launchera i wejdź 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
Etap 2: utwórz puste repo, dodaj remote `r1` z tokenem, pobierz branch i
ustaw lokalny `main`:
```bash
@@ -96,11 +96,11 @@ 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.
`r1` jest nazwą remota, z którego startujemy. `--track` ustawia lokalny branch
`main` tak, aby śledził `r1/main`, dzięki czemu późniejsze `git pull` i
`git push` wiedzą, z którym branchem zdalnym pracują.
Po tym kroku w workspace jest juz repo launchera:
Po tym kroku w workspace jest już repo launchera:
```text
~/dev/workspace/rv
@@ -108,16 +108,18 @@ Po tym kroku w workspace jest juz repo launchera:
└── rv-launcher
```
Etap 3: utworz katalog store i wczytaj token z remota do lokalnego store:
Etap 3: 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`:
`rvctl` sam tworzy katalog `~/dev/workspace/rv/tokens`, jeżeli jeszcze go nie
ma. Plik `tokens.json` dostaje prawa `600`, a katalog store prawa `700`.
Po tym kroku workspace ma już `tokens.json`:
```text
~/dev/workspace/rv
@@ -127,13 +129,13 @@ Po tym kroku workspace ma juz `tokens.json`:
└── tokens.json
```
Etap 4: sprawdz, czy git remote i lokalny store widza ten sam token:
Etap 4: sprawdź, czy git remote i lokalny store widzą ten sam token:
```bash
./rvctl tokens compare
```
Przykladowy wydruk:
Przykładowy wydruk:
```text
tokens
@@ -142,33 +144,33 @@ item server proto host org repo user remote t
1 gitea http 77.90.8.171:3001 edu-tools rv-launcher u1 r1 r1 * e59cc...13be forever wwwwwwwww +++++ ++++
```
Najwazniejsze pola:
Najważniejsze pola:
- `remote` - nazwa git remota, tutaj `r1`
- `token_ref` - lokalna nazwa tokena i marker zgodnosci po prawej stronie
- `token_ref` - lokalna nazwa tokena i marker zgodności 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
- `token` - zamaskowany sekret; `rvctl` nie wypisuje całego tokena
- `valid`, `scope`, `org`, `repo` - metadane i uprawnienia pobrane przez
`tokens update`
Pelny opis tabeli tokenow jest w `doc/tokens.md`.
Pełny opis tabeli tokenów jest w `doc/tokens.md`.
### Z `tokens.json`
Ten wariant jest dla sytuacji, w ktorej masz juz gotowy plik `tokens.json`.
Ten wariant jest dla sytuacji, w której masz już 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
cp /ścieżka/do/tokens.json tokens/tokens.json
chmod 600 tokens/tokens.json
```
Po tym kroku workspace ma store tokenow, ale nie ma jeszcze launchera:
Po tym kroku workspace ma store tokenów, ale nie ma jeszcze launchera:
```text
~/dev/workspace/rv
@@ -176,7 +178,7 @@ Po tym kroku workspace ma store tokenow, ale nie ma jeszcze launchera:
└── tokens.json
```
Etap 2: wejdz do katalogu narzedzi i sklonuj `rv-launcher`:
Etap 2: wejdź do katalogu narzędzi i sklonuj `rv-launcher`:
```bash
mkdir -p ~/dev/workspace/rv/tools
@@ -185,16 +187,16 @@ 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`:
Etap 3: zmień nazwę 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`.
używać remota `r1`.
Po `git clone` workspace wyglada tak:
Po `git clone` workspace wygląda tak:
```text
~/dev/workspace/rv
@@ -204,14 +206,14 @@ Po `git clone` workspace wyglada tak:
└── tokens.json
```
Etap 4: sprawdz store i wpisz credentials ze store do remota `r1`:
Etap 4: sprawdź 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:
`list store` powinien pokazać token ze store:
```text
tokens
@@ -232,14 +234,14 @@ status updated
url http://77.90.8.171:3001/edu-tools/rv-launcher.git
```
Etap 5: odswiez metadane tokena i porownaj store z remote:
Etap 5: odśwież metadane tokena i porównaj store z remote:
```bash
./rvctl tokens update r1
./rvctl tokens compare
```
`compare` powinien pokazac `*` przy `r1`, jezeli remote i `tokens.json` sa
`compare` powinien pokazać `*` przy `r1`, jeżeli remote i `tokens.json` są
zgodne:
```text
@@ -249,7 +251,7 @@ item server proto host org repo user remote tok
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
Etap 6: po operacjach Git możesz usunąć sekret z `.git/config`, zostawiając
token tylko w store:
```bash
@@ -257,7 +259,7 @@ token tylko w store:
./rvctl tokens compare
```
Po usunieciu remota `compare` pokazuje marker `S`, czyli token jest tylko w
Po usunięciu remota `compare` pokazuje marker `S`, czyli token jest tylko w
store:
```text
@@ -269,7 +271,7 @@ item server proto host org repo user remote tok
### Po pobraniu kart pracy
Karty trafiaja do `series` w workspace:
Karty trafiają do `series` w workspace:
```text
~/dev/workspace/rv
@@ -285,10 +287,10 @@ Karty trafiaja do `series` w workspace:
`rvctl` pracuje na kartach z `series_root`, czyli na katalogu
`~/dev/workspace/rv/series`.
### Po uruchomieniu srodowiska kontenerowego
### Po uruchomieniu środowiska kontenerowego
Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu srodowiska
kontenerowego. Wtedy pojawia sie pod `tools`:
Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu środowiska
kontenerowego. Wtedy pojawia się pod `tools`:
```text
~/dev/workspace/rv
@@ -302,20 +304,20 @@ kontenerowego. Wtedy pojawia sie pod `tools`:
└── 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.
Repozytoria źródłowe poza workspace, na przykład `~/dev/edu/repos/rv`, są
zapleczem dla autora materiałów albo fallbackiem dla narzędzi. Nie są wymagane
do zwykłej pracy w workspace.
## Szybki start
Najpierw zobacz konfiguracje i dostepne komendy:
Najpierw zobacz konfigurację i dostępne komendy:
```bash
./rvctl
./rvctl show-config
```
Typowy przeplyw pracy:
Typowy przepływ pracy:
```bash
./rvctl tokens compare
@@ -327,17 +329,17 @@ Typowy przeplyw pracy:
```
`--dry-run` jest przydatny przy sprawdzaniu planu uruchomienia lub konfiguracji
repo, zanim narzedzie cos zmieni.
repo, zanim narzędzie coś zmieni.
## Dokumentacja
- `doc/rvctl.md` - techniczna dokumentacja CLI: wszystkie komendy, argumenty
i przelaczniki
- `doc/tokens.md` - model tokenow, synchronizacja remote <-> store
i przełączniki
- `doc/tokens.md` - model tokenów, synchronizacja remote <-> store
- `doc/series.md` - docelowy model komend dla serii i kart pracy
- `doc/containers.md` - docelowy model komend dla srodowisk kontenerowych
- `doc/containers.md` - docelowy model komend dla środowisk kontenerowych
- `doc/tokens.schema.json` - schemat `tokens/tokens.json`
- `doc/workspace.md` - krotki opis konfiguracji workspace
- `doc/workspace.md` - krótki opis konfiguracji workspace
README jest tylko mapa projektu. Szczegoly operacyjne trzymamy w `doc/`, zeby
nie dublowac instrukcji w kilku miejscach.
README jest tylko mapą projektu. Szczegóły operacyjne trzymamy w `doc/`, żeby
nie dublować instrukcji w kilku miejscach.