XC=Basic 3

Syntax highlighting for XC=BASIC 3, a cross compiled BASIC for 8-bit Commodore machines.

Features

• Rich Syntax Highlighting for XC=BASIC3 (including ASM blocks)
• IntelliSense & Code Completion - Auto-completion for keywords, built-in functions, and data types
• Hover Information - Detailed documentation on hover for keywords and functions
• Error Highlighting - Compilation errors are highlighted directly in the editor
• Automatic Toolchain Management - XC=BASIC3 compiler and DASM assembler are downloaded and managed automatically
• Integrated Build System - Compile, run, and debug with keyboard shortcuts
• External Tool Integration - Works with Vice emulator, Retro Debugger, Exomizer, and c1541
• Cross-Platform - Supports Windows, macOS, and Linux

Requirements

No requirements for basic compilation, but these external tools are recommended for a complete development experience:

• Vice Emulator: https://vice-emu.sourceforge.io/
• Retro Debugger: https://github.com/slajerek/RetroDebugger
• Exomizer: https://csdb.dk/release/?id=238365

Installation

1. Install the extension from the VS Code Marketplace
2. Open a folder containing .bas files
3. The extension will automatically download and set up the XC=BASIC3 compiler and DASM assembler

macOS Security Note

On macOS, the first compilation attempt may fail with security warnings:

Fix: Open System Settings > Privacy & Security > General, then click "Open Anyway" next to the warning.

Quick Start

1. Create a new .bas file:

   PRINT "Hello, World!"
   

2. Compile and run:

   • Press Shift+F5 to compile
   • Press Ctrl+F5 (or Cmd+F5 on Mac) to compile and run in emulator

3. View compilation errors:

   • Errors appear as red squiggly lines in the editor
   • Check the Problems panel (View → Problems) for detailed error messages
   • XC-Basic compiles in 2 phases. Second phase is Dasm compilation and errors in 2nd phase cannot be tracked back to the basic code.

Configuration

Extension Settings

Configure these settings in VS Code's settings (File → Preferences → Settings):

Tasks Configuration

The extension automatically creates .vscode/tasks.json with predefined build tasks. You can customize these tasks or create new ones.

Default Tasks

Example Custom Task

Add this to your .vscode/tasks.json to create a custom compilation task:

{
  "label": "XC=BASIC Compile with Custom Args",
  "type": "shell",
  "command": "${env:XCBASIC3_COMPILER}",
  "args": [
    "--dasm=${env:DASM_PATH}",
    "--target=c64",
    "--optimize",
    "${file}",
    "${fileBasenameNoExtension}.prg"
  ],
  "group": "build",
  "problemMatcher": "$xcbasic3"
}

Usage Examples

Basic Compilation

1. Create a simple program (hello.bas):

   PRINT "Hello from XC=BASIC!"
   FOR I = 1 TO 10
       PRINT "Count: "; I
   NEXT I
   

2. Compile: Press Shift+F5 or use Command Palette → "Tasks: Run Task" → "XC=BASIC Compile File"

Using Assembly Blocks

PRINT "Hello from XC=BASIC!"

ASM
loop
    INC $D020    ; Change border color
    JMP loop
END ASM

Error Handling Example

If you have an error in your code:

PRONT "This has a typo!"  ; PRONT should be PRINT

The extension will:

• Show a red squiggly line under the error
• Display the error in the Problems panel
• Show the exact line and column of the error

Working with External Tools

Running in Vice Emulator

1. Configure the emulator path in settings
2. Press Ctrl+F5 to compile and run
3. The program will automatically load in Vice

Debugging with Retro Debugger

1. Configure the debugger path in settings
2. Press F5 to compile and debug
3. The program will load in Retro Debugger with symbols

Creating Disk Images

Use the "XC=BASIC Build Disk" task to create a .d64 disk image:

1. Run the task from Command Palette
2. The compiled program will be added to a new disk image
3. Load the disk in your emulator

Commands

Access these commands via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Advanced Configuration

Using External XC=BASIC Installation

If you prefer to use your own XC=BASIC installation:

1. Set xcbasic3.basefolder to your installation path
2. Update your tasks to use ${config:xcbasic3.basefolder}/bin/xcbasic3 instead of ${env:XCBASIC3_COMPILER}

Custom Compiler Arguments

Add compiler arguments in your task configuration:

{
  "label": "XC=BASIC Compile Optimized",
  "command": "${env:XCBASIC3_COMPILER}",
  "args": [
    "--dasm=${env:DASM_PATH}",
    "--target=c64",
    "--optimize",
    "--verbose",
    "${file}",
    "${fileBasenameNoExtension}.prg"
  ]
}

Troubleshooting

Common Issues

Q: Error highlighting doesn't appear A: Make sure your task uses "problemMatcher": "$xcbasic3" in .vscode/tasks.json.

Q: External tools don't work A: Check that the tool paths in settings are correct and the executables exist.

Q: macOS security warnings A: Go to System Settings > Privacy & Security and click "Open Anyway" for blocked applications.

Getting Help

1. Check the Problems panel (View → Problems) for detailed error messages
2. Look at the Terminal output for compilation details
3. Verify your settings in File → Preferences → Settings
4. Report issues at: https://github.com/orlof/xcb3-vscode-ext/issues

Language Features

Syntax Highlighting

The extension provides rich syntax highlighting for:

• XC=BASIC keywords and built-in functions
• String literals and numeric constants
• Comments (both REM and ' style)
• Assembly blocks with 6502 instruction highlighting
• Type declarations and function definitions

Code Folding

Fold these code blocks:

• SUB / END SUB
• FUNCTION / END FUNCTION
• ASM / END ASM

Auto-Completion

Basic auto-completion for:

• Bracket pairs: (), {}
• String quotes: ""

Notes

This extension provides:

• Rich Language Support: IntelliSense, code completion, and hover information via Language Server Protocol
• Syntax Highlighting: Rich syntax highlighting for XC=BASIC3 and embedded assembly
• Build System Integration: Seamless compilation and execution workflow
• Toolchain Management: Automatic XC=BASIC3 compiler and DASM assembler management
• External Tool Integration: Works with Vice emulator, Retro Debugger, and other Commodore development tools

This extension does NOT provide:

• Debugging Support: No support for VS Code's integrated debugger (stepping, breakpoints, variable inspection)
• Advanced Refactoring: Basic language server features only, no complex refactoring tools

Thanks

• Syntax definitions based on work by:

  • https://github.com/Viza74/xcbasiclanguagevscodeext
  • https://github.com/zeh/vscode-dasm

• This extension downloads and uses:

  • XC=BASIC 3: https://xc-basic.net/
  • DASM Assembler: https://dasm-assembler.github.io/

License

This extension is released under the MIT License. See LICENSE file for details.