From ce30d10a355daf975fec817fe9ee9ca8ea9cad8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ismael=20Venegas=20Castell=C3=B3?= Date: Sun, 14 Apr 2024 12:51:46 -0600 Subject: [PATCH] Update readme and makefile, add installation commands and instructions. --- Makefile | 46 ++++++++++++++++++++++---- README.md | 62 +++++++++++++++++++++++++----------- utils/{kvr2tal.py => kvrptr} | 0 utils/tal2kvr.py | 2 -- 4 files changed, 83 insertions(+), 27 deletions(-) rename utils/{kvr2tal.py => kvrptr} (100%) delete mode 100644 utils/tal2kvr.py diff --git a/Makefile b/Makefile index 0b5a0e1..f7fbb51 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,9 @@ +en: setup +ifeq (,$(wildcard bin/kvrasm)) + @echo "Building kvrasm executable." + @gcc src/kvrasm.c -o bin/kvrasm +endif + all: en es eo tok setup: @@ -11,12 +17,6 @@ ifeq (,$(wildcard roms)) @mkdir roms endif -en: setup -ifeq (,$(wildcard bin/kvrasm)) - @echo "Building kvrasm executable." - @gcc src/kvrasm.c -o bin/kvrasm -endif - es: setup ifeq (,$(wildcard bin/kvrasm-es)) @echo "Building kvrasm-es executable." @@ -35,23 +35,55 @@ ifeq (,$(wildcard bin/kvrasm-tok)) @gcc src/kvrasm.c -o bin/kvrasm-tok -D LANG_TOK endif -test: all +test-all: test test-es test-eo test-tok + +test: en @echo "Testing kvrasm." @bin/kvrasm examples/english/sierpinski.kvr roms/sierpinski.rom @uxncli roms/sierpinski.rom +test-es: es @echo "Testing kvrasm-es." @bin/kvrasm-es examples/spanish/sierpinski.kvres roms/sierpinski-es.rom @uxncli roms/sierpinski-es.rom +test-eo: eo @echo "Testing kvrasm-eo." @bin/kvrasm-eo examples/esperanto/sierpinski.kvreo roms/sierpinski-eo.rom @uxncli roms/sierpinski-eo.rom +test-tok: tok @echo "Testing kvrasm-tok." @bin/kvrasm-tok examples/toki-pona/sierpinski.kvrtok roms/sierpinski-tok.rom @uxncli roms/sierpinski-tok.rom +install-all: all install install-es install-eo install-tok + +install: en install-setup install-path + @echo "Installing kvrasm at ~/bin directory." + @cp bin/kvrasm ~/bin + +install-es: es install-setup install-path + @echo "Installing kvrasm-es at ~/bin directory." + @cp bin/kvrasm-es ~/bin + +install-eo: eo install-setup install-path + @echo "Installing kvrasm-eo at ~/bin directory." + @cp bin/kvrasm-eo ~/bin + +install-tok: tok install-setup install-path + @echo "Installing kvrasm-tok at ~/bin directory." + @cp bin/kvrasm-tok ~/bin + +install-path: + @echo "Make sure that ~/bin is in your PATH." + +install-setup: +ifeq (,$(wildcard ~/bin)) + @echo "Creating ~/bin directory." + @mkdir ~/bin +endif + clean: ifneq (,$(wildcard bin)) @echo "Deleting bin directory." diff --git a/README.md b/README.md index 5e21b0d..2743944 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,17 @@ # Kvara -Kvara is an assembler with i18n (internationalization) support for the Varvara/Uxn ecosystem forked from the reference assembler uxnasm implemented in C. +Kvara is an assembler with i18n (internationalization) support for the +Varvara/Uxn ecosystem, forked from the reference *uxnasm* assembler implemented +in C. -- **kvara** means fourth in Esperanto. -- **kvara** rhymes with varvara. -- **kvara** is the fourth uxntal assembler I have used, the others are: *uxnasm*, *asma* and *drifblim*. +### What is the meaning of *Kvara*? + +- **Kvara** means *fourth* in Esperanto. +- **Kvara** rhymes with Uxn's *Varvara*. +- **Kvara** is the fourth Uxntal assembler that I have used, the others were: + *uxnasm*, *asma* and *drifblim*. +- **Kvara** is also a reference to the *Forth* programming langauge, which led + me to the Uxn ecosystem. ### Supported Languages @@ -16,8 +23,8 @@ Kvara is an assembler with i18n (internationalization) support for the Varvara/U ## Build ```bash -$ make # All versions. -$ make en # English version. +$ make # English version. +$ make all # All versions. $ make es # Spanish version. $ make eo # Esperanto version. $ make tok # Toki pona version. @@ -26,26 +33,46 @@ $ make tok # Toki pona version. ## Usage ```bash -$ kvrasm[-es|-eo|-tok] input.kvr[es|eo|tok] output.rom +$ kvrasm[-es|-eo|-tok] input.kvr[es|eo|tok] [output.rom] ``` ## Test ```bash -$ make test # Test all versions. -$ make test-en # Test English version. +$ make test # Test English version. +$ make test-all # Test all versions. $ make test-es # Test Spanish version. $ make test-eo # Test Esperanto version. $ make test-tok # Test Toki pona version. +``` + +## Install + +```bash +$ make install # Install English version. +$ make install-all # Install all versions. +$ make install-es # Install Spanish version. +$ make install-eo # Install Esperanto version. +$ make install-tok # Install Toki pona version. +``` +The executables are installed at `~/bin`, make sure that this directory is in +your `PATH` and that you have sourced your shell configuration file, for example +`~/.bashrc` or start a new shell session for Kvara assembler(s) to be available +from any directory. + +```bash +$ make install +$ echo "export PATH=$PATH:~/bin" >> ~/.bashrc +$ source ~/.bashrc ``` ## Differences From Uxnasm -- Kvara supports `\ comment` (backslash+space) Forth style comments, these are not - part of the Uxntal specification which only support `( comment )` - (there must whitespace after the opening `( ` and closing ` )` parenthesis) - Forth style comments. +- Kvara supports `\ comment` backslash space Forth style comments, these are + not part of the Uxntal specification which only supports `( comment )` + parenthesis Forth style comments (there must whitespace after the opening + `(` and closing `)` parenthesis). ## Utils @@ -56,8 +83,7 @@ $ make test-tok # Test Toki pona version. ## TODO -- [ ] Make `kvr2tal.py` better. -- [ ] Make `tal2kvr.py`. -- [ ] Explain how to contribute and add a new language. -- [ ] Implement another utility to scafold and make easier adding new languages. -- [ ] Use the opcode test for all languages. +- [] Implement `kvrptr` (Kvara porter). +- [] Explain how to contribute and add a new language. +- [] Implement another utility to scafold and make easier adding new languages. +- [] Use the opcode test for all languages. diff --git a/utils/kvr2tal.py b/utils/kvrptr similarity index 100% rename from utils/kvr2tal.py rename to utils/kvrptr diff --git a/utils/tal2kvr.py b/utils/tal2kvr.py deleted file mode 100644 index 09d65dc..0000000 --- a/utils/tal2kvr.py +++ /dev/null @@ -1,2 +0,0 @@ -if __name__ == '__main__': - pass \ No newline at end of file