Tirsvad
f8ccfca02e
A Debian image (python:3.13-slim-bookworm with Xvfb and GNOME's window manager) runs the linters, the whole test suite, the screenshots and the smoke test of a PyInstaller Linux binary and of the source program, so no window opens on the development machine. The screenshot tool works on Linux, a smoke driver presses the known button with the virtual mouse, and Windows Sandbox scripts are written (not run, they open a window on the host). README and the wiki Install pages describe it. Review records RC-077 (Python) and RC-078 (shell). Task: MIL-013#2 Task: MIL-013#3 Task: MIL-013#4 Task: MIL-013#5 Task: MIL-013#6 Task: MIL-013#7 Task: MIL-013#9 Task: MIL-013#10
104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
# Installation
|
|
|
|
🌐 [English](Install) · **Dansk** · [Bahasa Malaysia](Install-ms)
|
|
|
|
## Krav
|
|
|
|
- Python 3.13 eller nyere med Tkinter (på Debian eller Ubuntu: `sudo apt install python3-tk`).
|
|
- `git`.
|
|
- Valgfrit: en internetforbindelse og tilvalget `speech`, hvis du vil høre det malajiske ord.
|
|
|
|
## Hent koden
|
|
|
|
```bash
|
|
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card.git
|
|
cd 031-flash-card
|
|
```
|
|
|
|
## Opret og brug et lokalt virtuelt miljø
|
|
|
|
Windows (PowerShell):
|
|
|
|
```powershell
|
|
python -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
python -m pip install --upgrade pip
|
|
python -m pip install -e ".[dev]"
|
|
```
|
|
|
|
Linux og macOS:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
python -m pip install --upgrade pip
|
|
python -m pip install -e ".[dev]"
|
|
```
|
|
|
|
- `.[dev]` tilføjer `pytest`, `ruff`, `mypy` og `import-linter`. Brug `.`, hvis du kun vil køre programmet.
|
|
- Hvis PowerShell nægter at køre `Activate.ps1`, så kør `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` én gang.
|
|
- Forlad miljøet med `deactivate`; slet mappen `.venv` for at starte forfra.
|
|
|
|
## Udtalt malajisk ord (valgfrit)
|
|
|
|
```bash
|
|
python -m pip install -e ".[speech]"
|
|
```
|
|
|
|
Det installerer `gTTS` og `playsound==1.2.2`. Uden tilvalget virker programmet uden lyd.
|
|
|
|
## Kør og test
|
|
|
|
```bash
|
|
python -m flash_card
|
|
python -m pytest
|
|
```
|
|
|
|
Vinduestesten i `tests/e2e/` springes over, når der ikke er en skærm.
|
|
|
|
## Udgivelse og programfil (Windows)
|
|
|
|
Udgivelsessiderne for [v0.2.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.2.0) og [v0.1.0](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0) har udgivelsesnoterne. Programfilen er endnu ikke vedhæftet, fordi serverens grænse for upload afviser en fil af denne størrelse (HTTP 413); byg den som beskrevet nedenfor. Filen er ikke signeret, så Windows kan vise en SmartScreen-advarsel.
|
|
|
|
## Byg en programfil (Windows)
|
|
|
|
```powershell
|
|
python -m pip install -e ".[build,speech]"
|
|
python tools/build_executable.py
|
|
```
|
|
|
|
Scriptet bruger PyInstaller og skriver `dist/flash-card.exe`: én fil uden konsolvindue, med billeder, ordliste og udtalen indeni. Dobbeltklik for at starte; Python er ikke nødvendigt for at køre den.
|
|
|
|
- Din fremgang gemmes i en `data/`-mappe ved siden af programfilen (`data/words_to_learn.csv`).
|
|
- En `data/ms-da.csv` ved siden af programfilen erstatter ordlisten indeni.
|
|
- `python tools/build_executable.py --no-speech` udelader talepakkerne; `--clean` bygger forfra.
|
|
- Programfilen er ikke i repositoryet. Byg den på det system, hvor den skal køre; Windows kan vise en SmartScreen-advarsel, fordi filen ikke er signeret.
|
|
|
|
## Kontroller uden skrivebord (Docker)
|
|
|
|
Testene, linterne, skærmbillederne og en røgtest af en Linux-binær kører i en Debian-container på en virtuel skærm, så der ikke åbnes noget vindue på dit eget skrivebord.
|
|
|
|
```bash
|
|
docker build -f docker/debian.Dockerfile -t flash-card-debian .
|
|
# linters og hele testsuiten, også testene af det rigtige vindue
|
|
docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh run-checks.sh
|
|
# skærmbilleder til ./build/container-out
|
|
docker run --rm -v "$PWD:/repo:ro" -v "$PWD/build/container-out:/out" flash-card-debian bash /repo/tools/docker/in-container.sh screenshots.sh /out
|
|
# byg Linux-binæren og tryk på "kender" 5 gange (binær og kildekode)
|
|
docker run --rm -v "$PWD:/repo:ro" flash-card-debian bash /repo/tools/docker/in-container.sh smoke-binary.sh 5
|
|
```
|
|
|
|
I Windows PowerShell skriver du `${PWD}` i stedet for `$PWD`. Repositoryet monteres skrivebeskyttet og kopieres inde i containeren.
|
|
|
|
- Skrivebordet er Xvfb med GNOMEs vindueshåndtering (mutter). GNOME Shell prøves først og starter ikke i en container (den kræver en login-manager), så scripts falder tilbage til mutter og skriver hvilken der kørte.
|
|
- Windows-programfilen kontrolleres i **Windows Sandbox** (Windows 11 Pro, funktionen aktiveret): `powershell -File tools\sandbox\run.ps1 -Runs 5` efter `python tools/build_executable.py`. Sandboxen viser sit eget vindue, mens den kører; klikket sker inde i sandboxen.
|
|
- Ikke dækket: macOS (kan ikke køres i Docker på Windows eller Linux, og Apples licens tillader det kun på Apple-hardware), og selve Windows i Debian-containeren.
|
|
|
|
## Dokumentation af kildekoden
|
|
|
|
```bash
|
|
doxygen Doxyfile
|
|
```
|
|
|
|
HTML-filerne skrives til `docs/doxygen/html/index.html`.
|