Merge pull request #11 from matushorvath/remove-javascript

Restructure the repo

.github/workflows/build.yml

@@ -7,29 +7,8 @@ on:
       - main
 
 jobs:
-  build-javascript:
-    name: JavaScript
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Node.js 20.x
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install cc65
-        run: sudo apt install -y cc65
-
-      - name: Test
-        working-directory: js
-        run: |
-          npm install
-          npm test
-
-  build-intcode:
-    name: Intcode
+  build:
+    name: Build and Test
     runs-on: ubuntu-latest
 
     env:
@@ -44,43 +23,41 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: matushorvath/xzintbit
-          path: ic/xzintbit
+          path: xzintbit
 
       - name: Build xzintbit
-        working-directory: ic/xzintbit
+        working-directory: xzintbit
         run: make build-vm
 
       - name: Checkout Microsoft Basic
         uses: actions/checkout@v4
         with:
           repository: matushorvath/msbasic
-          path: ic/msbasic
+          path: msbasic
 
       - name: Install cc65
         run: sudo apt install -y cc65
 
       - name: Build Microsoft Basic
-        working-directory: ic/msbasic
+        working-directory: msbasic
         run: ./make.sh
 
       - name: Checkout 6502 functional tests
         uses: actions/checkout@v4
         with:
           repository: Klaus2m5/6502_65C02_functional_tests
-          path: ic/6502_65C02_functional_tests
+          path: 6502_65C02_functional_tests
 
       - name: Build
-        working-directory: ic
         run: make build
 
       - name: Test
-        working-directory: ic
         run: make test
 
       - name: Store artifact
         uses: actions/upload-artifact@v4
         with:
           name: msbasic.input
-          path: ic/bin/msbasic.input
+          path: bin/msbasic.input
           if-no-files-found: error
         if: github.ref == 'refs/heads/main'

.gitignore

@@ -1,3 +1,2 @@
-node_modules
-/ic/obj
-/ic/bin
+/obj
+/bin

ic/Makefile → Makefile

@@ -12,7 +12,7 @@ ICLD ?= $(abspath $(ICDIR)/bin/ld.input)
 ICLDMAP ?= $(abspath $(ICDIR)/bin/ldmap.input)
 LIBXIB ?= $(abspath $(ICDIR)/bin/libxib.a)
 
-SRCDIR = .
+SRCDIR = src
 BINDIR ?= bin
 OBJDIR ?= obj
 

README.md

@@ -2,48 +2,49 @@
 
 # Microsoft Basic on an Intcode Runtime
 
-VM6502 is a simple virtual nachine emulating the MOS 6502 processor, capable of running Microsoft Basic.
-There are two implementations of VM6502 in this repository: one in JavaScript and one in [Intcode](https://esolangs.org/wiki/Intcode).
+VM6502 is a virtual machine emulating the MOS 6502 processor, and is capable of running Microsoft Basic. The 6502 virtual machine itself is implemented in [Intcode](https://esolangs.org/wiki/Intcode), which a machine language specification introduced as part of [Advent of Code 2019](https://adventofcode.com/2019).
 
-## Intcode
+## Implementation Details
 
-The Intcode version of the 6502 emulator is written in Intcode assembly, which is a language that can be translated
-into raw Intcode using my [xzintbit](https://github.com/matushorvath/xzintbit) Intcode assembler and linker.
-(The assembler and linker are also written in Intcode, by the way, and are self-hosting.)
+The 6502 emulator is written in Intcode assembly, which is a language that can be translated
+into raw Intcode using my [xzintbit](https://github.com/matushorvath/xzintbit) Intcode assembler and linker. The assembler and linker are also written in Intcode, and are self-hosting.
 
-![Screenshot of Intcode VM6502 running Microsoft Basic](docs/screenshot-intcode.png)
+## Trying it Out
 
-You can try to run Microsoft Basic on an Intcode runtime yourself:
-1. Clone and build the [xzintbit](https://github.com/matushorvath/xzintbit) repository.
-   Please see the documentation in that repository.
-   You can either use your own Intcode runtime, or use one of the runtimes in the xzintbit repository.
-1. Clone and build the [msbasic](https://github.com/matushorvath/msbasic) repository,
-   which is a slightly modified Microsoft Basic version that can run on an emulated 6502.
-1. Clone the [functional tests](https://github.com/Klaus2m5/6502_65C02_functional_tests) repository (no need to build it).
-1. Build the intcode image. Assuming the paths were these three repositories are cloned:
+You will need an Intcode virtual machine. Perhaps you created one as part of solving Advent of Code 2019. If it can run all Advent of Code assignments, it should be good enough to run Microsoft Basic as well.
+
+Download the pre-built [`msbasic.input`](TODO) file from this repository and run it with your Intcode virtual machine. If everything goes correctly, you should see a "MEMORY SIZE?" prompt from the Microsoft Basic interpreter.
+
+The `msbasic.input` file contains plain Intcode in the same format that was used by Advent of Code assignments. It requires about 165536 "bytes" of Intcode memory, and should work fine even with Intcode VMs that use signed 32-bit integers.
+
+![Screenshot of Intcode VM6502 running Microsoft Basic](docs/screenshot.png)
+
+# Building it Yourself
+
+This projects has multiple parts that you'll need to get working if you want to rebuild the sources. (This is not needed if you just want to see Microsoft Basic running on your Intcode virtual machine; see the [Trying it Out](#trying-it-out) section above.)
+
+- You will need an Intcode virtual machine. Feel free to use your own, or you can use one of the Intcode virtual machines in the `vms` directory in the [xzintbit](https://github.com/matushorvath/xzintbit) repository.
+- You will need the Intcode assembler and linker itself. Please clone and build the [xzintbit](https://github.com/matushorvath/xzintbit) repository. See documentation in that repository for details, but a simple `make` should be enough to get you some results.
+- Clone and build the [msbasic](https://github.com/matushorvath/msbasic) repository. This is a a slightly modified Microsoft Basic version that can run on an emulated 6502.
+- Clone the [functional tests](https://github.com/Klaus2m5/6502_65C02_functional_tests) repository (no need to build it). This is used as a test suite to validate the 6502 virtual machine is working correctly.
+
+Now you can the `msbasic.input` Intcode image. Please substitute the correct paths where the three repositories mentioned above were cloned.
    ```sh
    $ ICDIR=~/xzintbit MSBASICDIR=~/msbasic FUNCTESTDIR=~/6502_65C02_functional_tests make test
    ```
-1. Execute the built image:
+
+The functional tests take a minute or two to finish. If the build process looks frozen and the last output line mentions `func_tests.input`, you're probably still waiting for the tests. You can skip the tests by running a plain `make` instead of `make test`.
+
+Now you can execute the newly built image:
    ```sh
    $ ~/xzintbit/vms/c/ic bin/msbasic.input
    ```
 
-## JavaScript
-
-The JavaScript version of the 6502 emulator was really a proof of concept. Before diving into Intcode, I wanted to
-proof I can write a working 6502 emulator in a more sane programming language.
-
-![Screenshot of JavaScript VM6502 running Microsoft Basic](docs/screenshot-javascript.png)
-
-You can also run the Microsoft Basic using the JavaScript VM6502:  
-```sh
-$ node js/main.mjs --load c000 ~/msbasic/tmp/vm6502.bin
-```
+You should now see the `MEMORY SIZE?` prompt from Microsoft Basic. Enter a reasonable memory size, for example `32786`, and a reasonable terminal width, for example `40`. Now you can start interacting with Basic (try `PRINT "HELLO WORLD"`).
 
 ## Q & A
 
-Q: How complete is the emulation?  
+Q: How complete is the 6502 emulation?  
 A: All officially documented instructions are emulated. The virtual machine passes [6502 functional tests](https://github.com/amb5l/6502_65C02_functional_tests).
 
 Q: Why?