mirror of
https://github.com/fadden/6502bench.git
synced 2025-02-28 10:29:02 +00:00
eef1710d5d
Two main changes: - "Seek nearby targets" is no longer enabled by default. - The application asks the user to save new projects immediately. Various minor edits were also made. A couple of the images are slightly stale, showing ".org" rather than ".addrs", but they're in the advanced section and the difference isn't notable.
242 lines
10 KiB
HTML
242 lines
10 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<!-- START: /incl-head.html -->
|
|
<!-- common head elements -->
|
|
<meta charset="utf-8"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
|
|
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
|
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
|
|
<link rel="stylesheet" href="../main.css"/>
|
|
<!-- END: /incl-head.html -->
|
|
|
|
<title>Using SourceGen - SourceGen Tutorial</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- START: /incl-masthead.html -->
|
|
<div id="masthead">
|
|
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
|
|
<div class="masthead-title">
|
|
6502bench
|
|
</div>
|
|
</div>
|
|
<!-- END: /incl-masthead.html -->
|
|
|
|
<!-- START: /incl-topnav.html active:#topnav-sgtutorial -->
|
|
<div id="topnav">
|
|
<!-- top navigation bar contents -->
|
|
<nav>
|
|
<a id="topnav-home" href=".././">HOME</a>
|
|
<a id="topnav-sgtutorial" class="active" href="../sgtutorial">SourceGen Tutorial</a>
|
|
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
|
|
<i class="fa fa-bars"></i>
|
|
</a>
|
|
</nav>
|
|
<script>
|
|
// Sidenav toggle function.
|
|
//
|
|
// Use a jQuery function to toggle the sidenav bar. The initial state
|
|
// is undefined / inherited, so it will pop in and out as the screen
|
|
// resizes around the "large" breakpoint.
|
|
function toggleSidenav() {
|
|
$("#sidenav").toggle("fast");
|
|
}
|
|
</script>
|
|
</div>
|
|
<!-- END: /incl-topnav.html -->
|
|
|
|
<!-- START: incl-sidenav.html active:#sidenav-using-sourcegen -->
|
|
<div id="sidenav">
|
|
<!-- side navigation bar contents -->
|
|
<ul>
|
|
<li id="sidenav-index"><a href="./">Introduction</a></li>
|
|
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
|
|
<li id="sidenav-using-sourcegen" class="active"><a href="using-sourcegen.html">Using SourceGen</a>
|
|
<ul>
|
|
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
|
|
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
|
|
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels & Symbols</a></li>
|
|
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
|
|
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
|
|
</ul></li>
|
|
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a>
|
|
<ul>
|
|
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
|
|
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
|
|
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
|
|
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds & Ends</a></li>
|
|
</ul></li>
|
|
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a>
|
|
<ul>
|
|
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
|
|
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
|
|
<li id="sidenav-visualizations"><a href="visualizations.html">Visualizations</a></li>
|
|
</ul></li>
|
|
<li id="sidenav-suggestions"><a href="suggestions.html">Suggestions</a></li>
|
|
</ul>
|
|
</div>
|
|
<!-- END: incl-sidenav.html -->
|
|
|
|
<div id="main">
|
|
|
|
<h2>Using SourceGen</h2>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>Many disassemblers take a very simple approach: they dump
|
|
the entire binary as if it were an instruction stream. It's then
|
|
left to the human to carve away the data sections. SourceGen
|
|
comes at the problem from a different angle, and assumes
|
|
everything is data until proven otherwise. The human need only
|
|
identify where code areas start. The computer will trace through
|
|
code automatically, following branches and subroutine calls, and
|
|
whatever isn't traced is either data storage or junk (dead code,
|
|
alignment padding, etc).</p>
|
|
<p>The difference in approach can be confusing at first for people
|
|
accustomed to other software. Code tracing tends to produce better
|
|
results more quickly, however, because much of the tedium is handled
|
|
by the software.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<hr style="width:80%;"/>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>This first section covers the basics of working with SourceGen: how to
|
|
move around, make edits, generate code, and so on.
|
|
You can't do anything useful until you open an existing project or
|
|
create a new one, so we'll start there.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>A SourceGen project is always associated with a data file, which
|
|
holds part or all of the program being disassembled.
|
|
For simplicity, the project is given the same name as the data file, with
|
|
<code>.dis65</code> on the end.
|
|
No part of the data file is included in the project file, so you need
|
|
to keep both files in the same place.
|
|
If the program you're disassembling was split into more than one data
|
|
file, you'll need a separate project file for each (or combine them into
|
|
a single file with the concatenation tool).</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-fresh-install.png" alt="t1-fresh-install"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>To start a new project, launch SourceGen, and click on the
|
|
"Start New Project" button on
|
|
the initial screen, or use <samp>File > New</samp>. This opens the "New Project"
|
|
window, which lets you specify the target system and data file.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-new-project.png" alt="t1-new-project"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Choosing a target system, such as Apple //e or Commodore 64, will
|
|
create a project configured with the appropriate CPU and options.
|
|
If nothing in the list matches the file you want to work on,
|
|
there are "generic" entries for each
|
|
of the primary CPU varieties (6502, 65C02, W65C02, and 65816). If
|
|
you're unsure, just take your best guess. It's easy to change things after the
|
|
project has been started.</p>
|
|
<p>The area on the right side of the window has a list of the symbol
|
|
files, scripts, and optional features that will be enabled for the
|
|
selected system. The various items here will be explained in more
|
|
detail later on.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-new-tutorial1.png" alt="t1-new-tutorial1"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>For this tutorial, we're going to use "<samp>Generic 6502</samp>",
|
|
near the bottom of the list.</p>
|
|
<p>The other thing we need to do here is select the data file to be
|
|
disassembled. Click <samp>Select File</samp>, navigate to the <samp>Examples</samp>
|
|
directory in the SourceGen installation directory, open <samp>Tutorial</samp>,
|
|
and select <samp>Tutorial1</samp>.
|
|
<p>Click <samp>OK</samp> to create the project.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>You will be asked to save the project file.
|
|
Some features create or load files from the directory where the project
|
|
file lives, so we want to establish where that is. It also enables the
|
|
optional auto-save feature. Save it with the default name
|
|
(<kbd>Tutorial1.dis65</kbd>), in the directory where the tutorial data
|
|
file lives.</p>
|
|
<p>(It's okay to create the project in the installation directory. You
|
|
don't need to work off of a copy of the data file; SourceGen doesn't modify
|
|
it, so you don't have to worry about trashing the example data.)</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t1-settings.png" alt="t1-settings"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>The disassembly display can be tailored to your personal
|
|
preferences. Use <samp>Edit > Settings</samp> to open the
|
|
settings editor. You can change fonts, upper/lower case, text
|
|
delimiters, line wrapping, pseudo-op names, and more. There
|
|
are "quick set" buttons on some screens that allow you to make the
|
|
output resemble various popular assemblers.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>All app settings are local to your system, and do not affect
|
|
the project in any way. If somebody else opens the same project,
|
|
they may see entirely different pseudo-ops and upper-case choices,
|
|
based on their own personal preferences.
|
|
(The settings that affect projects are accessed through a
|
|
different screen, via <samp>Edit > Project Properties</samp>.)</p>
|
|
|
|
<p>For now, click <samp>Cancel</samp> to leave everything set to
|
|
default values.</p>
|
|
</div>
|
|
</div>
|
|
|
|
</div> <!-- #main -->
|
|
|
|
<div id="prevnext">
|
|
<a href="about-disasm.html" class="btn-previous">« Previous</a>
|
|
<a href="moving-around.html" class="btn-next">Next »</a>
|
|
</div>
|
|
|
|
<!-- START: /incl-footer.html -->
|
|
<div id="footer">
|
|
<hr/>
|
|
<p>Copyright 2021 faddenSoft</p>
|
|
<!-- <p id="screen-size"></p>
|
|
<script>
|
|
var w = window.innerWidth;
|
|
var h = window.innerHeight;
|
|
var x = document.getElementById("screen-size");
|
|
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
|
|
</script> -->
|
|
</div>
|
|
<!-- END: /incl-footer.html -->
|
|
|
|
</body>
|
|
</html>
|