What

A simple and free development environment for c64 coding using Sublime text, the Kick Assembler compiler and the Vice c64 emulator or the C64Debugger emulator/debugger. It supports macOS, Linux and Windows.

Kick Assembler (C64) is a language package for the awesome Sublime text editor (version 2 and 3 supported).  The package supports things like syntax coloring, basic navigation and build/run/debug integration with Kick Assembler/Vice.

Install

Panic install guide (macOS, Windows, Linux)

1. Ensure Java Runtime Environment is installed
2. Download Kick Assembler and ensure KickAss.jar is in your CLASSPATH environment variable
3. Download Vice c64 emulator and ensure path to x64 is in your PATH environment variable
4. Install  Sublime Text and Package Control
5. Install package Kick Assembler (C64)
6. Code awesome demos!

Detailed installation guides

• Installation guide for macOS
• Installation guide for Linux
• Installation guide for Windows

Develop, build and run

1. Open a Kick Assembler code file in Sublime text. Example code file here.
2. Hit the F7 key to start Build and Run
3. Hopefully watch your lovely code execute!

In step 2 above you can select other Build Variants, by instead selecting Tools -> Build With… in the menu bar and select desired build variant, or by using the associated key (see below). Here follows a description of the available build variants.

Build and Run (F7)

Compiles the current file and runs it using the Vice emulator.

Build and Debug (Shift+F7)

Compiles the current file and runs it using the Vice emulator. This variant allows the creation of a file containing breakpoints, which is sent to the Vice emulator for debugging.

Build and Run Startup (F5)

Compiles a file with name Startup.asm in the same folder as the current file, and runs it using the Vice emulator. Handy if you have several code files included in a main runnable file (Startup.asm).

Build and Debug Startup (Shift+F5)

Compiles a file with name Startup.asm in the same folder as the current file, and runs it using the Vice emulator. Handy if you have several code files included in a main runnable file (Startup.asm). This variant allows the creation of a file containing breakpoints, which is sent to the Vice emulator for debugging.

Build Startup (Super+Shift+B / Ctrl+Shift+B)

Compiles a file with name Startup.asm in the same folder as the current file. Handy if you have several code files included in a main runnable file.

Make (F8)

Invokes a script called make.bat/make.sh (configurable thru the
default_make_path setting). The following (relevant?) environment variables will be available in the make script:

• kickass_file, filename of active file when command was triggered
• kickass_file_path, full path active file when command was triggered
• kickass_prg_file, full path for suggested prg file name, for active file when command was triggered
• kickass_bin_folder, path to current output folder (bin or specified by setting kickass_output_path)

Features and details

Syntax coloring

For most C64/Kick Assembler things syntax coloring is available.

Auto complete

Although no specific auto complete support is supplied for c64/Kick Assembler, the auto complete features built in to Sublime Text will help a whole lot, the names of existing labels, macros and other stuff will pop up as you write. Very handy.

Navigate to…

Press Super+r/Ctrl+r to view a list of the Kick Assembler labels, namespaces, functions, macros and pseudofunctions in the current file.

Build errors

If you get a compile/build error, just press the F4 key to go to the file/line where the error occurred.

Debugging and break points

You can easily create break points and make the Vice emulator enter the monitor once the address of the break point is hit. In the Vice monitor you can then step and such. To enable break points, you need the following code in your file (or in a separate file and using the .include directive):

//----------------------------------------------------------
// Code for creating the breakpoint file sent to Vice.
//----------------------------------------------------------
.var _useBinFolderForBreakpoints = cmdLineVars.get("usebin") == "true"
.var _createDebugFiles = cmdLineVars.get("afo") == "true"
.print "File creation " + [_createDebugFiles
? "enabled (creating breakpoint file)"
: "disabled (no breakpoint file created)"]
.var brkFile
.if(_createDebugFiles) {
.if(_useBinFolderForBreakpoints)
.eval brkFile = createFile("bin/breakpoints.txt")
else
.eval brkFile = createFile("breakpoints.txt")
}
.macro break() {
.if(_createDebugFiles) {
.eval brkFile.writeln("break " + toHexString(*))
}
}
//------------------------------------------------------

You can also insert the script by using a snippet, type brsc in Sublime to insert the script at the cursor location.

Once the above code is available to your code file, you can write :break() on a line of code and press Super+Shift+F7/Ctrl+Shift+F7 to run your code in Vice and make it stop once your breakpoint is hit. To insert a breakpoint you can also use the bp-snippet (see below).

Settings

The following settings can be used in sublime (on any level including users, application and project)

• kickass_run_path, path to executable used for run commands, if not set Vice (x64) is used, either by using the PATH environment variable or in the default location (see install guides here).
• kickass_debug_path, path to executable used for debug commands, if not set Vice (x64) is used, by using the PATH environment variable or in the default location (see install guides here). The main purpose is to allow use of C64Debugger or similar for debugging.
• kickass_jar_path, full path to the Kick Assembler jar-file, if not set the CLASSPATH environment variable, or the default location (see install guides here), is used.
• kickass_main_class_name, name of the main class for Kick Assembler, if not set the default cml.kickass.KickAssembler is used.
• kickass_run_args, additional command line arguments for run commands
• kickass_debug_args, additional command line arguments for debug commands
• kickass_args, additional command line arguments for kick assembler (all commands)
• kickass_startup_file_path, name of the file used for startup commands (Build and run startup and Build and debug startup). Default is Startup.
• kickass_path, string to add to path environment variable during build
• kickass_empty_bin_folder_before_build, true/false to toggle emptying bin-folder before build. Default value is true.
• kickass_breakpoint_filename, filename for breakpoint file to use. Default is breakpoints.txt.
• kickass_output_path, setting output-folder, default is bin​
• kickass_compiled_filename, filename of compiled prg-file, default is SourceFile.prg ​(where SourceFile is the name part of the compiled asm-file)
• default_prebuild_path and default_postbuild_path, default prebuild-/postbuild paths. Prebuild/postbuild-scripts located in the current directory will take precedence, but if not found the default path is also checked. No default value. More info
• default_make_path, default make path. Make-scripts located in the current directory will take precedence, but if not found the default path is also checked. No default value.
• kickass_env, list of environment variables to add during buildi. These variables has precedence over other environment variables with the same names. Mostly useful for prebuild, postbuild and make commands. Example:
  "kickass_env": { "MY_ENV_VAR1" : "Goats can fly", "MY_ENV_VAR2" : "Brown banana" }
• kickass_run_command_x64, kickass_debug_command_x64, kickass_debug_command_c64debugger, kickass_run_command_c64debugger, kickass_compile_args, kickass_compile_debug_additional_args, used for detailed customization of compile, run and debug commands. Defines the patterns for these commands.

Pre and post build actions

The ability to run your custom scripts in your project directory before and after compile.

• If a file called Prebuild.sh/Prebuild.bat exists in the same directory as the file being compiled, it will be called before compiling.
• If a file called Postbuild.sh/Postbuild.bat exists in the same directory as the file being compiled, it will be called after compiling (but before run/debug).
• The following environment variables will be available in the scripts:
  • kickass_buildmode, indicates the current build mode, one of the following:
    • build
    • build-run
    • build-debug
    • build-run-startup
    • build-debug-startup
    • build-startup
  • kickass_file, filename of the file being compiled
  • kickass_file_path: full path to the file being compiled
  • kickass_prg_file, full path to the compiled output prg file
  • kickass_bin_folder, path to folder of the compiled output prg file
• If you set an environment variable in the Prebuild script, it will also be available in the Postbuild script

Build annotations

Build annotations are meta info used by the Kick Assembler (64) sublime package to customize building, starting and debugging.

To add build annotations, simply put // @kickass-build followed by annotations on the first line of your “build startup file”. Which file is the “build startup file” depends on some things, if you use the Build and run command it is always the currently active file, but if you use the Build and run startup command, it is a file named Startup.asm (or another file name configured by the kickass_startup_file_path setting) in the same folder as the currently active file.

file-to-run build annotation

file-to-run build annotation tells the build system which prg-file to start (in Vice, C64Debugger or other configured run/debug tool). This is mostly useful when working with segments.

Using file-to-run will look like this:
// @kickass-build "file-to-run": "filename.prg"
Just replace filename.prg with the name the prg-file you want to start.

See below for a more complete code example. The “file” uses two segments and two corresponding prg-files, the Kick Assembler (64) sublime package will not know which one of them to start. The file-to-run annotation will configure which prg to start.

[code language="javascript"]
// @kickass-build "file-to-run": "StartupSegment.prg"

.segment Startup [outPrg="StartupSegment.prg"]
:BasicUpstart2(startup)
startup:
inc $d020
jmp *-3

.segment Another [outPrg="AnotherSegment.prg"]
:BasicUpstart2(another)
another:
inc $d021
jmp *-3
[/code]

With Vice you can even start files on D64-disks with syntax
// @kickass-build "file-to-run": "diskFilename.d64:prgname" (prg filename should typically be lower case without prg-extension)

startup-file build annotation

startup-file build annotation tells the build system which file to compile whenever startup commands are used (Build and run startup and Build and debug startup), similar to setting kickass_startup_file_path. The build annotation has precedence over setting kickass_startup_file_path.

Using startup-file will look like this:
// @kickass-build "startup-file": "filename.asm"
Just replace filename.asm with the name of the source file you want to compile for startup commands.

Snippets

There is a few “built in” snippets in Kick Assembler C64. A snippet is a template, where the Sublime text editor lets you fill in missing details. You write a sequence of characters (trigger), select the snippet, and start filling in the missing values, pressing tab between each value.
The available snippets so far are (trigger in parenthesis):

• Breakpoint (bp)
• For-loop (for)
• If statement (if)
• if-else statement (ifel)
• Macro (macro)
• C64 subroutine (sub)
• Sinus curve generation (sin)
• Cosinus cure generation (cos)
• Breakpoint script (brsc)

Version history

The full version history can be found here.

More

The Kick Assembler script language

I really recommend learning the Kick Assembler script language by reading the Kick Assembler manual.

Contribute

If you like to contribute there is a GitHub-repository here.

Future

The syntax coloring and language configuration for Sublime Package Kick Assembler (C64) can certainly improve, hopefully i will update periodically.

Follow @SwfNoc on twitter for future updates.

Thanks

The language files were originally downloaded and modified from here.