musique/README.md

# Musique interpreter

Interpreter języka Musique. Możliwy do wykorzystywania jako:

- biblioteka interpretera języka dołączana do innego projektu (podobnie jak Lua);
- REPL działający w systemie GNU/Linux + ALSA wykonujący język Musique.

## Wymagane pakiety systemowe

Do poprawnego skompilowania i uruchomienia interpretera języka Musique należy posiadać zainstalowane następujące pakiety (lub ich odpowiedniki) – dla systemu GNU/Linux Ubuntu Desktop 22.04 są to:

- `build-essential` – pakiet zawierający podstawowe narzędzia do pracy z kodem źródłowym, takie jak m.in. kompilator;
- `libasound2-dev` – pakiet zawierający biblioteki programistyczne pakietu `libasound2`.

Można je zainstalować korzystając z polecenia:

```
$ sudo apt update
$ sudo apt install -y build-essential libasound2-dev
```

## Budowanie interpretera

Jeśli nie posiadasz zależności `lib/midi` to:

```console
$ git submodule init
$ git submodule update
$ (cd lib/midi; make)
```

A następnie zbuduj interpreter:

```console
$ make bin/musique
```

Żeby zainstalować interpreter języka Musique w systemie, należy dodatkowo wykonać polecenie:

```
# make install
```

*Uwaga*: powyższe polecenie instalacyjne musi zostać wykonane jako uprzywilejowany użytkownik (np. wykorzystując polecenie `sudo`).

## Dostępne komendy

- `make` - Buduje interpreter `bin/musique` (tryb release)
- `make debug` - Buduje interpreter `bin/debug/musique` (tryb debug)
- `make clean` - Usuwa reprodukowalne elementy projektu (automatycznie stworzone pliki binarne czy raporty)
### Dokumentacja

- `make doc` - Tworzy `doc/build/html/` zawierający dokumentację projektu

### Testowanie

- `make test` - Uruchom wszystkie dostępne testy automatyczne
- `make unit-tests` - Uruchamia testy jednostkowe interpretera
- `make unit-test-coverage` - Uruchamia raport pokrycia kodu przez testy jednostkowe
- `scripts/test.py test examples` - Uruchamia testy zachowań przykładów
- `scripts/test.py record examples` - Nagrywa testy zachowań przykładów

### Debugowanie

- `scripts/log-function-calls.sh` - Tworzy listę wywołań funkcji używając GDB

## Budowa projektu

```
.
├── bin            Miejsce produkcji plików wykonywalnych
├── coverage
├── doc            Dokumentacja języka, interpretera
│   └── build      Miejsce produkcji dokumentacji
├── editor         Pluginy do edytorów dodające wsparcie dla języka
├── lib            Zewnętrzne zależności projektu
│   ├── expected
│   └── ut
└── include        Główny katalog z plikami nagłówkowymi
├── scripts        Skrypty wspierające budowanie i tworzenie
└── src            Główny katalog z plikami źródłowymi
    └── tests      Katalog z testami jednostkowymi
```

## Kolorowanie składni

### Vim / Neovim

Skopiuj plik [etc/editor/musique.vim](etc/editor/musique.vim) do folderu `syntax` wewnątrz twojej konfiguracji Vima (Neovima). Np:

```console
$ cp editor/musique.vim ~/.config/nvim/syntax/
```

Następnie musisz dodać ustawienie typu pliku na podstawie rozszerzenia wewnątrz twojej konfiguracji:

```vim
au BufRead,BufNewFile *.mq set filetype=musique
```

### Visual Studio Code

Skopiuj katalog [etc/editor/musique-vscode](etc/editor/musique-vscode) do folderu `<user home>/.vscode/extensions` i uruchom ponownie program VSCode.

# Thanks to

- Creator of [tl::expected](https://github.com/TartanLlama/expected) - [Sy Brand](https://sybrand.ink/)
- Creator of [bestline](https://github.com/jart/bestline) - [Justine Tunney](https://justinetunney.com/)