Deploy RiscEmu in a JupyterLite distribution. (#18)

* Try and deploy a RiscEmu JupyterLite distribution.

* Add examples to the JupyterLite deployment.

* Add some demo notebooks and link to it in Readme.

Co-authored-by: Emilien Bauer <bauer.emilien@gmail.com>

.github/workflows/jupyterlite.yml

@@ -0,0 +1,100 @@
+name: Deploy JupiterLite Page
+
+on:
+  # Trigger the workflow on push or pull request,
+  # but only for the master branch
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout RiscEmu
+        uses: actions/checkout@v3
+        with:
+          path: riscemu
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install jupyterlite[all] libarchive-c build pyodide-build
+          
+      - name: Build RiscEmu source distribution
+        run: |
+          cd riscemu
+          python setup.py sdist
+
+      # Pyodide is cached, so cloned only if not present in the cache, otherwise
+      # just checked out to whatever desired version and partially rebuilt.
+
+      - name: Restore cached Pyodide tree
+        id: cache-pyodide
+        uses: actions/cache@v3
+        with:
+          path: pyodide
+          key: pyodide
+          
+      - name: Clone pyodide if not cached
+        if: steps.cache-pyodide.outputs.cache-hit != 'true'
+        run: git clone https://github.com/pyodide/pyodide.git
+
+      # Clean the xDSL and FrozenList package folders, generate their skeletons
+      # and do the necessary updates before building.
+      - name: Build custom Pyodide distribution
+        run: |
+          
+          cd pyodide
+          git fetch --all
+          git checkout 0.22.0a3
+          python -m pip install -r requirements.txt
+          sudo apt update && sudo apt install f2c
+          
+          rm -rf packages/riscemu
+          pyodide skeleton pypi riscemu
+          
+          PYODIDE_PACKAGES="riscemu" make
+
+      - name: Build the JupyterLite site
+        run: |
+          mkdir content
+          cp riscemu/docs/* content -r
+          cp riscemu/examples content -r
+          
+          rm -rf pyodide/pyodide
+          mkdir pyodide/pyodide
+          mv pyodide/dist pyodide/pyodide/pyodide
+          
+          python -m jupyter lite build --contents content --pyodide pyodide/pyodide
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./_output
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1
+
+

README.md

@@ -31,6 +31,8 @@ Hello world
 Program exited with code 0
 ```
 
+If you want to run it from a python script, here is [an online demo](https://AntonLydike.github.io/riscemu/lab/index.html?path=PythonDemo.ipynb).
+
 The [`read` syscall](docs/syscalls.md) defaults to readline behaviour. Reading "true chunks" (ignoring newlines) is currently not supported.  
 
 See the docs on [asembly](docs/assembly.md) for more detail on how to write assembly code for this emulator.

docs/PythonDemo.ipynb

@@ -0,0 +1,53 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Using RiscEmu from Python\n",
+    "\n",
+    "Here is how you can run some assembly through RiscEmu from Python.\n",
+    "\n",
+    "This example is using [this fibonacci assembly](examples/fibs.asm)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from riscemu import RunConfig, UserModeCPU, RV32I, RV32M, AssemblyFileLoader\n",
+    "\n",
+    "cfg = RunConfig(debug_instruction=False, verbosity=50)\n",
+    "cpu = UserModeCPU((RV32I, RV32M), cfg)\n",
+    "\n",
+    "loader = AssemblyFileLoader.instantiate('examples/fibs.asm', [])\n",
+    "cpu.load_program(loader.parse())\n",
+    "\n",
+    "cpu.launch(cpu.mmu.programs[-1], True)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

examples/fibs.asm

@@ -10,7 +10,6 @@ main:
         addi    s2, zero, 56    ; last storage index
         addi    t0, zero, 1     ; t0 = F_{i}
         addi    t1, zero, 1     ; t1 = F_{i+1}
-        ebreak                  ; launch debugger
 loop:
         sw      t0, fibs(s1)    ; save
         add     t2, t1, t0      ; t2 = F_{i+2}
@@ -19,7 +18,6 @@ loop:
         addi    s1, s1, 4       ; increment storage pointer
         blt     s1, s2, loop    ; loop as long as we did not reach array length
         ; exit gracefully
-        ebreak                  ; launch debugger
         addi    a0, zero, 0
         addi    a7, zero, 93
-        scall                   ; exit with code 0
+        scall                   ; exit with code 0