^{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
• Documentation & getting started.
• Project layout
• Build instructions
  • Docker (targets Linux)
  • Linux
    • Other
  • Windows
    • Steps
• Development
  • Testing
• Credits
  • Core
  • 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 modules written in Lua.

Working on

• IDE for easy development.
• High level language.

---

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.
• expansions Source code for all of the default expansions.

---

Build instructions

Build instructions exist for Linux and Windows (amd64). The project should compile for MacOS as well however this hasn't been tested.

Docker (targets Linux)

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

Partial cross compilation targeting Windows systems can be done on Linux, see Windows.

Perquisites

• Languages

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

• Build tools

  • Poetry
  • Mage

For Node I would recommend installing NVM (Node Version Manager).

Fedora

Tested on Fedora 42.

x11

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

Wayland

mesa-libGL-devel wayland-devel libxkbcommon-devel

Other

gtk3-devel golang golang-tests python3 

Audio

alsa-lib-devel

Building (For Linux)

1. Install the prerequisites that are mentioned above.

2. Check that everything works.

   $ node --version
    v22.13.1
   $ mage --version
    Mage Build Tool <not set>
    Build Date: <not set>
    Commit: <not set>
    built with: go1.24.5
   $ poetry --version
    Poetry version 1.1.13
   $ go version 
    go version go1.24.5 linux/amd64
   $ python3 --version
    Python 3.13.2
   

3. Clone the repository from GitHub

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

4. Activate the virtual environment for Python (unneeded if not using or building the Python frontend):

eval $(poetry env activate)

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

   mage build
   

   Alternatively you can run mage dev frontend.gp32,expansion.goputer.sys to only build the gp32 frontend.

6. Go to the build directory and run the hello_world.gp example.

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

Windows

TLDR;

• Windows executables can be built using cross compilation on Linux (run build_win.sh).
• mingw must be installed, in addition to the prerequisites listed under Linux.
• The gp32 frontend will cross compile however the goputerpy one will not, this is because pyinstaller does not support cross compilation.
• MSYS2 is the recommended compilation environment if you are compiling on Windows and targeting Windows.
• You may not be able to compile the web frontend on Windows.

Steps

1. Install MSYS2.
2. Once in MSYS2 (mingw64) install the required packages:

   pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-go mingw-w64-x86_64-nodejs mingw-w64-x86_64-python mingw-w64-x86_64-python-poetry mingw-w64-x86_64-python-certifi mingw-w64-x86_64-python-pip mingw-w64-x86_64-pyinstaller git
   

3. Install mage:

   export GOBIN=$HOME/go/bin
   export PATH=$GOBIN:$PATH
   go install github.com/magefile/mage@latest
   

   Note: You may need to set those environment variables again.
4. Clone the repository:

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

5. cd into the repository and install dependencies:

   cd goputer
   poetry install
   npm install
   

6. Build:

   sh ./build_win.sh
   

   Optionally run eval $(poetry env activate) if building the Python frontend as well. This output the location of the virtual environment activation script.

The result typically be in C:\msys64\home\username\goputer\build.

---

Development

In addition to the dependencies in Building, you should also have golangci-lint (V2) installed.

Testing

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

To run them use:

go test ./tests -v

---

Credits

Core

• Lua runtime - Shopify/go-lua
  • The Lua runtime used by expansions.

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.
• Mediabunny - Vanilagy/mediabunny
  • Used for recording and muxing MP4 files
• Zip.js - gildas-lormeau/zip.js
  • Used to create and load ZIP archives
• Dexie.js - dexie/Dexie.js
  • Used for interacting with IndexedDB.
• Comlink - GoogleChromeLabs/comlink
  • Used to provide a easier interface between the worker/runtime and UI threads.

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.
• Tview - rivo/tview
  • Used for the profiler UI.

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