ARM Assembly Compiler and Remote Runner (PureScript)

A Visual Studio Code extension for compiling ARM assembly code and running it locally (with QEMU) or remotely (via SSH). Written in PureScript with minimal FFI.

Features

• Local Build: Assemble and link ARM assembly files using aarch64-linux-gnu-as and aarch64-linux-gnu-ld
• Local Execution: Run ARM binaries locally using QEMU (qemu-aarch64)
• Remote Build: Upload .s files to a remote device via SSH and build them there
• Remote Execution: Build and run ARM programs on remote hardware (e.g., Raspberry Pi)
• Status Bar Buttons: Quick access buttons in the VS Code status bar
• Editor Toolbar: Context-aware buttons when viewing .s files
• Output Channels: Real-time build and execution output

Prerequisites

Local Development

• aarch64-linux-gnu-as - ARM assembler
• aarch64-linux-gnu-ld - ARM linker
• qemu-aarch64 - ARM emulator (for local execution)

Install on Fedora/RHEL:

sudo dnf install binutils-aarch64-linux-gnu qemu-user

Install on Ubuntu/Debian:

sudo apt install binutils-aarch64-linux-gnu qemu-user

Remote Execution

• SSH access to a remote ARM device (e.g., Raspberry Pi)
• ARM toolchain installed on the remote device

Installation

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

4. Press F5 in VS Code to launch the extension development host

Configuration

Configure remote SSH connection in VS Code settings:

• polsl-arm-asm.sshHost - Remote device hostname or IP address
• polsl-arm-asm.sshPort - SSH port (default: 41)
• polsl-arm-asm.sshUser - SSH username
• polsl-arm-asm.sshPassword - SSH password
• polsl-arm-asm.remotePath - Remote directory path (default: /home)

Usage

Commands

Open the Command Palette (Ctrl+Shift+P) and use:

• ARM ASM: Assemble and link ARM Assembly (Local) - Build locally
• ARM ASM: Run ARM Assembly locally (using QEMU) - Run pre-built binary
• ARM ASM: Assemble + Link + Run locally - Build and run locally
• ARM ASM: Assemble and link ARM Assembly (Remote) - Build on remote device
• ARM ASM: Assemble + Link + Run remotely - Build and run on remote device

Status Bar Buttons

Four buttons appear in the status bar:

• 🔧 Build - Local build
• ▶️ Run Local - Build and run locally
• ☁️ Remote Build - Build on remote device
• 🌐 Remote Run - Build and run remotely

Keyboard Shortcuts

• Ctrl+Alt+R - Build and run locally

Project Structure

├── src/
│   ├── Main.purs              # Extension entry point
│   ├── VSCode.purs/js         # VS Code API bindings (FFI)
│   ├── SSH2.purs/js           # SSH2 client bindings (FFI)
│   ├── Compiler.purs          # Assembly and linking logic
│   ├── Runner.purs            # Local QEMU execution
│   ├── RemoteOperations.purs  # SSH remote build/run
│   ├── Config.purs            # Configuration loading
│   ├── ChildProcess.purs      # Process execution (native)
│   ├── Path.purs              # Path utilities (native)
│   └── FileSystem.purs        # File operations (native)
├── spago.dhall                # PureScript dependencies
├── packages.dhall             # Package set configuration
├── package.json               # NPM dependencies + extension manifest
├── bundle.js                  # Build script
└── out/extension.js           # Compiled extension (generated)

Development

Build

npm run compile

This runs:

1. spago build - Compiles PureScript to JavaScript modules
2. node bundle.js - Bundles with esbuild to out/extension.js

Watch Mode

npm run watch

Automatically recompiles on file changes (requires manual reload in VS Code).

Clean

npm run clean

Removes output/, out/, and .spago/ directories.

Architecture

PureScript + Minimal FFI

The extension is written primarily in PureScript with FFI only where necessary:

FFI Used For:

• VS Code API (VSCode.js) - No PureScript library available
• SSH2 client (SSH2.js) - No PureScript library available

Native PureScript Libraries:

• purescript-node-child-process - Process execution
• purescript-node-path - Path manipulation
• purescript-node-fs - File system operations
• purescript-node-buffer - Buffer handling
• purescript-aff - Asynchronous effects

Build Pipeline

src/*.purs → spago build → output/*.js → esbuild → out/extension.js
     ↓                                        ↑
src/*.js (FFI) ──────────────────────────────┘

The bundle.js script:

1. Bundles ES modules to CommonJS
2. Marks vscode, ssh2, cpu-features as external
3. Wraps exports for VS Code extension API

License

BSD-3-Clause

Author

Developed for POLSL (Politechnika Śląska) - ARM Assembly course project.