6502bench SourceGen: Code Generation & Assembly
SourceGen can generate an assembly source file that, when fed into the target assembler, will recreate the original data file exactly. Every assembler is different, so support must be added to SourceGen for each.
The generation / assembly dialog can be opened with File > Assemble.
Supported Assemblers
SourceGen currently supports the following cross-assemblers:
Version-Specific Code Generation
Code generation must be tailored to the specific version of the assembler. This is most easily understood with an example.
If you write MVN $01,$02, the assembler is expected to output
54 02 01, with the arguments reversed. cc65 v2.17 doesn't
do that; this is a bug that was fixed in a later version. So if you're
generating code for v2.17, you want to create source code with the
arguments the wrong way around.
Having version-dependent source code is a bad idea, so SourceGen just outputs raw hex bytes for MVN/MVP instructions. This yields the correct code for all versions of the assembler, but is ugly and annoying. So we want to output actual MVN/MVP instructions when producing code for newer versions of the assembler.
When you configure a cross-assembler, SourceGen executes it and extracts the version information from the command-line output stream. This is used by the generator to ensure that the output will compile. If no assembler is configured, SourceGen will produce code optimized for the latest version of the assembler.
Generating Source Code
Cross assemblers tend to generate additional files, either compiler intermediaries ("file.o") or metadata ("_FileInformation.txt"). Some generators may produce multiple source files, perhaps a link script or symbol definition header to go with the assembly source. To avoid spreading files across the filesystem, SourceGen does all of its work in the same directory where the project lives. Before you can generate code, you have to have given your project a name by saving it.
The Generate and Assemble dialog has a drop-down list near the top that lets you pick which assembler to target. The name of the assembler will be shown with the detected version number. If the assembler executable isn't configured, "[latest version]" will be shown instead of a version number.
The Settings button will take you directly to the assembler configuration tab in the application settings dialog.
Hit the Generate button to generate the source code into a file on disk. The file will use the project name, with the ".dis65" replaced by "_<assembler>.S".
The first 64KiB of each generated file will be shown in the preview window. If multiple files were generated, you can use the "preview file" drop-down to select between them. Line numbers are prepended to each line to make it easier to track down errors.
Label Localizer
The label localizer is an optional feature that automatically converts some labels to an assembler-specific less-than-global label format. Local labels may be reusable (e.g. using "]LOOP" for multiple consecutive loops is easier to understand than giving each one a unique label) or reduce the size of a generated link table. There are usually restrictions on local labels, e.g. references to them may not be allowed to cross a global label definition, which the localizer factors in automatically.
The localizer is somewhat experimental at this time, and can be disabled from the application settings.
Cross-Assembling Generated Code
After generating sources, if you have a cross-assembler executable configured, you can run it by clicking the "Run Assembler" button. The command-line output will be displayed, with stdout and stderr separated. (I'd prefer them to be interleaved, but that's not what the system provides.)
The output will show the assembler's exit code, which will be zero on success (note: sometimes they lie.) If it appeared to succeed, SourceGen will then compare the assembler's output to the original file, and report any differences.
Failures here may be due to bugs in the cross-assembler or in SourceGen. However, SourceGen can generally work around assembler bugs, so any failure is an opportunity for improvement.