Tirsvad
9c8e294021
Milestone MIL-010, story US-001.08, BC-001 and PP-001 amended (the release of the executable is in scope), CHANGELOG.md for 0.1.0, and links to the release page in README and the Install page of the wiki. Review records RC-051 to RC-054, all Go (autonomous mode, not independent). Task: MIL-010#1 Task: MIL-010#2
84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
# Install
|
|
|
|
🌐 **English** · [Dansk](Install-da) · [Bahasa Malaysia](Install-ms)
|
|
|
|
## Requirements
|
|
|
|
- Python 3.13 or later with Tkinter (on Debian or Ubuntu: `sudo apt install python3-tk`).
|
|
- `git`.
|
|
- Optional: an internet connection and the `speech` extra to hear the Malay word.
|
|
|
|
## Get the code
|
|
|
|
```bash
|
|
git clone https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card.git
|
|
cd 031-flash-card
|
|
```
|
|
|
|
## Create and use a local virtual environment
|
|
|
|
Windows (PowerShell):
|
|
|
|
```powershell
|
|
python -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
python -m pip install --upgrade pip
|
|
python -m pip install -e ".[dev]"
|
|
```
|
|
|
|
Linux and macOS:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
python -m pip install --upgrade pip
|
|
python -m pip install -e ".[dev]"
|
|
```
|
|
|
|
- `.[dev]` adds `pytest`, `ruff`, `mypy` and `import-linter`. Use `.` if you only want to run the program.
|
|
- If PowerShell refuses to run `Activate.ps1`, run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
|
|
- Leave the environment with `deactivate`; delete the `.venv` folder to start over.
|
|
|
|
## Spoken Malay word (optional)
|
|
|
|
```bash
|
|
python -m pip install -e ".[speech]"
|
|
```
|
|
|
|
This installs `gTTS` and `playsound==1.2.2`. Without it the program works silently.
|
|
|
|
## Run and test
|
|
|
|
```bash
|
|
python -m flash_card
|
|
python -m pytest
|
|
```
|
|
|
|
The window test in `tests/e2e/` is skipped when no display is available.
|
|
|
|
## Download the executable (Windows)
|
|
|
|
Download `flash-card.exe` and `flash-card.exe.sha256` from the [release page](https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/releases/tag/v0.1.0). Compare the SHA-256 hash of the file with the checksum file (`certutil -hashfile flash-card.exe SHA256` on Windows). The file is not signed, so Windows may show a SmartScreen warning.
|
|
|
|
## Build an executable (Windows)
|
|
|
|
```powershell
|
|
python -m pip install -e ".[build,speech]"
|
|
python tools/build_executable.py
|
|
```
|
|
|
|
The script uses PyInstaller and writes `dist/flash-card.exe`: one file, no console window, with the images, the word list and the spoken word inside. Double-click it to start; Python is not needed to run it.
|
|
|
|
- Your progress is kept in a `data/` folder next to the executable (`data/words_to_learn.csv`).
|
|
- A `data/ms-da.csv` next to the executable replaces the word list inside it.
|
|
- `python tools/build_executable.py --no-speech` leaves the speech packages out; `--clean` rebuilds from scratch.
|
|
- The executable is not committed to the repository. Build it on the system you want to run it on; Windows may show a SmartScreen warning because the file is not signed.
|
|
|
|
## Documentation of the source code
|
|
|
|
```bash
|
|
doxygen Doxyfile
|
|
```
|
|
|
|
The HTML is written to `docs/doxygen/html/index.html`.
|