search

simondotm / beeb-vsc

Visual Studio Code Extension to support code development for BBC Micro
https://marketplace.visualstudio.com/items?itemName=simondotm.beeb-vsc
MIT License
13 stars 3 forks source link

readme

Beeb VSC

A Visual Studio Code Extension to support code development for the Acorn BBC Micro/Master range of 6502 based micro computers from the 1980's.

Visual Studio Code is free and really good for general retro/6502 development, so this extension was created to enhance the experience by providing syntax colouring for 6502 opcodes, labels, and BBC BASIC commands & functions supported by BeebAsm as well as various types of VS Code functionality.

See the CHANGELOG for full release history.

Features

Syntax Highlighting:

Hover Information:

References:

The various types of reference navigation options available within VS Code via the context menu (right-click on a symbol or label).

Diagnostics:

The extension parses your code to try and identify the errors that would be reported by BeebAsm when compiling your code. Lines with issues will be underlined and reported in the Problems tab of VS Code. Dozens of issues are detected including:

Completions:

Provides a list of potential matches as you start to type.

Supported Filetypes:

Build tools

Integrated BBC Micro Emulator

Screenshot

Quick Setup

1. Install the extension

Press CTRL+Shift+X in VS Code, search for 'beeb vsc' or 'beebasm', click install.

2. Install Assembler and Emulator

By default, BeebVSC configures BeebAsm.exe as the default assembler, and BeebEm.exe as the default emulator, and assumes that these executables are can be located on the system path. If not, simply add paths to them in your global Windows environment variables.

3. Load your project

Open your project folder in VSC. Syntax colouring will automatically activate when .6502, .asm, or .s files are opened in the editor.

Screenshot

4. Create a new build target

Press F10 and the extension will provide a drop down list of compatible source files it has found in the current workspace.

Screenshot

Select the one that you wish to assemble with BeebAsm, and a new build target will be created in your workspace.

Screenshot

A tasks.json file will be created in a .vscode folder in your workspace containing the required tasks to build or run your targets. A settings.json file will also be created in the same location and is used for identifying the target source file(s) so we can parse the files in a suitable order even when viewing a different source file.

Screenshot

5. Build the target

Press F7 or Ctrl+Shift+B and Visual Studio Code will build(assemble) the source file you selected and output a disk image <sourcefile>.ssd.

Any errors output by the assembler will be captured in Visual Studio Code's Problems view.

6. Run the target

Press F9 or Ctrl+Shift+T and Visual Studio Code will run your disk image with the currently configured emulator (BeebEm by default).

Alternatively, right-click on your disk image and select BeebVSC: Open Emulator to open with the built-in copy of JSBeeb.

7. Debug (experimental)

Step 1 - Create source map

With your assembly file in focus, open the command palette and select BeebVSC: Create source map. If your file is called build.asm, it will create build.asm.map with information about labels, symbols, and the addresses at which instructions are run.

Step 2 - Run debugger

Right-click your disk image and select BeebVSC: Debug to open the JSBeeb emulator in debug mode. You can now set breakpoints in your code, add watch points and step through the code. See below debugging section for more details.

That's it! Have fun!

Advanced Usage

Changing Assembler and/or Emulator configuration

If you wish to change your Assembler or Emulator configuration, go to File->Preferences->User Settings in Visual Studio Code, the editor will present current user preferences. Scroll to the bottom of the configuration until you see the BeebVSC settings. Copy the settings "beebvsc.assembler" and "beebvsc.emulator" across to your user settings and modify accordingly. Note that although full paths to executables can be included here, we do not recommend this since they are not portable if your project source is shared.

Screenshot

Managing multiple build targets

You can run the add build target command multiple times to add additional source files to the list of build targets in the tasks.json file.

Switching between build targets

It is possible to switch between build targets as follows:

Press F6 and the extension will provide a drop down list of build targets currently in the tasks.json file.

Screenshot

The selection you make will become the new default 'build' and 'test' target, which can then be built as normal by pressing F7 or Ctrl+Shift+B, or similarly, pressing F9 or Ctrl+Shift+T to run in the emulator.

NOTE: It is not possible to add duplicate targets, also note that only one target can be built at once.

Listing commands

Press Ctrl+Shift+P to open the command palette. In here you will see the BeebVSC commands listed for reference/convenience.

Screenshot

Running specific tasks

BeebVSC takes advantage of standard Visual Studio Code 'tasks', which are just a list of named shell commands stored in the .vscode/tasks.json file. Each task is 'runnable' in its own right, so another useful shortcut is Ctrl+Shift+R to list all of the current tasks, which you can then manually select.

Screenshot

Adding custom tasks

The BeebVSC extension is careful to preserve the contents of the tasks.json file. Therefore once targets(tasks) have been added, is very easy to manually configure or override them by simply making modifications to the tasks.json file directly:

The only property that is managed by the extension is Group -> Kind, so this is subject to modification. Note also that the commandline argument for the test task is managed by the extension, and updates whenever a new build target is selected.

Directly managing target source files

If you don't want to use BeebVSC's functionality to add build targets, some functionality will be limited because the extension will not know what order INCLUDE files are processed. In this case, it is necessary to add the target file(s) to the settings.json file. For example, if the targets build.asm and loader.asm are run through BeebAsm then the settings file would look like: 

{
    "beebvsc": {
        "sourceFile": [
            "/Users/Games/Test/build.asm",
            "/Users/Games/Test/loader.asm"
        ],
        "targetName": "main.ssd"
    }
}

The easiest way to set this up is adding the build targets in a normal way and they removing the tasks.json entries if those are not wanted.

Debugging

Debugging is enabled through a two-stage process. Whenever the code is changed, a new source map must be generated through the BeebVSC: Create source map command. This uses the built-in logic from BeebAsm to create a map from each opcode in your code to the address at which it will be run. Eventually it would be better to have this file generated by BeebAsm itself but while the feature is experimental, this gives us more control.

Then the built-in copy of JSBeeb needs to be launched in debug mode. This can be done in two ways. 1) Just right-click on the disk image and select BeebVSC: Debug 2) Set up a launch.json file so that you can just press F5 to start debugging with a specific disk image and named source map file(s). A template for this is included, so you can go to the Run and Debug panel in VS Code and click create a launch.json file to get an initial template, then update the diskImage and sourceMapFiles fields.

Example launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "jsbeebdebugger",
            "request": "launch",
            "name": "Debug in built-in jsbeeb emulator",
            "diskImage": "${workspaceFolder}/mygame.ssd",
            "sourceMapFiles": [
                "build.asm.map"
            ]
        }
    ]
}

Watches can be set for symbols and labels from your code (assuming they relate to 16 bit addresses).

Examples:

Watch panel

Linux/Mac support

The installation is for Windows by default, but its quite feasible to get it working for Linux and MacOS. Primarily this is done by changing the settings for "beebvsc.assembler" and "beebvsc.emulator".

Possible further features to add

Contributors & Kudos

Many thanks to the following people who have contributed directly & indirectly to this project:

More information here about developing the extension.

Acorn Community

Development tools

Emulators

BBC Micro/6502 Resources: