Restructure help documentation to use the WUDSN IDE Installer

This commit is contained in:
Peter Dell 2022-12-26 03:58:08 +01:00
parent f584cfbf31
commit e46bd1f5fb
3 changed files with 243 additions and 445 deletions

View File

@ -8,8 +8,8 @@
<li><a href="#HexEditor">Hex Editor</a></li>
<li><a href="#GraphicsEditor">Graphics Editor</a></li>
<li><a href="#Preferences">Preferences for editing</a></li>
<li><a href="#CompilerPreferences">Preferences for compiling</a></li>
<li><a href="#CompilerAnnotations">Annotations for compiling</a></li>
<li><a href="#CompilerPreferences">Preferences for assembling and compiling</a></li>
<li><a href="#CompilerAnnotations">Annotations for assembling and compiling</a></li>
<li><a href="#KnownBugs">Known Bugs</a></li>
<li><a href="#PlannedFeatures">Planned features</a></li>
</ul>

View File

@ -1,31 +1,15 @@
<p>There are two ways of installing WUDSN IDE. If you are using a Windows operating system, I recommend downloading the
ready to run zero installation distribution:</p>
<div align="center"><a href="https://www.wudsn.com/productions/java/ide/downloads/wudsn-ide-win64.zip" target="_blank"
rel="noopener noreferrer"> <img src="productions/java/ide/installation/ide-download-win64.png"
alt="Click to download the Windows 64-bit version" /></a></div>
<p>It contains the Eclipse Platform, the Java Runtime Environment, the latest stable version of the WUDSN IDE plugin,
all supported compilers, and an emulator for each supported platform. All paths to folders, compilers, and emulators
are pre-configured. Unpack the content of this archive to the directory "C:\jac\wudsn" and click the "WUDSN IDE-64
bit" link. Eclipse will open with the predefined workspace that contains "Hello World" examples for different
platforms. <br /> <br /> If you use another operating system or want to use the latest version of WUDSN or want to
install compilers and emulators more selectively, read the descriptions of the installation steps below. In
addition, the following previous versions of the zero installation distribution are available</p>
<ul>
<li>WUDSN IDE 1.7.0: <a href="https://www.wudsn.com/productions/java/ide/downloads/1.7.0/wudsn-ide-win64.zip"
target="_blank" rel="noopener noreferrer">Windows 64-bit version</a>, <a
href="https://www.wudsn.com/productions/java/ide/downloads/1.7.0/wudsn-ide-win32.zip" target="_blank"
rel="noopener noreferrer">Windows 32-bit version</a></li>
<li>WUDSN IDE 1.6.6: <a href="https://www.wudsn.com/productions/java/ide/downloads/1.6.6/wudsn-ide-win64.zip"
target="_blank" rel="noopener noreferrer">Windows 64-bit version</a>, <a
href="https://www.wudsn.com/productions/java/ide/downloads/1.6.6/wudsn-ide-win32.zip" target="_blank"
rel="noopener noreferrer">Windows 32-bit version</a></li>
</ul>
<p>In case something is not correct or not working, please contact me.</p>
<p id="ide_installation">
The recommended way to install WUDSN IDE, is the <a href="https://github.com/peterdell/wudsn-ide-install#readme" target="_blank"
rel="noopener noreferrer">WUDSN IDE Installer</a>. It is currently available for Window 64-bit, version for mac OS X and Linux are planned.</p>
<p>
If you use another operating system or want to use the an older version of WUDSN or want to install assemblers,
compilers and emulators more selectively, read the descriptions of the installation steps below.
In case something is not correct or not working, please contact me.</p>
<ul>
<li><a href="#InstallingEclipse">Installing Eclipse</a></li>
<li><a href="#InstallingWUDSNIDE">Installing WUDSN IDE</a></li>
<li><a href="#InstallingCompilers">Installing compilers like ATASM, MADS, XASM...</a></li>
<li><a href="#InstallingEmulators">Installing Atari800Win and other emulators</a></li>
<li><a href="#InstallingAssemblersAndCompilers">Installing assemblers and compilers like ATASM, MADS, XASM...</a></li>
<li><a href="#InstallingEmulators">Installing Altirra, Atari800 and other emulators</a></li>
<li><a href="#CreatingExampleProject">Creating and compiling an example project</a></li>
<li><a href="#FurtherAssemblerProgrammingInformation">Further information on assembler programming</a></li>
</ul>
@ -66,7 +50,7 @@
<ul>
<li>Start Eclipse</li>
<li>Select the entry "Install New Software..." from the menu "Help".</li>
<li>Enter "https://www.wudsn.com/update" in the "Work with" field and press ENTER.</li>
<li>Enter "https://www.wudsn.com/update/stable" in the "Work with" field and press ENTER.</li>
<li>Select the latest version of the feature "WUDSN IDE" for in and press the button "Next". <br /> You don't need
to install the "General Eclipse Enhancements" feature as it is already included in the "WUDSN IDE" feature".
</li>
@ -78,302 +62,111 @@
<li>As always with updates, it may happen that the update fails for whatever reason or the installed version turns
out to have severe issues. For example, the required Java version might not be available on your machine. In
this case, you can uninstall it via the link "What is already installed" in the "Install New Software..." dialog
and restart the IDE. Then you can reinstall the latest version from "https://www.wudsn.com/update" or previously
released versions from the locations listed in the "Releases" chapter. <br /> <img
and restart the IDE. Then you can reinstall the latest version from "https://www.wudsn.com/update/stable" or previously
released versions from the locations listed on the <a href="https://www.wudsn.com/index.php/ide/releases">Releases</a> page. <br /> <img
src="productions/java/ide/installation/ide-installation-steps.gif" alt="IDE installation steps" /></li>
</ul>
<h5 id="InstallingCompilers">Installing compilers like ATASM, MADS, XASM...   <a href="#ide_installation">» top</a></h5>
<h5 id="InstallingAssemblersAndCompilers">Installing assemblers and compilers like ATASM, MADS, XASM...   <a href="#ide_installation">» top</a></h5>
<ul>
<li>Start Eclipse</li>
<li>Select the entry "Preferences" from the menu "Window" (in Windows and Linux) or the menu "Eclipse" (in Mac OS X)
</li>
<li>Open the preferences page "Assembler/Atari 8-bit Compilers" or the respective page for your platform.</li>
<li>Select the tab for the compiler of your choice. <br /> The following compilers are or will be supported: <br />
<li>Open the preferences page "Languages/Assembler/Atari 8-bit Assemblers" or the respective page for your platform.</li>
<li>Select the tab for the assembler or compiler of your choice. The following assemblers and compilers are or will be supported: <br />
<table>
<tbody>
<tr>
<th>Compiler</th>
<th>Language</th>
<th>Tool</th>
<th>Default Target Platform</th>
</tr>
<tr>
<td>Assembler</td>
<td>ACME</td>
<td>C64</td>
</tr>
<tr>
<td>Assembler</td>
<td>ASM6</td>
<td>NES</td>
</tr>
<tr>
<td>Assembler</td>
<td>ATASM</td>
<td>Atari 8-bit</td>
</tr>
<tr>
<td>Assembler</td>
<td>DASM</td>
<td>Atari 2600</td>
</tr>
<tr>
<td>Assembler</td>
<td>KickAss</td>
<td>C64</td>
</tr>
<tr>
<td>Assembler</td>
<td>MADS</td>
<td>Atari 8-bit</td>
</tr>
<tr>
<td>Assembler</td>
<td>XASM</td>
<td>Atari 8-bit</td>
</tr>
<tr>
<td>Assembler</td>
<td>TASS</td>
<td>C64 (in preparation)</td>
</tr>
</tbody>
</table>
</li>
<li>Click the "Download" link to open the home page of the compiler.</li>
<li>Follow the instruction on the download site to install the compiler to the folder of your choice.</li>
<li>Alternatively, you can download the single <a
href="https://www.wudsn.com/productions/java/ide/downloads/compilers.zip" target="_blank"
rel="noopener noreferrer">archive containing all supported 6502 compilers</a> including the Linux and Mac OS
X versions where available. The archive contains a readme file with the date of the last update and the included
compiler versions.  <br />
<table>
<tbody>
<tr>
<th>Compiler</th>
<th>Operating System</th>
<th>Architecture</th>
<th>Compiler Version</th>
<th>Executable Path</th>
<th>Compilation Date</th>
<th>Compiled By</th>
</tr>
<tr>
<td>ACME</td>
<td>Windows</td>
<td>Intel - 32 bit</td>
<td>0.90</td>
<td>ACME / acme.exe</td>
<td>2006-03-19</td>
<td>Krzysztof Dabrowski</td>
</tr>
<tr>
<td>ASM6</td>
<td>Windows</td>
<td>Intel - 32 bit</td>
<td>1.6</td>
<td>ASM6 / asm6.exe</td>
<td>2011-03-11</td>
<td>loopy</td>
</tr>
<tr>
<td>ATASM</td>
<td>Windows</td>
<td>Intel - 32 bit</td>
<td>1.07 (non-final)</td>
<td>ATASM / atasm.exe</td>
<td>2010-05-10</td>
<td>M. Schmelzenbach</td>
</tr>
<tr>
<td>ATASM</td>
<td>Mac OS X</td>
<td>Intel</td>
<td>1.07 (non-final)</td>
<td>ATASM / atasm.macosx-i386</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>ATASM</td>
<td>Mac OS X</td>
<td>PowerPC</td>
<td>1.07 (non-final)</td>
<td>ATASM / atasm.macosx-powerpc</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>ATASM</td>
<td>Linux</td>
<td>Intel - 32 bit</td>
<td>1.07 (non-final)</td>
<td>ATASM / atasm.linux-i386</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>ATASM</td>
<td>Linux</td>
<td>Intel - 64 bit</td>
<td>1.07 (non-final)</td>
<td>ATASM / atasm.linux-x86-64</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>DASM</td>
<td>Windows</td>
<td>Intel - 32 bit</td>
<td>2.20.11</td>
<td>DASM / bin / dasm.exe</td>
<td>2015-05-08</td>
<td>JAC!</td>
</tr>
<tr>
<td>DASM</td>
<td>Mac OS X</td>
<td>Intel</td>
<td>2.20.11</td>
<td>DASM / bin / dasm.macosx-i386</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>DASM</td>
<td>Mac OS X</td>
<td>PowerPC</td>
<td>2.20.11</td>
<td>DASM / bin / dasm.macosx-powerpc</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>DASM</td>
<td>Linux</td>
<td>Intel 32-bit</td>
<td>2.20.11-20140304</td>
<td>DASM / bin / dasm.linux-i386</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>DASM</td>
<td>Linux</td>
<td>Intel 64-bit</td>
<td>2.20.11-20140304</td>
<td>DASM / bin / dasm.linux-x86-64</td>
<td>2015-05-01</td>
<td>JAC!</td>
</tr>
<tr>
<td>KickAss</td>
<td>All</td>
<td>Java</td>
<td>V3.39</td>
<td>KICKASS / KickAss.jar</td>
<td>2015-03-26</td>
<td>Mads Nielsen</td>
</tr>
<tr>
<td>MADS</td>
<td>Windows</td>
<td>Intel - 32 bit</td>
<td>2.0.7 (new features since 1.9.0 are not fully supported in WUDSN IDE yet)</td>
<td>MADS / mads.exe</td>
<td>2014-05-20</td>
<td>JAC!</td>
</tr>
<tr>
<td>MADS</td>
<td>Mac OS X</td>
<td>Intel - 32 bit</td>
<td>2.0.7 (new features since 1.9.0 are not fully supported in WUDSN IDE yet)</td>
<td>MADS / mads.macosx-i386</td>
<td>2017-11-05</td>
<td>JAC!</td>
</tr>
<tr>
<td>MADS</td>
<td>Mac OS X</td>
<td>Intel - 64 bit</td>
<td>2.1.0 (new features since 1.9.0 are not fully supported in WUDSN IDE yet)</td>
<td>MADS / mads.macosx-x64</td>
<td>2021-03-26</td>
<td>John Paul Jones</td>
</tr>
<tr>
<td>MADS</td>
<td>Mac OS X</td>
<td>PowerPC</td>
<td>2.0.7 (new features since 1.9.0 are not fully supported in WUDSN IDE yet)</td>
<td>MADS / mads.macosx-powerpc</td>
<td>2017-11-05</td>
<td>JAC!</td>
</tr>
<tr>
<td>MADS</td>
<td>Linux</td>
<td>Intel - 32 bit</td>
<td>2.0.7 (new features since 1.9.0 are not fully supported in WUDSN IDE yet)</td>
<td>MADS / mads.linux-i386</td>
<td>2017-11-05</td>
<td>JAC!</td>
</tr>
<tr>
<td>TASS</td>
<td>Windows</td>
<td>Intel - 32 bit</td>
<td>1.46 r38</td>
<td>TASS / 64tass.exe</td>
<td>2011-07-03</td>
<td>Soci</td>
</tr>
<tr>
<td>XASM</td>
<td>Windows</td>
<td>Intel - 32 bit</td>
<td>3.1.0</td>
<td>XASM / xasm.exe</td>
<td>2014-07-20</td>
<td>0xF</td>
</tr>
<tr>
<td>XASM</td>
<td>Linux</td>
<td>Intel - 32 bit</td>
<td>3.1.0</td>
<td>XASM / xasm.linux-i386</td>
<td>2014-07-20</td>
<td>0xF</td>
</tr>
<tr>
<td>XASM</td>
<td>Mac OS X</td>
<td>Intel - 32 bit</td>
<td>3.1.0</td>
<td>XASM / xasm.macosx-i386</td>
<td>2014-07-20</td>
<td>0xF</td>
<td>Pascal</td>
<td>MadPascal</td>
<td>Atari 8-bit</td>
</tr>
</tbody>
</table>
</li>
<li>There are 3 ways to download the assemblers / compilers:
<ul>
<li>Option 1: Download the <a
href="https://github.com/peterdell/wudsn-ide-tools/archive/refs/heads/main.zip" target="_blank"
rel="noopener noreferrer">complete assemblers / compilers / emulators package for WUDSN IDE</a>
including the Windows, Linux and macOS X versions where available.
This is the simplest way to get all of them for many operating systems.
The archive contains a readme file with the date of the last update and the included program versions.</li>
<li>Option 2: Download single assemblers / compilers from <a href="https://github.com/peterdell/wudsn-ide-tools" target="_blank"
rel="noopener noreferrer">https://github.com/peterdell/wudsn-ide-tools<a>. Use this option if you prefer to only download what you actually need.</li>
<li>Option 3: Click the "Download" link to open the home page of the assembler / compiler. Use this option, if you need the most recent version of the assembler / compiler.</li>
</ul>
</li>
<li>Follow the instruction on the download site to install the assembler / compiler to the folder of your choice.</li>
<li>In the section "Browse..." button for the field "Path to Compiler" to locate the executable.</li>
<li>If not explicit compiler parameters are specified, the default parameters are used.</li>
<li>If explicit compiler parameters are specified, the default parameters are ignored.</li>
<li>If no explicit assembler / compiler parameters are specified, the default parameters are used.</li>
<li>If explicit assembler / compiler parameters are specified, the default parameters are ignored.</li>
<li>The variable "${sourceFilePath}" is replaced by the absolute path to the source file. <br /> The variable
"${outputFilePath}" is replaced by the absolute path to the output file. <br /> For more variables see section
<a href="#CompilerPreferences">preferences for compiling.</a></li>
"Preferences for assembling and compiling" on the "Features" page.</a></li>
<li>Choose if you want to use the source folder or the temporary folder as the output folder.</li>
<li>Choose the file extension for the output file, for example, ".xex" or ".bin"</li>
<li>Press the button "OK".</li>
<li>Using the button "Restore Defaults" all values are reset, except for the paths to the compilers. <br /> <br />
<li>Using the button "Restore Defaults" all values are reset, except for the paths to the assembler / compilers. <br /> <br />
<img src="productions/java/ide/features/ide-assembler-preferences-compilers.gif"
alt="Configuration of compiler executable path" /></li>
alt="Configuration of aseembler / compiler executable path" /></li>
<li>Using the button "Default" in the "File Associations" preferences you can set the default editor for a file
extension, for example, "MADS" for "*.asm". <br /> <img
src="productions/java/ide/features/ide-editor-file-associations.gif" alt="IDE file associations" /></li>
</ul>
<h5 id="InstallingEmulators">Installing Atari800Win and other emulators   <a href="#ide_installation">» top</a></h5>
<h5 id="InstallingEmulators">Installing Altirra, Atari800 and other emulators   <a href="#ide_installation">» top</a></h5>
<ul>
<li>Start Eclipse.</li>
<li>Select the entry "Preferences" from the menu "Window" (for Windows and Linux) or "Eclipse" (for Mac OS X).</li>
<li>Open the preferences page "Assembler/Atari 8-bit Compilers" and select to tab for your compiler.</li>
<li>Open the preferences page "Languages/Assembler/Atari 8-bit Assemblers" and select to tab for your assembler.</li>
<li>The field "Default Application to open Output File" is defaulted to "Operating System Default Application".
<ul>
<li>If you have the emulator registered as the default application for the extension of the output file, for
example, "Atari800Win" or "Atari800MacX" for ".xex", you don't need to configure anything in addition
example, "Altirra", "Atari800" or "Atari800MacX" for ".xex", you don't need to configure anything in addition
and can skip the steps below.</li>
<li>If your operating system, like for example Linux, does not support default applications or if you need a
special output file extension and special parameters to open the output file in the emulator you can
@ -393,8 +186,8 @@
<li>If no explicit command line is specified, the default command line is used.</li>
<li>If an explicit command line is specified, the default command line is ignored.</li>
<li>The variable "${runnerExecutablePath}" is replaced by the path to the application executable. <br /> The
variable "${outputFilePath}" is replaced by the absolute path to the output file. <br /> For more variables see
section <a href="#CompilerPreferences">preferences for compiling</a>.</li>
variable "${outputFilePath}" is replaced by the absolute path to the output file. <br /> For more variables see section
"Preferences for assembling and compiling" on the "Features" page.</li>
<li>Press the button "OK".</li>
<li>In case you also need the Atari ROM files, you can find them in the file <a
href="http://www.emulators.com/freefile/pcxf380.zip" target="_blank"

View File

@ -1,6 +1,6 @@
<p>The following table lists all releases of WUDSN IDE, the required minimum Java and Eclipse version, the link to the
release news article, and the release news video. For releases before 1.6.0 no downloads and no videos are offered.
The latest stable version is always available via the update site "https://www.wudsn.com/update". The daily version
The latest stable version is always available via the update site "https://www.wudsn.com/update/stable". The daily version
and older versions are available via version-specific update sites listed below.</p>
<table>
<tbody>
@ -13,16 +13,6 @@
<th>Release News Article</th>
<th>Release News Video</th>
</tr>
<tr>
<td>stable</td>
<td>updated permanently</td>
<td>Java 11</td>
<td>4.19</td>
<td>https://www.wudsn.com/update</td>
<td><a href="https://atariage.com/forums/topic/145386-wudsn-ide-the-free-integrated-atari-8-bit-development-plugin-for-eclipse/"
target="_blank" rel="noopener noreferrer">read</a></td>
<td>n/a</td>
</tr>
<tr>
<td>daily</td>
<td>updated permanently</td>
@ -34,11 +24,11 @@
<td>n/a</td>
</tr>
<tr>
<td>1.7.2</td>
<td>1.7.2 (stable)</td>
<td>2021-04-01</td>
<td>Java 11</td>
<td>4.19</td>
<td>https://www.wudsn.com/update/1.7.2</td>
<td>https://www.wudsn.com/update/stable</td>
<td><a href="https://www.wudsn.com/index.php/191-wudsn-ide-update-1-7-2" target="_blank"
rel="noopener noreferrer">read</a></td>
<td>Planned</td>
@ -235,3 +225,18 @@
</tr>
</tbody>
</table>
<p>Before version 1.7.2, so-called "zero installation distributions" were been provided for Windows. They contain the Eclipse Platform, the Java Runtime Environment, the latest stable version of the WUDSN IDE plugin,
all supported compilers, and an emulator for each supported platform. All paths to folders, compilers, and emulators
are pre-configured. Unpack the content of this archive to the directory "C:\jac\wudsn" and click the "WUDSN IDE-64
bit" link. Eclipse will open with the predefined workspace that contains "Hello World" examples for different platforms.</p>
<ul>
<li>WUDSN IDE 1.7.1: <a href="https://www.wudsn.com/productions/java/ide/downloads/1.7.1/wudsn-ide-win64.zip"
target="_blank" rel="noopener noreferrer">Windows 64-bit version</a></li>
<li>WUDSN IDE 1.7.0: <a href="https://www.wudsn.com/productions/java/ide/downloads/1.7.0/wudsn-ide-win64.zip"
target="_blank" rel="noopener noreferrer">Windows 64-bit version</a>, <a
href="https://www.wudsn.com/productions/java/ide/downloads/1.7.0/wudsn-ide-win32.zip" target="_blank"
rel="noopener noreferrer">Windows 32-bit version</a></li>
<li>WUDSN IDE 1.6.6: <a href="https://www.wudsn.com/productions/java/ide/downloads/1.6.6/wudsn-ide-win64.zip"
target="_blank" rel="noopener noreferrer">Windows 64-bit version</a>, <a
href="https://www.wudsn.com/productions/java/ide/downloads/1.6.6/wudsn-ide-win32.zip" target="_blank"
rel="noopener noreferrer">Windows 32-bit version</a></li>