Relaunch64 help

This is a small help page with an overview of selected functions. Choose from the index below to jump to a help topic.

You'll find a more detailed manual, including illustrative figures, at the C64-Wiki in German and English.

General

Menu items

Assembler setting

In the bottom status bar of the main window you can select the assembler of the current active source code. It is recommended to do so for two reasons:

  1. Selecting the correct assembler will ensure that the syntax highlighting is applied correctly.
  2. The Goto commands (see Navigate menu) only work proper if the correct assembler is selected.

Comment commands

There are following placeholders that can be used as commented line for additional settings when compiling the source:

User scripts

User scripts will be executed similar to bash or console commands. You can run any assembler and / or emulator in the same way you would do when calling these tools from the console or a batch file.

You can define several actions that should be executed. Use multiple lines in your script to define multiple actions.

Adding new scripts

To add a new script, simply change the script name (in the related text field). Once you changed the script name, the apply-button's text will change to Add script. Edit the script in the text area below and add the script by clicking on the button.

If you press the New Script button, all fields will be cleared and you can enter script name and script lines.

Updating existing scripts

To change or update an existing script, simply select the script from the dropdown list, but do not change the script name (in the related text field). Edit the script in the text area below and save the changes by clicking on the button Update script.

Relaunch64 options

To set a specific behaviour of Relaunch64 when compiling scripts, use a command line starting with R64, followed by one of these switches:

Note: See user script examples below.

Placeholders

To specifiy directories or input and output files, there are following constants that should be used:

Note 1: In some cases you may have to add the "open" command to the command line (e.g., on OS X, starting Vice will throw an access denied error without the open-parameter). See examples below.

Note 2: If you specify full pathes to your assembler or emulator and the path contains whitechars (spaces), you need to set the path in quotes (see examples below). Placeholders like SOURCEFILE or OUTFILE, however, will be automatically quoted if necessary. You don't need to quote the placeholders.

Note 3: To make use of the START placeholder, you have to specify the start address in a comment line with following syntax:
<comment sign> start=<start address>, for instance:
// start=$c000 (for Kick Assembler)
; start=12288 (for other assemblers)

Drag & Drop

You can drag & drop executables from assemblers, crunchers and emulators from the explorer (or file browser) window onto the script text field. Relaunch64 will then automatically generate a proper scriptline, including recommended parameter settings (in case the assembler, cruncher or emulator is recognized and supported).

User scripts examples

Using KickAss and Vice on OS X

java -jar /<path to kickass>/KickAss.jar SOURCEFILE
open /Applications/Vice/x64.app OUTFILE

ACME and Vice, when ACME- and VICE-Path are in PATH-Environment

acme -v4 RSOURCEFILE
x64 ROUTFILE

Using ACME, ignore assembler warnings, don't wait for script

R64 -iw -nowait
C:\Users\<username>\Documents\C64\acme.exe --outfile ROUTFILE --format cbm RSOURCEFILE
C:\Users\<username>\Documents\C64\WinVICE-2.4\x64.exe COMPFILE

ACME and Vice, when ACME-Path is in PATH-Environment (Vice is not)

acme --outfile ROUTFILE --format cbm RSOURCEFILE
"C:\Users\<username>\Documents\C64\WinVICE 2.4\x64.exe" ROUTFILE

64tass on OS X

/usr/local/bin/64tass -C -a -i SOURCEFILE -o OUTFILE
open /Applications/Vice64/x64.app OUTFILE

64tass on OS X, ignore assembler warnings

R64 -iw
/usr/local/bin/64tass -C -a -i SOURCEFILE -o OUTFILE
open /Applications/Vice64/x64.app OUTFILE

Using KickAss and Vice on Windows

java -jar C:\Users\<username>\Documents\C64\KickAss\KickAss.jar RSOURCEFILE
C:\Users\<username>\Documents\C64\WinVICE-2.4\x64.exe ROUTFILE

Using ACME, PuCrunch and Vice on OS X

/usr/local/bin/acme --outfile OUTFILE --format cbm SOURCEFILE
/usr/local/bin/pucrunch UNCOMPFILE COMPFILE -xSTART
open /Applications/Vice64/x64.app COMPFILE

Using ACME, Exomizer and Vice, with white space in path

"C:\Users\<username>\Documents\C64\sontige tools\acme 0.9\acme.exe" --outfile ROUTFILE --format cbm RSOURCEFILE
C:\Users\<username>\Documents\C64\Exomizer\exomizer.exe sfx basic UNCOMPFILE -o COMPFILE
C:\Users\<username>\Documents\C64\WinVICE-2.4\x64.exe COMPFILE

Using ACME and VICE on OS X

/usr/local/bin/acme --outfile OUTFILE --format cbm SOURCEFILE
open /Applications/Vice64/x64.app OUTFILE

Editor

Note! Since the syntax of labels, macros and functions differs among the various assemblers, the assembler settings information is needed for the auto-completion-feature to work.

Auto-completion for labels

While typing, press ctrl+space to open a popup with a list of all labels that match the previous chars to complete and insert a label name. If you did not already started typing before pressing ctrl+space, all available labels will be shown in the popup. Press Enter or mouse click on a label to insert it or complete your input.

Note that only those local labels within reachable scope will be shown in the popup. Furthermore, you can continue typing while the popup is visible. The list of labels will then be filtered.

If no matching label was found, ctrl+space then automatically tries to extract functions, macros and script-commands. However, you can directly start auto-completion for functions, macros and script-commands with ctrl+shift+space.

Auto-completion for functions, macros and script-commands

While typing, press ctrl+shift+space to open a popup with a list of all functions, macros or scripting-language-commands that match the previous chars to complete the related name. If you did not already started typing before pressing ctrl+shift+space, all available function or macro names or scripting-language-commands will be shown in the popup. Press Enter or mouse click on an item to insert it or complete your input.

Drag & drop

You can drag & drop files from the file explorer (or finder, nautilus, etc.) into the editor area to either open them or include them into your source. The drop operation depends on which modifier keys (shift and control) you hold down while dropping the selected file(s).

Number conversion

Type any numbers in the text fields at the bottom status bar to automatically see the converted numbers in decimal, hex and octal format. Furthermore, if you select a number in the source code, the converted values will also be shown in the conversion text fields.


Undocumented editor shortcuts

Here is a list of shortcuts for the editor:


File menu

This menu includes typical file operations like opening, saving and closing files. Note that the latest ten recent files can be opened quickly via the Recent files submenu, and that the associated assembler and user script settings will be restored automatically when opening a recent document.

Source code files that are included via include-directive (e.g. !src "mysource.a") can be automatically opened using the Open included source or Open all included sources. The first command opens a source file if the related include-directive is in the current caret/edit-line. The latter commands scans the complete current source for any include-directive and opens all source files.


Edit menu

This menu contains the default edit operations like cut, copy, paste, but also undo and redo.


Find menu

Contains all find and replace operation for current active documents. Both the Find searchterm and the Replace command will open an edit field below the source code window where find and replace terms can be edited.

The Find searchterm function also accepts regular expressions.

Use buttons beside the text fields or menu shortcuts / hotkeys to jump to the next or previous occurence of a searchterm.


Navigate menu

Note! The goto- and jump-functions only work properly if the assembler settings for each source code is correctly set. Since the syntax of labels, macros and functions differs among the various assemblers, the assembler setting information is needed for the navigate-functions to work.

The Goto-commands / Sidebar

Except for the Goto line command, each of the goto commands opens a sidebar to the right of the editor window. The content of this list depends on the context, i.e. the command that opened this list. The Goto label command, for instance, extracts all labels from all currently opened files and lists them in the drop down list. A gray, uppercased heading with the related file name indicates to which file the labels from this list belong. Selecting an item will choose the related file and scrolls the caret to the line containing the label.

The Goto function or Goto macro command work in a similar way, just that the sidebar list contains all functions or macros found in all opened files.

The Goto section command lets you choose any section to jump. Section are specific comments on the source code, which can be used to structure your source. See Source menu for more details.

The Goto line command sets the input focus into the text field at the bottom left part, where you can enter any line number. Then the content will scroll to this line.


The sidebar textfield

Under the sidebar is a textfield where you can find entries by typing. Entries from the sidebar that start with your input are automatically selected. To filter the sidebar-list, press Enter. All list-items that contain the text input remain in the list, all other entries will be removed.


The Jump-commands

Unlike the Goto commands, which scroll to a specific label, function, macro... etc., the Jump commands scroll to the next, respectively to the previous occurence of a label, section or error. Next and previous relate to the current caret position.

While the Jump to next/prev label and Jump to next/prev section commands only work when you have labels or sections defined in your source, the Jump to next/prev error command only works after you have compiled a source file that contains errors. In case the assembler stops parsing your source code due to errors, the Assembler log is shown and you can cycle through all errors with the Jump to next/prev error command.

The Jump to label command only works when the caret (cursor) is positioned over a label inside your source code. The command will then scroll to the line where this label is defined.


Source menu

Running and selecting scripts

The Run script command runs the currently selected user script. The script selection list typically is under the log-textfields. User script are commands that you would typically type into the console or terminal in order to run assemblers, crunchers or emulators. With these scripts you can execute your assembler, cruncher and emulator in order to compile your source code and watch the compiled file in an emulator.

You can set up as much different scripts as you want in order to get various compile and run options. Please refere to the preferences, select the Compile & Run tab and click on the help button for details on user scripts.

With the Select script command the input focus is set to the drop down list with all user scripts. This is a convenience command for quickly switching between scripts using the keyboard.

Select assembler lets you switch between different assembler syntax schemes (e.g. the KickAss syntax differs from ACME and 64tass) in order to correctly highlight keywords, comments, assembler directives etc. and in order to make the navigate functions work correctly.


Toggle and insert commands

The Toggle comment command comments or uncomments the current selection. Note that this command only works when text is selected.

Insert section inserts a specific command line with a named label, which can be used to structure your source and easily navigate through it (see Navigate menu). Insert separator inserts a simple commented dashed line as separator.

The Insert Basic start command adds a short asm code snippet that adds a Basic line to the compiled source code with a Sys-command to start your code.

Inserts bytes from file reads a file byte-wise and insert all bytes of that file as byte-table. The Insert sinus table command opens an input window where you can specifiy parameters for computing a sinus curve, which will be inserted as byte-table into your source.


View menu

With the commands of the View menu, it is possible to switch the position and layout of the log windows and the Compile and Run area. Furthermore, you can quickly show one of the log windows.