^{Go + Computer = goputer}

---

A computer emulator/virtual machine that intends to demonstrate how basic computers work at a low level.

---

Contents

• Features
  • Complete
  • Working on
  • In the future
• Documentation & getting started.
• Project layout
• Build instructions
  • Docker
  • Linux
• Testing
• Credits
  • GP32 Frontend
  • goputerpy Frontend
  • Web playground/frontend.
  • CLI tool
  • GUI launcher
  • Other
• License

---

Features

Complete

• Custom assembly language and compiler.
• Custom runtime.
• Standalone executables.
• Frontends to show VM output.
• A WASM based runtime that runs in a web browser.
• Expansion cards/modules.

Working on

• IDE for easy development.

In the future

• Rewrite of compiler.
• High level language.
• Non-native plugins via Lua.

---

Documentation & getting started.

See the project wiki or try the playground at goputer.oscarcp.net.

---

Project layout

• frontends Contains source for the frontends.
• frontends/web The WASM frontend.
• frontends/gp32 The Go frontend.
• frontends/goputerpy The Python frontend.
• examples A list of example code to get started with.
• cmd/goputer The CLI tool for compiling, running & disassembling code.
• cmd/launcher The GUI for running code.
• pkg Shared code. Includes the compiler, VM runtime and constants for instructions and registers.

---

Build instructions

Build instructions for Linux, other platforms are not supported at the moment as native plugins do not work at all. See plugin

Docker

If you have Docker installed, you can build goputer in Docker without installing additional dependencies by running:

./docker_entrypoint.sh

This will build the container and then run mage dev inside the container, outputting to the build directory.

Note: This uses a Fedora container, so the output will only work on Linux based systems.

Linux

Perquisites

• Languages

  • Python ^3.10
  • Go ^1.19
  • NodeJS ^18.X

• Build tools

  • Poetry
  • Mage

• Library requirements

  Requirements for different display servers & audio.

  Ubuntu

  x11

  libgl1-mesa-dev libxi-dev libxcursor-dev libxrandr-dev libxinerama-dev
  

  Wayland

  libgl1-mesa-dev libwayland-dev libxkbcommon-dev 
  

  Audio

  libasound2-dev
  

  Fedora

  x11

  mesa-libGL-devel libXi-devel libXcursor-devel libXrandr-devel libXinerama-devel
  

  Wayland

  mesa-libGL-devel wayland-devel libxkbcommon-devel
  

  Audio

  alsa-lib-devel
  

Building

1. Install the prerequisites that are mentioned above.

2. Check that everything works.

   $ node --version
   v18.12.1
   $ mage --version
   Mage Build Tool v1.14.0
   Build Date: 2022-11-09T16:45:13Z
   Commit: 300bbc8
   built with: go1.19.3
   $ poetry --version
   Poetry version 1.1.13
   

3. Clone the repository from GitHub

   git clone https://github.com/sccreeper/goputer
   cd goputer
   

4. Build the project. (This step shouldn't take that long depending on your hardware)

   mage dev
   

   Alternatively you can run mage all to not build the examples.

5. Go to the build directory and run the hello_world example.

   cd build
   ./goputer run -f gp32 -e ./examples/hello_world
   

---

Testing

There a small suite of tests written for testing the core of goputer.

To run them use:

go test ./tests -v

---

Credits

GP32 Frontend

• Raylib Go Bindings - gen2brain/raylib-go
  • Very useful rendering library.
  • See also: Raylib - raysan5/raylib
• Beep - faiface/beep
  • Used for producing sound on the fly.
• TOML - BurntSushi/toml
  • Configuration format used by frontends.
  • See also: TOML - toml-lang/toml

goputerpy Frontend

• pygame - pygame/pygame
  • Used for rendering & sound output.
• numpy - numpy/numpy
  • Used partially for sound generation
• poetry - python-poetry/poetry
  • Very useful for Python dependency management.

Web playground/frontend.

• Tailwind CSS - tailwindlabs/tailwindcss
  • CSS library used to build the UI.
• Parcel - parcel-bundler/parcel
  • Module bundler.
• Parcel Static Files Copy - elwin013/parcel-reporter-static-files-copy
  • Used for copying static files into the final dist directory.
• Bootstrap Icons - twbs/icons
  • Icons used heavily by the UI.
• Microtip - ghosh/microtip
  • Tooltip library used in UI.

CLI tool

• CLI - urfave/cli
  • Used by the compiler for getting input from the terminal.
• Color - fatih/color
  • Used for colouring & formatting the terminal output i.e. making it look nice.
• Termlink - savioxavier/termlink
  • Inserting links into the terminal.

GUI launcher

• Fyne - fyne-io/fyne
  • UI library used
• dialog - sqweek/dialog
  • Used for file open dialogs.

Other

• Mage - magefile/mage
  • Build system used for development.

---

License

MIT - Refer to the LICENSE file