Add support for Fujisan emulator

CHANGELOG.md

@@ -28,3 +28,9 @@
 * Bug Fix: Fix issue where Atari800MacX would not start if multiple copies on disk
 * Tighter Atari800MacX debug integration - start/stop stays in sync
 
+## 0.9.0 - 2025-02-01
+* Feature: Fujisan emulator support via TCP (emulatorType: "fujisan")
+* Hybrid approach: TCP for XEX deployment, H4: file protocol for debug
+* Add emulatorType, fujisanHost, fujisanPort to launch config
+* Fujisan must be running with TCP server enabled; H4: must map to project bin folder
+

package.json

@@ -1,7 +1,7 @@
 {
   "name": "fastbasic-debugger",
   "displayName": "FastBasic Debugger",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "publisher": "ericcarr",
   "description": "Runs FastBasic on an Atari emulator, providing debugging support to set breakpoints, step through code, view and change variables. Downloads FastBasic and Atari Emulator automatically on Windows and Mac",
   "author": "Eric Carr",
@@ -73,6 +73,22 @@
     "request": "never"
   },
   "contributes": {
+    "configuration": {
+      "title": "FastBasic Debug",
+      "properties": {
+        "fastbasic.defaultEmulator": {
+          "type": "string",
+          "enum": ["atari800", "fujisan"],
+          "default": "atari800",
+          "description": "Emulator to use when you run or debug from the editor without a launch config, or when a launch config doesn't set emulatorType. 'atari800' = Atari800MacX or Altirra; 'fujisan' = Fujisan over TCP."
+        },
+        "fastbasic.defaultLaunchConfiguration": {
+          "type": "string",
+          "default": "",
+          "description": "Launch configuration name to use for 'Debug File' and 'Run File' (e.g. 'Debug FastBASIC (Fujisan)'). If set, the editor buttons use this config from launch.json; otherwise they use an inline config with the default emulator. Works on Windows, macOS, and Linux."
+        }
+      }
+    },
     "themes": [
       {
         "label": "FastBasic Atari",
@@ -170,8 +186,7 @@
           "launch": {
             "required": [
               "sourceFile",
-              "compilerPath",
-              "emulatorPath"
+              "compilerPath"
             ],
             "properties": {
               "sourceFile": {
@@ -189,15 +204,47 @@
                 "description": "Full path to the FastBasic compiler.",
                 "default": "E.G. c:/fastbasic/fastbasic.exe"
               },
+              "emulatorType": {
+                "type": "string",
+                "enum": ["atari800", "fujisan"],
+                "description": "Which emulator to use. Use 'atari800' to launch Atari800MacX or Altirra. Use 'fujisan' to connect to an already-running Fujisan instance via its TCP server.",
+                "default": "atari800"
+              },
               "emulatorPath": {
                 "type": "string",
-                "description": "Full path to the Atari Emulator.",
+                "description": "Path to the emulator executable. Only used when emulatorType is 'atari800'. Ignored for Fujisan.",
                 "default": "E.G. C:/atari/Altirra/Altirra64.exe"
               },
               "windowsPaths": {
                 "type": "boolean",
                 "default": true,
                 "description": "Set to true to force calling emulatorPath with Windows path style (for running Altirra using Wine)"
+              },
+              "fujisanHost": {
+                "type": "string",
+                "description": "Host where Fujisan's TCP server is running. Only used when emulatorType is 'fujisan'.",
+                "default": "localhost"
+              },
+              "fujisanPort": {
+                "type": "number",
+                "description": "Port for Fujisan's TCP server. Only used when emulatorType is 'fujisan'.",
+                "default": 6502
+              },
+              "autoConfigureH4": {
+                "type": "boolean",
+                "description": "When using Fujisan, set H4: to your project's bin folder over TCP so the debugger can talk to the program. Set to false if you map H4: yourself.",
+                "default": true
+              },
+              "fujisanBootMode": {
+                "type": "string",
+                "enum": ["none", "warm", "cold"],
+                "enumDescriptions": [
+                  "No explicit boot — BINLOAD handles the internal reset when loading the XEX. FujiNet stays running. Recommended when using FujiNet.",
+                  "Warm boot before loading XEX. Resets Atari state without restarting FujiNet. Use for extra state cleanup with FujiNet.",
+                  "Stop FujiNet-PC, restart it fresh, then load XEX. Use when you need a clean FujiNet state so network apps work correctly after load."
+                ],
+                "description": "Boot mode for XEX load on Fujisan. 'none' (default): just load XEX, FujiNet stays up. 'warm': warm boot then load XEX. 'cold': stop FujiNet → start FujiNet → load XEX.",
+                "default": "none"
               }
             }
           }
@@ -209,8 +256,19 @@
             "name": "Debug FastBASIC",
             "sourceFile": "${file}",
             "compilerPath": "E.G. c:/fastbasic/fastbasic.exe",
+            "emulatorType": "atari800",
             "emulatorPath": "E.G. C:/atari/Altirra/Altirra64.exe",
             "windowsPaths": true
+          },
+          {
+            "type": "fastbasic",
+            "request": "launch",
+            "name": "Debug FastBASIC (Fujisan)",
+            "sourceFile": "${file}",
+            "compilerPath": "E.G. c:/fastbasic/fastbasic.exe",
+            "emulatorType": "fujisan",
+            "fujisanHost": "localhost",
+            "fujisanPort": 6502
           }
         ],
         "configurationSnippets": [
@@ -223,9 +281,24 @@
               "name": "Debug FastBASIC",
               "sourceFile": "${file}",
               "compilerPath": "E.G. c:/fastbasic/fastbasic.exe",
+              "emulatorType": "atari800",
               "emulatorPath": "E.G. C:/atari/Altirra/Altirra64.exe",
               "windowsPaths": true
             }
+          },
+          {
+            "label": "FastBasic Debug: Fujisan",
+            "description": "Debug with Fujisan over TCP. H4: is set to your project's bin folder automatically. Start Fujisan and turn on Tools → TCP Server first.",
+            "body": {
+              "type": "fastbasic",
+              "request": "launch",
+              "name": "Debug FastBASIC (Fujisan)",
+              "sourceFile": "${file}",
+              "compilerPath": "E.G. c:/fastbasic/fastbasic.exe",
+              "emulatorType": "fujisan",
+              "fujisanHost": "localhost",
+              "fujisanPort": 6502
+            }
           }
         ],
         "variables": {

readme.md

@@ -1,18 +1,19 @@
 # FastBasic Debugger
 
-This a work-in-progress extension with the goal to provide a first class debugging experience for FastBasic in Visual Studio Code on Windows or Mac.
+This a work-in-progress extension with the goal to provide a first class debugging experience for FastBasic in Visual Studio Code on **Windows**, **macOS**, and **Linux**.
 
-Press F5 to debug a file, or Ctrl+F5 to run it without debugging.
+**To debug:** Press F5, or use the **Debug File** button above the editor.  
+**To run without debugging:** Press Ctrl+F5 (Cmd+F5 on Mac), or use the **Run File** button.
 
-On first debug, the extension will prompt to download the FastBasic compiler and a platform specific Atari emulator. It will then configure that emulator to work for debugging. You can tweak the emulator settings (NTSC vs PAL, Enable Joystick, etc) while it is running.
+On first debug, the extension will prompt to download the FastBasic compiler and a platform-specific Atari emulator (Altirra on Windows, Atari800MacX on macOS). It will then configure that emulator to work for debugging. You can tweak the emulator settings (NTSC vs PAL, Enable Joystick, etc) while it is running.
 
-**Advanced use:** You can create a custom launch.json to start a customer emulator (e.g. Altirra on Mac for FujiNet development). More setup steps are needed. See below if desired.
+**Advanced use:** You can create a custom `launch.json` to use a different emulator (e.g. Altirra via Wine on Mac, or Fujisan on any platform). See below.
 
  **If you encounter ISSUES,**  please let me know at: https://forums.atariage.com/topic/351055-fastbasic-debugger-extension-for-vscode/
 
 ## Features
 
-* Automatically downloads the latest supported FastBasic and Atari Emulator (Altirra or AtariMacX) on Windows or Mac
+* Automatically downloads the latest supported FastBasic and Atari emulator (Altirra on Windows, Atari800MacX on macOS) - If you are using Fujisan you have to download and install it manually.
 * Compiles and run or debug in emulator with a single key press
 * Inspect and change variables while debugging
 * See variable value in decimal/hex along with address on hover
@@ -25,18 +26,20 @@ On first debug, the extension will prompt to download the FastBasic compiler and
 
 ## Running or Debugging
 
-To **debug**, press F5.
-To **run** without any debugging code, press Ctrl-F5.
+You can start a session in two ways:
 
-This extension will compile the source code to an XEX and run it in the emulator. If compiling fails, that message will be displayed in the Output pane. 
+1. **Run view:** Open the Run and Debug view (Ctrl+Shift+D / Cmd+Shift+D), choose a launch configuration (e.g. **Debug FastBASIC (Fujisan)** or **Debug FastBASIC (Atari800MacX)**), then press **F5** to debug or **Ctrl+F5** / **Cmd+F5** to run without debugging.
+2. **Editor buttons:** With a `.bas` file active, use the **Debug File** or **Run File** button above the editor. These use your **default launch configuration** (if set in settings) or the **default emulator** (see Settings below).
 
-When debugging with F5, a "GET" statement will be added to the last line so the program waits for a final key press before exiting. When running via Ctrl+F5, this line is not added.
+This extension will compile the source code to an XEX and run it in the emulator. If compiling fails, that message will be displayed in the Output pane.
+
+When debugging, a "GET" statement will be added to the last line so the program waits for a final key press before exiting. When running without debugging, this line is not added.
 
 ## Variables
 
 Variables will show while debugging is stopped on a line and can be viewed multiple ways:
 1. In the Variables pane
-2. By hovering over the varible name in source code. In this view, the value is shown in both decimal and hex, along with the address of where the variable exists in memory
+2. By hovering over the variable name in source code. In this view, the value is shown in both decimal and hex, along with the address of where the variable exists in memory
 3. By right clicking on a variable in source and adding it to the watch pane.
 
 All variable types are supported:
@@ -59,16 +62,17 @@ All variable types are supported:
 
 This is currently a work in progress, but I am working on a theme that gives an experience very close to writing original Atari BASIC, including font, with some color syntax highlighting as a bonus.
 
-## Custom Emulator
+## Custom Emulator (Atari800MacX / Altirra)
 
-You can specify a custom emulator path. This is useful to run Altirra using Wine on non Windows machine, for a FujiNet PC setup. You control this by creating a `launch.json` file in a special folder ( `.vscode` ) under the main project folder.
+On **Windows**, the default emulator is **Altirra**. On **macOS**, it is **Atari800MacX**. You can specify a custom emulator path in `launch.json` (e.g. to run Altirra via Wine on Mac for FujiNet development, or even better, use Fujisan with built-in Fujinet support on macOS and Linux).
 
-You can also generate it by going to the vscode debug view and clicking **Create a launch json file**.
+Create a `launch.json` in the `.vscode` folder under your project, or use the Run view and click **Create a launch.json file**.
 
-#### Two important notes!!
-1. The `emulatorPath` contains the path to wine/altirrra, and `windowsPaths` is set to true so the extension passes a windows like path to altirra
-2. When starting an emulator manually, you need to map H4: to the bin folder under the main project folder. This means, in Altirra, go to System->Configure System->Peripherals>Devices, click Add, choose `Host Device (H:)`, set `H4 / H9` to the path, e.g. `Z:\Users\eric\Documents\projects\my-project\bin\` 
-3. You may need to end the emulator to complete a debugging run. This is a bit tedius, sorry.
+**Notes:**
+1. **compilerPath** can be the path to the FastBasic **folder** (e.g. `C:\atari\fastbasic-4.7HF` or `/path/to/fastbasic-4.7HF`); the extension will use the `fastbasic` (or `fastbasic.exe`) executable inside it.
+2. For a custom emulator, set **emulatorPath** to the executable (or e.g. `wine /path/to/Altirra64.exe` on Mac). Set **windowsPaths** to `true` when passing Windows-style paths to Altirra (e.g. under Wine).
+3. When starting an emulator manually, map **H4:** to your project’s **bin** folder (e.g. in Altirra: System → Configure System → Peripherals → Devices → Add → Host Device (H:) → set H4 to the `bin` path).
+4. You may need to close the emulator to end a debugging run.
 
 For reference, here is a sample file that loads Altirra using wine.
 ```
@@ -89,14 +93,51 @@ For reference, here is a sample file that loads Altirra using wine.
 }
 ```
 
+## Fujisan Emulator
+
+The extension supports **Fujisan** (libatari800-based emulator) on macOS, Windows, and Linux via its TCP Server API. You must use Fujisan 1.1.4 or newer. The latest version is always available here: https://github.com/pedgarcia/fujisan/releases
+
+**Setup:** Fujisan must be running with the TCP server enabled (Tools → TCP Server). The extension configures **H4:** to your project’s `bin` folder automatically over TCP, so you do not need to map H4: manually in Fujisan.
+
+Add a launch configuration in `.vscode/launch.json`:
+```json
+{
+  "type": "fastbasic",
+  "request": "launch",
+  "name": "Debug FastBASIC (Fujisan)",
+  "sourceFile": "${file}",
+  "compilerPath": "/path/to/fastbasic",
+  "emulatorType": "fujisan",
+  "fujisanHost": "localhost",
+  "fujisanPort": 6502,
+  "bootMode": "warm",
+}
+```
+
+You can set **compilerPath** to the folder that contains the FastBasic binary (e.g. `/path/to/fastbasic-4.7HF`); the extension will use the executable inside it. Set **autoConfigureH4** to `false` in the config if you prefer to map H4: manually in Fujisan.
+
+**bootMode** in particular controls how the machine is reset before loading the XEX:
+- `none` (default): no explicit boot before `media.load_xex`.
+- `warm`: warm boot before loading.
+- `cold`: perform a FujiNet restart sequence before loading.
+
+Benefits: deploy and load XEX via TCP; H4: auto-configured for the current project; same step-by-step debugging as with other emulators.
+
+## Settings
+
+In **Settings** (search for **FastBasic**), you can set:
+
+* **Default Emulator** — `atari800` or `fujisan`. Used when you use **Debug File** / **Run File** without a default launch config, or when a launch config does not specify `emulatorType`. On Windows, `atari800` uses Altirra; on macOS, it uses Atari800MacX.
+
+* **Default Launch Configuration** — The name of a launch configuration from `launch.json` (e.g. `Debug FastBASIC (Fujisan)`). When set, **Debug File** and **Run File** use this configuration instead of building an inline config. Ensures the editor buttons use the same emulator and options as the Run view.
 
 ## Current Limitations
 
 This is a work in progress, with the following limitations:
 
 * The program opens files on #4 and #5 to communicate with the debugger, so your program must use different channels (e.g. #1, #2) for I/O. I chose #4 and #5 because these are not typically used.  
 * You can only set/remove breakpoints when the program is stopped for debugging, or not running. This is to keep the program execution speed fast.
-* If your program has a lot of variables (or arrays with many entries), tthere will be a noticable pause when stepping through (F10) line by line.  This is because all variable memory is sent to the debugger after each line.
+* If your program has a lot of variables (or arrays with many entries), there will be a noticeable pause when stepping through (F10) line by line.  This is because all variable memory is sent to the debugger after each line.
 * These limitations may be solved in the future if needed, using a different approach from the H4: host drive for communication.
 
 ## FAQ / Troubleshooting

sampleWorkspace/.vscode/launch.json

@@ -1,17 +1,36 @@
-/*{
-  // Example launch.json that starts Altirra using wine (for Mac users who don't want to use Atari800MacX)
+{
   "version": "0.2.0",
   "configurations": [
-
     {
       "type": "fastbasic",
       "request": "launch",
-      "name": "Debug FastBASIC",
+      "name": "Debug FastBASIC (Fujisan)",
+      "fujisanBootMode": "cold",
+      "sourceFile": "${file}",
+      "compilerPath": "/Users/pgarcia/atari/fastbasic-4.7HF",
+      "emulatorType": "fujisan",
+      "fujisanHost": "localhost",
+      "fujisanPort": 6502,
+      "bootMode": "warm",
+    },
+    {
+      "type": "fastbasic",
+      "request": "launch",
+      "name": "Debug FastBASIC (Atari800MacX)",
+      "sourceFile": "${file}",
+      "compilerPath": "/Users/pgarcia/atari/fastbasic-4.7HF",
+      "emulatorType": "atari800",
+      "emulatorPath": ""
+    },
+    {
+      "type": "fastbasic",
+      "request": "launch",
+      "name": "Debug FastBASIC (Altirra via Wine)",
       "sourceFile": "${file}",
       "compilerPath": "",
-      "emulatorPath": "wine /Users/eric/Documents/Altirra/Altirra64.exe",
+      "emulatorType": "atari800",
+      "emulatorPath": "wine /Applications/Emulators/Altirra/Altirra64.exe",
       "windowsPaths": true
     }
   ]
 }
- */