grahambates / uae-dap

Debug Adapter Protocol for Amiga development with FS-UAE or WinUAE

UAE Debug Adapter Protocol

Stand-aloneDebug Adapter for Amiga assembly development with FS-UAE or WinUAE.

This package was extracted from the vscode-amiga-assembly extension, to create stand-alone adapter for use with other editors that support Debug Adapter Protocol.

This library relies on patched binaries for FS-UAE and WinUAE with changes from @prb28 and @bartman to provide a remote GDB server. These are now bundled with the package for Windows, Mac and Debian Linux x64. Note that the FS-UAE implementation is now based on the current 4.x dev build, and as such has some limitations and missing features. It is totally usable though and is much closer to current WinUAE, allowing us to share common patches rather than maintaining two separate GDB implementations.

Tested with:

• NeoVim nvim-dap plugin. See example below.
• Emacs dap-mode. See emacs-m68k (currently using 0.x version).

Installation

Install the uae-dap npm package globally: npm i -g uae-dap

Usage

The Amiga binaries to be debugged must include SAS/C-compatible LINE DEBUG hunks. Use the -linedebug option is vasm and -hunkdebug in vbcc to include these.

Example configuration:

Here's a minimal example configuration for NeoVim with the Amiga Assembly example workspace.

dap.adapters.asm68k = {
  type = 'executable',
  command = 'uae-dap',
  options = { initialize_timeout_sec = 20 },
}

dap.configurations.asm68k = {
  {
    type = 'asm68k',
    request = 'launch',
    program = '${workspaceFolder}/uae/dh0/gencop',
    stopOnEntry = true,
    emulatorType = "fs-uae",
    emulatorArgs = {
      "--chip_memory=2048",
      "--amiga_model=A1200",
      "--automatic_input_grab=0",
      "--floppy_drive_0_sounds=off",
      "--hide_hud=1",
      "--window_resizable=1"
    }
  }
}

Configuration options:

Option	Type	Description	Default
program	string	Local path of target Amiga binary	-
remoteProgram	string	Remote path of target Amiga binary	"SYS:{basename(program)}"
stopOnEntry	boolean	Automatically stop target after launch	false
noDebug	boolean	Just launch emulator without debugging	false
trace	boolean	Enable verbose logging	false
serverName	string	Host name of the debug server	"localhost"
serverPort	number	Port number of the debug server	2345
exceptionMask	number	Mask used to catch the exceptions	0b1111111111100
emulatorType	"fs-uae" | "winuae"	Emulator program type	"winuae" on windows, "fs-uae" on other platforms
emulatorBin	string	Path of emulator executable	bundled version
emulatorArgs	string[]	Additional CLI args to pass to emulator program. Remote debugger args are added automatically	[]

Changes

1.0

• Changed configuration schema
• No longer supports the patched fs-uae 3.x implementation.

uae-dap's Issues

Adapter fails to launch on macOS due to incorrect dynamic library paths

Trying to launch the uae-dap adapter when installed globally via NPM on macOS is causing a dynamic loader error, at least on my system:

dyld[10852]: Library not loaded: @loader_path/../../../../opt/freetype/lib/libfreetype.6.dylib
  Referenced from: <07B03B30-1437-3451-BA21-71A9F664B841> /opt/homebrew/lib/node_modules/uae-dap/bin/fs-uae/lib/libharfbuzz.0.dylib
  Reason: tried: '/opt/homebrew/lib/node_modules/uae-dap/bin/fs-uae/lib/../../../../opt/freetype/lib/libfreetype.6.dylib' (no such file), '/usr/local/lib/libfreetype.6.dylib' (no such file), '/usr/lib/libfreetype.6.dylib' (no such file, not in dyld cache)

This appears to be because the libfreetype.6.dylib library and its siblings are one level deeper than the specified path relative to @loader_path.

I did a quick regression test of versions, and it appears this was introduced at v1.0.3 of uae-dap, as installing v1.0.2 fixes it and the adapter launches properly.

If I can provide any additional information, or might've missed something obvious, let me know!

DAP hangs/fails to connect if previous debug session was ended by quitting FS-UAE

I'm on macOS using Neovim. To explain the issue, let me list a working and non-working scenario.

Working scenario:

1. Start a debug session. Node and FS-UAE start up.
2. End the session from the debugger by sending terminate(). FS-UAE and Node both quit.
3. Start a new debug session. Node and FS-UAE start up and work as expected.

Another working scenario:

1. Start a debug session. Node and FS-UAE start up.
2. Force quit Node, and then quit FS-UAE normally.
3. Start a new debug session. Node and FS-UAE start up and work as expected.

Non-working scenario:

1. Start a debug session. Node and FS-UAE start up.
2. End the session by quitting FS-UAE. FS-UAE and Node both quit.
3. (Optional) Restart Neovim to ensure nothing stale is going on with the debugger.
4. Start a new debug session. FS-UAE and Node start up, but FS-UAE hangs. A force quit is required on both FS-UAE and Node.
5. After force quitting Node and FS-UAE, start another debug session. Node and FS-UAE start up and work as expected.

Basically, if the debug session is ended by quitting FS-UAE, then the next session is guaranteed to fail. It's very strange because I confirmed that the Node process also ends when quitting FS-UAE. Is there a difference between how the DAP handles FS-UAE quitting versus terminate() from the debugger?