stem-launcher/doc/containers.md

Containers

Ten dokument opisuje docelowy model komend rvctl do uruchamiania środowiska programistycznego w kontenerach.

Zasada

Kontener jest środowiskiem pracy dla wybranej karty, opcjonalnie zawężonym do konkretnego zadania. rvctl uruchamia je przez sesję tmux, tak aby terminal z kontenerem był łatwy do ponownego podłączenia.

Używamy namespace containers, a nie container, bo jest spójny z pluralnymi namespace'ami tokens, cards i tasks.

Szybki przepływ

Typowy przepływ pracy:

./rvctl tokens compare
./rvctl series cards show inf 03
./rvctl series cards tasks list inf 03
./rvctl containers show inf 03
./rvctl containers start inf 03 --session rv-inf03 --attach
./rvctl containers list
./rvctl containers stop rv-inf03

Model

Docelowo komendy containers pracują na trzech warstwach:

• karta pracy, np. inf 03
• opcjonalne zadanie, np. --task task1
• instancja środowiska, np. --instance shell

Domyślne wartości pochodzą z workspace.json:

defaults.series
defaults.card
defaults.task
defaults.instance
defaults.tmux_session
defaults.tmux_window

Komendy

containers show [SERIES] [CARD]

Pokazuje plan uruchomienia środowiska bez tworzenia sesji tmux.

./rvctl containers show inf 03
./rvctl containers show inf/03 --task task1

Typowe pola:

selector        inf/03
task            task1
card_path       ~/dev/workspace/rv/series/inf/03
task_path       ~/dev/workspace/rv/series/inf/03/task1
tools_root      ~/dev/workspace/rv/tools/rv32i-hazard3-env
session         rv-inf03
window          rv
instance        shell

Ta komenda jest odpowiednikiem obecnego trybu:

./rvctl tmux-container inf 03 --dry-run

containers start [SERIES] [CARD]

Uruchamia sesję tmux i kontener dla wybranej karty.

./rvctl containers start inf 03
./rvctl containers start inf/03 --session rv-inf03
./rvctl containers start inf 03 --task task1 --instance shell --attach

Przełączniki:

• --task TASK Wybiera zadanie w karcie. Bez tego rvctl używa domyślnego zadania z workspace.json albo pracuje na katalogu karty.
• --session NAME Nadpisuje nazwę sesji tmux.
• --window NAME Nadpisuje nazwę okna tmux.
• --instance NAME Ustawia wariant środowiska, np. shell.
• --attach Po uruchomieniu od razu podłącza terminal do sesji.

containers list

Listuje aktywne środowiska uruchomione przez rvctl.

./rvctl containers list

Przykładowy wynik:

session   selector  task   instance  window
--------  --------  -----  --------  ------
rv-inf03  inf/03    task1  shell     rv

containers attach SESSION

Podłącza terminal do istniejącej sesji.

./rvctl containers attach rv-inf03

Technicznie odpowiada to:

tmux attach -t rv-inf03

containers stop SESSION

Zamyka sesję tmux, a razem z nią uruchomiony w niej proces kontenera.

./rvctl containers stop rv-inf03

Technicznie odpowiada to:

tmux kill-session -t rv-inf03

Aliasowanie Starej Komendy

Stara komenda może zostać jako alias kompatybilności:

tmux-container inf 03 --dry-run      -> containers show inf 03
tmux-container inf 03 --session NAME -> containers start inf 03 --session NAME
tmux-container inf/03 --attach       -> containers start inf/03 --attach

Dokumentacja i nowe przykłady powinny promować namespace containers.