ATasm Altirra Bridge - write 6502 code, assemble, run and debug all in one
This extension lets you code your Atari 8 bit assembler projects using a modern tool chain.
Write in VSCode and use the status bar icons or keyboard shortcuts to assemble, run and debug your project. Set breakpoints and debug with ease. Use the symbol explorer to quickly navigate to parts of your code (currently only available with ATasm)
This extension includes the following features:
- 6502 assembler syntax highlighting
- Cross-platform macro assembler (ATasm).
- Run your code in the Altirra emulator (or setup another one)
- Source level debugging with breakpoints
- Constant/Label/Macro explorer to quickly navigate to parts of your code
- Optional settings to use mads (https://mads.atari8.info/mads_eng.html) as your assembler
Use the icon to switch to the
Asm Symbol Explorer.
This tool shows data exported by the
ATasm assembler. Use the
-hv switch in the
params section to generate the data, or use the
Export For Symbol Explorer setting.
"_4": "Additional atasm parameters:",
or use the settings as shown in this image.
The demo file below will produce the data shown in the image below:
* = $2000
TEST_ME = 88 ; Setup test variable
BOOT ; We will boot from here
loop JMP loop ; Wait for ever
TheEnd .byte 0 ; The END indicator
The first item shows that the
TEST_ME constant has a value of 88 (in hex $58) and what the comment for the definition is. Clicking on the
TEST_ME symbol will take you to the line where the symbol is defined in the source file.
The second section show labels sorted by address/memory location:
ORIGINAL_GRAPHICS was set to 0 on the command line, in this case in the
symbols section of the
THEEND symbols where defined in the assembler source code. The location in memory together with source comment is shown. If you hover the cursor over the symbol the origin in the source file is shown. In this case
LOOP is at address $2005 and it's source comment is
Wait for ever.
Build tasks and shortcuts for building you assembler projects
The extension registers build tasks for 6502 assembly files which invoke
ATasm on the file
currently beind edited (Ctrl + Shift + B).
If you have a
atasm-build.json configuration file in your workspace folder then a task will be created for the defined project.
The build tasks allow you to quickly assemble your code. By default output goes to the
out folder with a
For a full integration with the
Altirra emulator you need to create the
atasm-build.json configuration file. This allows you to optionally specify the name of the input file which is passed to the assembler as well as any additional parameters.
There is no need to create this file by hand. You can use the status bar shortcut buttons:
or the command pallette (Ctrl+Shift+P then type atasm)
to create the file.
Pressing the gear icon will create and open the configuration file.
input - the first file in your project. This will
.include all others.
theapp.asm by default. Change this to the name of your game or application.
includes - a list of folders that will be searched for files when they are included.
outputFolder - the location relative to your workspace where the assembler output will be written to. This is
out by default.
params - The extra ATasm parameters you want to specify. i.e. -v for verbose output
symbols - An array of predefined symbol definitions. i.e ["VERSION=1","TEST=0"]
withDebug - Boolean value of
true will create a symbol and listing file that will help with Altirra debugging.
The VSCode status bar allows for quick access to the
Build (Shift + F5),
Build and Run (F5), and
Build and Debug (Ctrl + F5) commands.
The build button will run ATasm with the configured parameters. Output and status messages go to the
Build and Run
The first time the build and run button is pressed the extension will verify if
Altirra (or another emulator) has been setup and its location on the machine configured. It its not configured then the following screen will be shown. Enter the location of your Altirra emulator location including the executable filename. i.e. D:\Altirra\3.90\Altirra64.exe or /usr/bin/altirra/wine-altirra
Once a reference to Altirra has been added you can run your project code directly from VSCode.
If your system does not allow you to run Altirra or you want to use another emulator you can confiure the path and command line for it.
You need to supply all the arguments in the correct format, the extension would not know how to format the arguments. .i.e. Would an arguement start the --, -, or /.
Build and Debug
The real power of the extension comes in the form of the Altirra debugger. Pressing the build and debug button will not only create the binary file, but also a file containing the
symbol definitions and a
list file. The list file maps every line number of the project to a memory location. This allows us to do source level debugging and to set break points in the assembler code and have Altirra hit them when the program is executed.
Here is what source level debugging with a hit breakpoint looks like in Altirra
Installing and configuring
ATasm and Altirra
A version of the ATasm macro assembler ships with this extension. The Linux x64 and Windows x64 binaries are included.
Altirra can be downloaded from here. A description on how to configure it can be found in the Retro Coding Blog.
Mads as an alternative assembler
If you prefer using the every popular MAD-ASSEMBLER (mads) (https://mads.atari8.info/mads_eng.html) then you can setup a the path to it, switch the plugin settings to
Mads and do nearly all the things you can do with
ATasm. The switch is located under
Which Assembler in the settings.
The only plugin feature not available to
Mads users is the
Updating the extension
Updates are regularly provided and you will be notified via VS Code when one has been made available. Once an update has been installed you will generally be prompted to restart VS Code.
; A simple test app to put some color on the screen
COLPF2 = $d018
COLBK = $D01A
WSYNC = $d40a
VCOUNT = $d40b
RTCLOK = $14
* = $2000
The Altirra emulator needs to be installed to run and debug your code.
Should you want to use
Mads as your assembler then you will need to setup the path to it.
There are various settings that control aspects of this extension. To access them open the settings (Ctrl+,) and select
Atasm Altirra Bridge from the extensions.
This extension contributes the following settings:
Mads. Select which assembler is being used by the plugin. Defaults to
atasm-altirra-bridge.assembler.atasmPath: If you wish to use your own version of ATasm (and not the one shipped with the extension) then set the path to it here
atasm-altirra-bridge.assembler.madsPath: If you wish to use
Mads as your assembler then set the path to it here and switch the
Which Assembler setting to
atasm-altirra-bridge.assembler.atasm.outline.ExportForSymbolExplorer: Whether to tell ATasm to export symbols (equates, labels, macros) for the
Symbols Explorer. Sets the -hvclm flag and generates the
atasm-altirra-bridge.assembler.atasm.outline.noEquates: Tell ATasm NOT to export equates (abc = 123) for the
Symbols Explorer. Clears 'c' from the -hvclm flag.
atasm-altirra-bridge.assembler.atasm.outline.noLabels: Tell ATasm NOT to export labels (ABC jmp ABC) for the
Symbols Explorer. Clears 'l' from the -hvclm flag.
atasm-altirra-bridge.assembler.atasm.outline.noMacros: Tell ATasm NOT to export macro definitions (.macro NAME) for the
Symbols Explorer. Clears 'm' from the -hvclm flag.
atasm-altirra-bridge.editor.clearPreviousOutput: Whether to clear the previous output window everytime the assembler is triggered.
atasm-altirra-bridge.editor.saveAllFilesBeforeBuild: Whether to save all files before build is triggered.
atasm-altirra-bridge.editor.saveFileBeforeBuild: Whether to save the active file before build is triggered.
atasm-altirra-bridge.editor.showAssemblerOutput: Whether to show the assembler messages in the output window.
atasm-altirra-bridge.editor.statusBarCommands: Show information and feature short-cuts on the Status Bar.
atasm-altirra-bridge.emulator.altirra.path: Specify the full path to the Altirra emulator.
atasm-altirra-bridge.emulator.altirra.args: Specify (optional) Altirra command line arguments.
atasm-altirra-bridge.emulator.altirra.autoCloseRunningAltirra: Automatically close any existing Altirra instances before opening a new one.
atasm-altirra-bridge.emulator.altirra.singleInstance: Only run a single instance of the emulator.
atasm-altirra-bridge.emulator.altirra.region: Run Altirra in PAL or NTSC region
atasm-altirra-bridge.emulator.ownEmulator: Whether to run Altirra or another emulator (own)
atasm-altirra-bridge.emulator.own.args: All arguments passed to the own emulator. The extension does not add any.
atasm-altirra-bridge.emulator.own.path: Full path to your own emulator.
- Atasm version bump to 1.20
- Atasm now exports a "Memory Map" which the extension parses and shows as an "Atasm Assembler memory viewer"
- Gives a nice layout of the used memory
- To name memory sections you can use a string behind the *=<addr> directive like: *=$200 "Booting from here"
- or use the .NAME "Music" directive to tell Atasm that this is a section with Music in it
- Atasm version bump to 1.18
- Atasm can now export comments on the same line where equates (a=123), labels (abc) and macros (.macro) are defined
- Use the
-hv command line option to export the comments with the symbols
- Or use the Export For Symbol Explorer setting (with its three exclusion options)
- The extension tracks changes to the 'asm-symbols.json' file and updates the symbol explorer accordingly.
- You can now configure the extension to only run a single instance of the Altirra emulator
- Atasm version bump to 1.17
- Atasm can now dump constant, label and macro definition information to a file
- use command line switch -hv to dump all the info
- use -hv[clm] c=constant l=labels m=macros to select a subset of info to dump
-hvc only dumps the defined constants
-hvl only dumps information about labels
- The 'asm-symbols.json' file in the root of the project can be viewed in vscode via
Asm Symbol Explorer. Clicking on any of the constants, labels, macros or included
files will take you to the source code instantly.
- Atasm version bump to 1.13
- Atasm can now generate CC65 header and atasm include files from your project
- use -hc switch to generate a CC65 header file
- use -ha switch to generate an atasm include file
- Atasm version bump to 1.12
- MacOS support
- Added a MacOS x64 atasm executable
- Better integration of the ATasm assembler
- Fixed a bug that reset the path to be always the Windows path of the atasm
- Build Task now also works when 'atasm-build.json' is the currently open file
- Added configuration options to allow for another emulator to be used
- Set the ownEmulator setting and supply the path and arguments
- The extension will not add any parameters. You will need to supply them in the correct format.