6502bench/SourceGen/RuntimeData/Help/settings.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="main.css" rel="stylesheet" type="text/css" />
<title>Properties &amp; Settings - 6502bench SourceGen</title>
</head>

<body>
<div id="content">
<h1>6502bench SourceGen: Properties &amp; Settings</h1>
<p><a href="index.html">Back to index</a></p>

<h2><a name="overview">Settings Overview</a></h2>

<p>There are two kinds of settings: application settings, and
project properties.</p>


<h2><a name="app-settings">Application Settings</a></h2>

<p>Application settings are stored in a file called "SourceGen-settings"
in the SourceGen installation directory.  If the file is missing or
corrupted, default settings will be used.  These settings are local
to your system, and include everything from window sizes to whether or not
you prefer hexadecimal values to be shown in upper case.  None of them
affect the way the project analyzes code and data, though they may affect
the way generated assembly sources look.</p>

<p>The settings editor is divided into four tabs.  Changes don't take
effect until you hit Apply or OK.</p>


<h3><a name="appset-codeview">Code View</a></h3>

<p>These settings change the way the code looks on screen.</p>

<p>Click the Column Visibility buttons to hide columns.  Click them
again to restore the column to a width appropriate for the current font.
A "hidden" column just has a width of zero, so with careful mouse
positioning you can show and hide columns by dragging the column headers.
The buttons may be more convenient though.</p>

<p>You can select a different font for the code list, and make it as large
or as small as you want.  Mono-space fonts like Courier or Consolas are
recommended (and will be the only ones shown).</p>

<p>You can choose to display different parts of the display in upper or
lower case, using the "all lower" and "all upper" buttons as a quick way
to set all values.  These settings are also used for generated assembly
code, unless the assembler has specific case-sensitivity requirements.  There
is no setting for labels, which are always case-sensitive.</p>

<p>The Clipboard drop-down list lets you choose the format for text
<a href="mainwin.html#clipboard">copied to the clipboard</a>.  The
"Assembler Source" format includes the rightmost columns (label,
opcode, operand, and comment), like assembly source code does.  The
"Disassembly" format adds the address and bytes on the left.  Use
the "All Columns" format to get all columns.</p>

<p>The "add spaces in bytes column" checkbox changes the format of the
hex data in the code list "bytes" column from dense (<code>20edfd</code>)
to spaced (<code>20 ed fd</code>).  This also affects the format of
clipboard copies and exports.</p>

<p>Check "use 'dark' color scheme" to change the main disassembly list
to use white text on a black background, and mute the Note highlight
colors.
(Most of the GUI uses standard Windows controls that take their colors
from the system theme, but the disassembly list uses a custom style.  You
can change the rest of the UI from the Windows display "personalization"
controls.)</p>


<h3><a name="appset-textdelim">Text Delimiters</a></h3>

<p>Character and string operands are shown surrounded by quotes, e.g.
<code>LDA #'*'</code> or <code>.STR "Hello, world!"</code>.  It's
handy to be able to tell at a glance how characters are encoded, so
SourceGen allows you to set the delimiters independently for every
supported character encoding.</p>
<p>String operands may contain a mixture of text and hexadecimal values.
For example, in ASCII data, the control characters for linefeed and
carriage return ($0a and $0d) are considered part of the string, but
don't have a printable symbol.  (Unicode defines some glpyhs, but they
don't look very good at smaller font sizes.)</p>
<p>If one of the delimiter characters appears in the string itself,
the character will be output as hex to avoid confusion.  For this
reason, it's generally wise to use delimiter characters that aren't
part of the ASCII character set.  The "Sample Characters" box holds some
characters that you can copy and paste (with Ctrl+C / Ctrl+V) into the
delimiter fields.</p>
<p>For character operands, the prefix and suffix are added to the start
and end of the operand.  For string operands, the prefix is added to the
start of the first line, and suffixes aren't allowed.
<p>These options change the way the code list looks on screen.  They
do not affect generated code, which must use the delimiter characters
specified by the chosen assembler.</p>


<h3><a name="appset-asmconfig">Asm Config</a></h3>

<p>These settings configure cross-assemblers and modify assembly source
generation in various ways.</p>
<p>To configure an assembler, select it in the pop-up menu.  The fields
will initially contain assembler-specific default values.  All of
the values in the Assembler Configuration box may be configured
differently for each assembler.</p>
<p>The "executable" box holds the full path to the cross-assembler
executable.</p>
<ul>
  <li>64tass: <code>64tass.exe</code>
  <li>ACME: <code>acme.exe</code>
  <li>cc65: <code>bin/cl65.exe</code> -- full installation required,
    with all configuration files and libraries
  <li>Merlin 32: <code>Merlin32.exe</code>
</ul>
<p>The "column widths" section allows you to specify the minimum
width of the label, opcode, operand, and comment fields.  If the width
is less than 1, or isn't a valid number, 1 will be used.  These are
not hard stops: if the contents of a field are too wide, the contents
of the next column will be pushed over.  (The comment field width is
not currently being used, but may be used to fold lines in the future.)</p>

<p>When "show cycle counts" is checked, every instruction line will have
an end-of-line comment that indicates the number of cycles required for
that instruction.  This is shown in the code list and included in
generated assembly output.  If the cycle count can't be determined solely
from a static analysis, e.g. an extra cycle is required if
<code>LDA (dp),Y</code> crosses a page boundary, a '+' will be shown.
In some cases the variability can be factored out if the state of
certain status flags is known, e.g. 65C02 instructions that take longer
in decimal mode won't be shown as variable if the analyzer can determine
that D=0 or D=1.</p>

<p>If "put long labels on separate line" is checked, labels that are
longer than the label column are placed on their own line.  This looks
a bit nicer because otherwise the opcode gets pushed out of alignment.
(Some assemblers get bent out of shape if you split an equate
directive, so those might stay on one line.)</p>

<p>If you enable "identify assembler in output", a comment will be
added to the top of the generated assembly output that identifies the
target assembler and version.  It also shows the command-line options
passed to the assembler.  This can be very helpful if the source
file is sent to other people, since it may not otherwise be obvious from
the source file what the intended target assembler is, or what options
are required to process the file correctly.</p>


<h3><a name="appset-displayformat">Display Format</a></h3>

<p>These options change the way the code list looks on screen.  They
do not affect generated code.</p>

<p>The
<a href="intro.html#width-disambiguation">operand width disambiguator</a>
strings are used when the width of an instruction operand is unclear.
You may specify values for all of them or none of them.</p>

<p>Different assemblers have different ways of forming expressions.
Sometimes the rules allow expressions to be written simply, other times
explicit grouping with parenthesis is required.  Select whichever style
you are most comfortable with.</p>

<p>Non-unique labels are identified with a prefix character, typically
'@' or ':'.  The default is '@', but you can configure it to any character
that isn't valid for the start of a label.  (64tass uses '_' for locals,
but that's a valid label start character, and so isn't allowed here.)
The setting affects label editing as well as display.</p>

<p>If you would like your local variables to be shown with a prefix
character, you can set it in the "local variable prefix" box.</p>

<p>The "quick set" pop-up configures the fields on this tab to match
the conventions of the specified assembler.  Select your preferred assembler
in the combo box to set the fields.  The setting automatically switches to
"custom" when you edit a field.  (64tass and ACME use the "common"
expression style, cc65 and Merlin 32 have their own unique styles.)</p>


<h3><a name="appset-pseudoop">Pseudo-Op</a></h3>

<p>These options change the way the code list looks on screen.  Assembler
directives and data pseudo-opcodes will use these values.  This does
not affect generated source code, which always matches the conventions
of the target assembler.</p>

<p>Enter the string you want to use for the various data formats.  If
a field is left blank, a default value is used.</p>

<p>The "quick set" pop-up configures the fields on this tab to match
the conventions of the specified assembler.  Select your preferred assembler
in the combo box to set the fields.  The setting automatically switches to
"custom" when you edit a field.</p>


<h2><a name="project-properties">Project Properties</a></h2>

<p>Project properties are stored in the .dis65 project file.
They specify which CPU to use, which extension scripts to load, and a
variety of other things that directly impact how SourceGen processes
the project.  Because of the potential impact, all changes to
the project properties are made through the undo/redo buffer.</p>

<p>The properties editor is divided into four tabs.  Changes aren't pushed
out to the main application until you close the dialog.  Clicking Apply
will capture the current changes, ensuring that they're applied even if
you later hit Cancel, but the changes are not applied immediately.</p>
<p>All changes are subject to undo/redo.</p>


<h3><a name="projprop-general">General</a></h3>

<p>The choice of CPU determines the set of available instructions, as
well as cycle costs and register widths.  There are many variations
on the 6502, but from the perspective of a disassembler most can be
treated as one of these three:</p>
<ol>
  <li>MOS 6502.  The original 8-bit instruction set.</li>
  <li>WDC W65C02S.  Expanded the instruction set and smoothed
    some rough edges.</li>
  <li>WDC W65C816S.  Expanded instruction set, 24-bit address space,
    and 16-bit registers.</li>
</ol>
<p>The Rockwell R65C02, Hudson Soft HuC6280, and Commodore CSG 4510 / 65CE02
have instruction sets that expand on the 6502/65C02, but aren't compatible
with the 65816.  These are not yet supported by SourceGen.</p>

<p>If "enable undocumented instructions" is checked, some additional
opcodes are recognized on the 6502 and 65C02.  These instructions are
not part of the chip specification, but most of them have consistent
behavior and can be used.  If the box is not checked, the instructions
are treated as invalid and cause the code analyzer to assume that it
has run into a data area.  This option has no effect on the 65816.</p>
<p>The "treat BRK as two-byte instruction" checkbox determines whether
BRK instructions should be handled as if they have an operand.</p>

<p>The entry flags determine the initial value for the processor status
flag register.  Code that is unreachable internally (requiring a code
entry point hint) will use this value.  This is chiefly of value for
65816 code, where the initial value of the M/X/E flags is significant.</p>

<p>If "analyze uncategorized data" is checked, SourceGen will attempt to
identify character strings and regions that are filled with a repeated
value.  If it's not checked, anything that isn't detected as code or
explicitly formatted as data will be shown as individual byte values.</p>
<p>If "seek nearby targets" is checked, the analyzer will try to use
nearby labels for data loads and stores, adjusting them to fit
(e.g. <code>LDA LABEL+1</code>).  If not enabled, labels are not applied
unless they match exactly.  Note that references into the middle of an
instruction or formatted data area are always adjusted, regardless of
how this is set.  This setting has no effect on local variables, and
only enables a 1-byte backward search on project/platform symbols.</p>
<p>If "smart PLP handling" is checked, the analyzer will try to use
the processor status flags from a nearby <code>PHP</code> when a
<code>PLP</code> is encountered.  If not enabled, all flags are set to
"indeterminate" following a <code>PLP</code>.</p>

<p>The "default text encoding" setting has two effects.  First, it
specifies which character encoding to use when searching for strings in
uncategorized data.  Second, if an assembler has a notion of preferred
character encoding (e.g. you can default string operands to PETSCII),
this setting will determine which encoding is preferred.</p>
<p>The "min chars for string detection" setting determines how many
ASCII characters need to appear consecutively for the data analyzer to
declare it a string.  Shorter values are prone to false-positive
identifications, longer values miss out on short strings.  You can also
set it to "none" to disable automatic string identification.</p>

<p>The auto-label style setting determines the format for labels that are
generated automatically.  By default the label will be the letter 'L'
followed by the hexadecimal address, but the label can be annotated based
on usage.  For example, addresses that are the target of branch instructions
can be labeled with the letter 'B'.</p>


<h3><a name="projprop-projsym">Project Symbols</a></h3>
<p>You can add, edit, and delete individual symbols and constants.
See the <a href="intro.html#about-symbols">symbols</a> section for an
explanation of how project symbols work.</p>

<p>The Edit Symbol button opens the
<a href="editors.html#project-symbol">Edit Project Symbol</a> dialog, which
allows changing any part of a symbol definition.  You're not allowed to
create two symbols with the same label.</p>

<p>The Import button allows you to import symbols from another project.
Only labels that have been tagged as global and exported will be imported.
Existing symbols with identical labels will be replaced, so it's okay to
run the importer multiple times.  Labels that aren't found will not be
removed, so you can safely import from multiple projects, but will need
to manually delete any symbols that are no longer being exported.</p>

<p>Shortcut: you can open the project properties window with the
Project Symbols tab selected by hitting F6 from the main code list.</p>


<h3><a name="projprop-symfiles">Symbol Files</a></h3>
<p>From here, you can add and remove platform symbol files, or change
the order in which they are loaded.
See the <a href="intro.html#about-symbols">symbols</a> section for an
explanation of how platform symbols work, and the
<a href="advanced.html#platform-symbols">advanced topics</a> section
for a description of the file syntax.</p>

<p>Platform symbol files must live in the RuntimeData directory that comes
with SourceGen, or in the directory where the project file lives.  This
is mostly to keep things manageable when projects are distributed to
other people, but also acts as a minor security check, to prevent a
wayward project from trying to open files it shouldn't.</p>
<p>Click one of the "Add Symbol Files" buttons to include one or more
symbol files in the project.
The "Add Symbol Files from Runtime" button sets the directory
to the SourceGen RuntimeData directory, while "Add Symbol Files from Project"
starts in the project directory.  If you haven't yet saved the project,
the latter button will be disabled.  The only difference between the
buttons is the initial directory.</p>
<p>In the list, files loaded from the RuntimeData directory will be
prefixed with <code>RT:</code>.  Files loaded from the project directory
will be prefixed with <code>PROJ:</code>.</p>
<p>If a platform symbol file can't be found when the project is opened,
you will receive a warning.</p>


<h3><a name="projprop-extscripts">Extension Scripts</a></h3>
<p>From here, you can add and remove extension script files.
See the <a href="advanced.html#extension-scripts">extension scripts</a>
section for details on how extension scripts work.</p>

<p>Extension script files must live in the RuntimeData directory that comes
with SourceGen, or in the directory where the project file lives.  This
is mostly to keep things manageable when projects are distributed to
other people, but also acts as a minor security check, to prevent a
wayward project from trying to open files it shouldn't.</p>
<p>Click one of the "Add Scripts" buttons to include one more scripts in
the project.  The "Add Scripts from Runtime" button sets the directory
to the SourceGen RuntimeData directory, while "Add Scripts from Project"
starts in the project directory.  If you haven't yet saved the project,
the latter button will be disabled.  The only difference between the
buttons is the initial directory.</p>
<p>In the list, files loaded from the RuntimeData directory will be
prefixed with <code>RT:</code>.  Files loaded from the project directory
will be prefixed with <code>PROJ:</code>.</p>
<p>If an extension script file can't be found when the project is opened,
you will receive a warning.</p>

</div>

<div id="footer">
<p><a href="index.html">Back to index</a></p>
</div>
</body>
<!-- Copyright 2018 faddenSoft -->
</html>