6502/wudsn-ide
1
0
Fork 0
mirror of https://github.com/peterdell/wudsn-ide.git synced 2024-12-21 18:29:40 +00:00
Code Issues Projects Releases Wiki Activity
0821d40ed7
wudsn-ide/com.wudsn.ide.lng/help/ide-features.section.html
Peter Dell 6472440284 Update documentation for "WUDSN_LANGUAGE".
2023-08-30 20:43:50 +02:00

547 lines
34 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<p>The latest version contains the following features:</p>
<ul>
<li><a href="#IDE">General IDE Enhancements</a></li>
<li><a href="#Editor">Fully Integrated Assembler Editor</a></li>
<li><a href="#ContentOutline">Content Outline and Source Folding</a></li>
<li><a href="#ContentAssistance">Content Assistance and Code Completion</a></li>
<li><a href="#Hyperlinks">Hyperlink Navigation</a></li>
<li><a href="#HexEditor">Hex Editor</a></li>
<li><a href="#GraphicsConversionEditor">Graphics Conversion Editor</a></li>
<li><a href="#PreferencesForEditing">Preferences for Editing</a></li>
<li><a href="#PreferenesForBuildingAndRunning">Preferences for Building and Running</a></li>
<li><a href="#AnnotationsForBuilding">Annotations for Building</a></li>
<li><a href="#PlannedFeatures">Planned Features</a></li>
<li><a href="#KnownBugs">Known Bugs</a></li>
</ul>
<h5 id="IDE">General IDE Enhancements</h5>
<ul>
<li>The environment variable "WUDSN_LANGUAGE" can be set to "en" or "de" to override the default locale of the IDE used for all menu and message texts.</li>
<li>The "Open Folder" context menu is available for all folders and files.</li>
<li>The "Sort" context menu with sub-menu is available for all text files, including <br />
<ul>
<li>Case-sensitive, case-insensitive, and numeric sorting</li>
<li>Sorting with and without removal of duplicates</li>
<li>Reverse ordering</li>
</ul>
<img src="productions/java/ide/features/ide-common-context-menu-open-folder.png" alt="Open folder action in context menu" /> <img src="productions/java/ide/features/ide-text-editor-context-menu.png" alt="Sort action in text editor context menu" /></li>
<li>The online help contains the "WUDSN IDE Guide" with the following multiple sections.
<ul>
<li>WUDSN IDE <br />This is the documentation from the website.
<ul>
<li>Video links to the tutorial and release news</li>
<li>Features</li>
<li>Installation</li>
<li>FQA</li>
<li>Link</li>
</ul>
</li>
<li>Assemblers<br />This is the information on the supported assemblers and their properties.
<ul>
<li>General<br />Links, syntax, and support features.</li>
<li>Instructions<br />All supported instructions, including their descriptions, are grouped by type.</li>
<li>Manual<br />Direct access to the PDF, HTML, or text manual files or files that are part of the installation.</li>
</ul>
</li>
<li>Hardware Platforms<br />The information on the supported hardware platforms and the corresponding emulators and links.
<ul>
<li>Reference documentation - Hardware-specific PDF, HTML, or text files with CPU and customer chips reference sheets and programming guides</li>
</ul>
</li>
</ul>
<br /><img src="productions/java/ide/features/ide-help.gif" alt="Integrated Help" /></li>
</ul>
<h5 id="Editor">Fully Integrated Assembler Editor</h5>
<ul>
<li>The Eclipse platform contains editors like, for example, the generic text editor. Editors can support one or more content types identified by file extensions. One editor can be the default for a specific file extension. WUDSN IDE provides an assembler editor and a corresponding content type for every compiler. Every assembler editor has an associated default compiler, which defines via the preferences which application is used to run the output file. <br /><img src="productions/java/ide/features/ide-editor-content-types.png" alt="IDE editors, content types and file associations" /></li>
<li>Content types and file associations for Atari 2600 compilers 
<ul>
<li>DASM Source File (*.asm)</li>
</ul>
</li>
<li>Content types and file associations for Atari 8-bit compilers
<ul>
<li>ATASM Source File (*.asm)</li>
<li>MADS Source File (*.asm, default)</li>
<li>XASM Source File (*.asx, default)</li>
</ul>
</li>
<li>Content types and file associations for C64 compilers
<ul>
<li>ACME Source File (*.a, default)</li>
</ul>
</li>
<li>New content types and file associations for NES compilers
<ul>
<li>ASM6 Source File (*.asm)</li>
</ul>
</li>
<li>The default editor for a file extension can be configured in the "File Associations" section of the preferences with the "Default " button.<br /><img src="productions/java/ide/features/ide-editor-file-associations.gif" alt="IDE file associations" /></li>
<li>Syntax highlighting provides colors and styles for comments, directives, different types of identifiers, legal opcodes, illegal opcodes, pseudo opcodes, and strings.</li>
<li>Single-line comments for the current line selection can be toggled using "CTRL-7" or the editor context menu entry "Toggle Comment".</li>
<li>Support for illegal opcodes of the 6502 CPU is configurable.</li>
<li>Support for 16-bit opcodes of the WDC 65816 CPU is configurable.</li>
<li>Built-in support for <a href="https://atari.miribilist.com/atasm" target="_blank" rel="noopener noreferrer">ATASM assembler</a>, <a href="https://mads.atari8.info" target="_blank" rel="noopener noreferrer">MADS assembler</a>, <a href="https://github.com/pfusik/xasm" target="_blank" rel="noopener noreferrer">XASM assembler</a>, <a href="https://sourceforge.net/projects/acme-crossass" target="_blank" rel="noopener noreferrer">ACME assembler</a></li>
<li>Built-in support for running compiler output files with the operating system default application without configuration effort</li>
<li>Built-in support for <a href="http://www.virtualdub.org/altirra.html" target="_blank" rel="noopener noreferrer">Altirra emulator</a>, <a href="https://github.com/Jaskier/Atari800Win-PLus/" target="_blank" rel="noopener noreferrer">Atari800Win emulator</a>, <a href="https://www.atarimac.com/atari800macx.php" target="_blank" rel="noopener noreferrer">Atari800MacX emulator</a>, <a href="http://www.xl-project.com" target="_blank" rel="noopener noreferrer">Atari++ emulator</a></li>
<li>Adding support for new compilers and applications is possible via Eclipse extension points.<br /><img src="productions/java/ide/features/ide-compiler-extensions.png" alt="IDE compiler extensions" /></li>
<li>Build or build and run with a single keystroke or via the menu.</li>
<li>Toolbar button for "Build and Run", which adapts to the hardware of the currently opened editor. For example, it will show a C64 icon when using the "ACME (C64)" editor.</li>
<li>The toolbar button for "Build and Run" offers a pulldown menu that allows running the output file with any of the applications configured in the preferences. You can run the output file quickly with different emulators without changing the preferences. That can be very helpful if one emulator shows another behavior or if you have specified a build script as a user-defined application in the preferences.<br /><img style="vertical-align: top;" src="productions/java/ide/features/ide-assembler-run-with-atari2600.png" alt="Run with... for Atari 2600" /> <img style="vertical-align: top;" src="productions/java/ide/features/ide-assembler-run-with-atari8.png" alt="Run with... for Atari 8-bit" /> <img style="vertical-align: top;" src="productions/java/ide/features/ide-assembler-run-with-c64.png" alt="Run with... for C64" /></li>
<li>The "Open Source Folder" and "Open Output Folder" entries the respective folder directly from the menu.</li>
<li>The "Language Help" entry opens the language-specific help from the menu if the documentation is available in the default folder structure of the assembler/compiler executable.<br />TODO: Note that the images below are outdated and must be updated.<br /><img src="productions/java/ide/features/ide-assembler-menu.png" alt="IDE assembler menu" /></li>
<li>The complete list of assembler/compiler errors and warning messages in the problems view.</li>
<li>Direct navigation to the source location is supported by double-clicking the problem message.</li>
<li>Problem markers in the scroll area, including the tooltip with the problem message.<br /><img src="productions/java/ide/features/ide-example-source.png" alt="IDE example source" /></li>
<li>German localization is available for all Eclipse plugin texts. The original compiler messages are not translated, but some are mapped automatically.<br />
<ul>
<li>ATASM ".bank" warnings are mapped to info messages.</li>
</ul>
</li>
<li>The console view with compiler output opens automatically in the background after compiling, which is helpful in cases where the plugin is incomplete. The "Console" window is automatically brought to the front when the assembler/compiler starts. This prevents the compiler output from being hidden behind other consoles in the console view.<br /><img src="productions/java/ide/features/ide-compiler-console.png" alt="IDE compiler console view" /></li>
</ul>
<h5 id="ContentOutline">Content Outline and Source Folding</h5>
<p>The content outline and the folder of source code sections are two of the most helpful features of WUDSN IDE. They help you navigate and manage even huge source files efficiently. The standard menu "Window / Show View / Outline" activates the content outline. Source folding requires the content outline to be active. The content outline has the following features.</p>
<ul>
<li>Nesting.</li>
<li>Type-specific icons.</li>
<li>Automated asynchronous parsing while typing.</li>
<li>Automated recursive parsing of source includes and merges with the current outline.</li>
<li>Positioning in the content outline remains stable while typing unless structure changes appear.</li>
<li>Outline is supported for
<ul>
<li>equate definitions (including equates from defining expression)</li>
<li>labels</li>
<li>and variable definitions</li>
<li>source includes</li>
<li>binary includes</li>
</ul>
</li>
<li>Outline and folding are supported for
<ul>
<li>definition section</li>
<li>implementation sections</li>
<li>enum definition</li>
<li>struct definitions</li>
<li>macro definitions</li>
<li>repeat sections</li>
<li>procedure definitions</li>
<li>local sections.</li>
</ul>
</li>
<li>The line-end comment is a short description in the outline.</li>
<li>The toolbar has a button to toggle the sorting order of the sections and labels. The state of the toggle button is persisted automatically along with the respective source file. The setting from the currently opened file will be used for files that do not have a value set yet.<br /><img src="productions/java/ide/features/ide-content-outline.gif" alt="IDE content outline" /></li>
<li>Folding is activated automatically when the outline is visible.</li>
<li>Folding is nested with a tooltip for folded sections.</li>
<li>Folding is supported for if/else/endif blocks. <br /><img src="productions/java/ide/features/ide-content-folding.gif" alt="IDE content folding" /></li>
</ul>
<h5 id="ContentAssistance">Content Assistance and Code Completion</h5>
<p>Content assistance provides proposals as you type and lets you enter code more efficiently. Content assistance is activated by pressing "CTRL-Space" or automatically by typing special characters. The content assistance has the following features.</p>
<ul>
<li>Content assistance for directives, legal, illegal, and pseudo-opcodes.</li>
<li>Recognizes if there is already an instruction in the current line and suggests the available identifiers instead if this is the case. It supports global identifiers in the active source file and source files included from there. </li>
<li>Completion proposal auto-activation without pressing "CTRL-Space" after typing compiler-dependent characters, for example, "." in ATASM, "." or "#" in MADS, and "!" in ACME</li>
<li>Type-specific icon and mnemonic highlighting.</li>
<li>Progressive filtering as you type.</li>
<li>Automatic detection of lower-case/upper-case based on current input.</li>
<li>Configurable default case (lower-case, upper-case) via preferences. <br /><img src="productions/java/ide/features/ide-content-assist.gif" alt="IDE content assist" /></li>
<li>Multi-line content completion and explicit cursor positioning, for example, ".MA" becomes "<code>.MACRO &lt;cursor is here&gt; &lt;newline&gt;.ENDM</code>".<br /><img src="productions/java/ide/features/ide-content-completion-instruction.gif" alt="Muli-line content completion and cursor positioning" /></li>
</ul>
<h5 id="Hyperlinks">Hyperlink Navigation</h5>
<p>The source code editor provides detection for different types of links in the source code. You can navigate to other parts of the file, other files, or websites via these links. You activate the hyperlink navigation by pressing "CTRL". The hyperlink navigation has the following features.</p>
<ul>
<li>Hyperlink navigation via CTRL-click to source includes and binary includes.</li>
<li>Support for relative and absolute file paths.</li>
<li>Source files are always opened with the same assembler editor, irrespective of the extension.</li>
<li>Missing file extensions for source include statements are appended automatically where possible.</li>
<li>Option for binary include statements opening the file with:
<ul>
<li>The built-in hex editor</li>
<li>The built-in graphics editor</li>
<li>The default Eclipse editor (e.g., a text editor)</li>
<li>The system editor (e.g., an emulator or a paint program)</li>
</ul>
</li>
<li>Hyperlink navigation via CTRL-click to labels equates, local definitions, macro definitions, and procedure definitions. In case there is only one target, direct navigation takes place. In case there is more than one possible target, the type and line number of the target are displayed in a hyperlink popup. All included source files are also considered, like in the content outline. If targets are from different files, the file name is also displayed as a differentiator in the hyperlink popup. <br /><br /><img src="productions/java/ide/features/ide-hyperlink-navigation-source.png" alt="IDE navigation to source file" /> <br /><img src="productions/java/ide/features/ide-hyperlink-navigation-binary.png" alt="IDE navigation to binary file" /> <br /><img src="productions/java/ide/features/ide-hyperlink-navigation-identifier.png" alt="IDE navigation to labels, equates, local definitions, macro definitions and procedure definitions" /></li>
</ul>
<h5 id="HexEditor">Hex Editor</h5>
<p>The Hex Editor allows inspection of arbitrary files on the binary level. It has the following features.</p>
<ul>
<li>It is available via the context menu, including a multi-file selection to open several files simultaneously.<br /><img src="productions/java/ide/features/ide-common-context-menu-open-with-hex-editor.png" alt="Open With Hex Editor" /></li>
<li>The "Open With Hex Editor" menu entry closes an existing editor in case the file is already opened, forcing the file to be opened with the hex editor. In addition, the hex editor is set as the default editor for this file. Consequently, double-clicking the file in the package explorer will open it automatically with the hex editor, no matter which file type. This saves you from always using the context menu just because the file has no known file type. Using the "Open With" context menu entry, you can change the default editor again.</li>
<li>It is available via hyperlink navigation for binary include statements.</li>
<li>The content offers a context menu to copy parts of the file into the clipboard in different formats:
<ul>
<li>hex values (".byte $01,$02,...")</li>
<li>decimal values (".byte 1,2,...")</li>
<li>ASCII string</li>
</ul>
This is very helpful to turn parts of a file into source code. The possibility to copy/paste into the binary file to modify is prepared but not working yet and will be completed later. <br /><img src="productions/java/ide/features/ide-hex-editor-context-menu.png" alt="Hex Editor context menu" /></li>
<li>It detects and supports the type of the file. For example, binary files, Atari COM files, Atari Disk Images, and several other file types.<br /><img src="productions/java/ide/features/ide-hex-editor-binary-file.png" alt="Hex Editor file mode selection" /></li>
<li>The possible file modes for a binary file are computed automatically and used as default when opening the file.</li>
<li>Unsupported file modes are detected and cannot be used.</li>
<li>Files with a block structure get an outline in the outline view.</li>
<li>Files with a corrupted block structure are detected and displayed as well as possible.<br /><img src="productions/java/ide/features/ide-hex-editor-outline.png" alt="Hex Editor outline view" /> <br /><img src="productions/java/ide/features/ide-hex-editor-atari-com-file.png" alt="Hex Editor with corrupted Atari COM file " /></li>
</ul>
<h5 id="GraphicsConversionEditor">Graphics Conversion Editor</h5>
<p>The Graphics Conversion Editor views and converts many binary and image file formats. It has the following features.</p>
<ul>
<li>Viewer for binary files and 8-bit image files. <br />The most suitable supported converter and the corresponding default parameters are computed based on the file content, size, and extension. <br />The converters for the Atari standard image formats are based on <a href="https://sourceforge.net/projects/recoil" target="_blank" rel="noopener noreferrer">RECOIL fka. FAIL</a> is the excellent First Atari Image Library created by Piotr Fusik and Adrian Matoga. <br />
<table class="standard_table">
<tbody>
<tr>
<th>Platform</th>
<th>File Extension</th>
<th>File Format</th>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>AP3</td>
<td>80x192, 256 colors, interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>APC</td>
<td>Any Point, Any Color, 80x96, 256 colors, interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>CHR</td>
<td>8x8 charset, mono or multi-color</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>CCI</td>
<td>Champions' Interlace, 160x192, compressed</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>CIN</td>
<td>Champions' Interlace, 160x192</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>CHG</td>
<td>Gephard Hires Graphics, up to 320x200, mono</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>CPR</td>
<td>Trzmiel, 320x192, mono, compressed</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>FNT</td>
<td>Standard 8x8 font, mono</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>GR8</td>
<td>Standard 320x192, mono</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>GR9</td>
<td>Standard 80x192, grayscale</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>HIP</td>
<td>Hard Interlace Picture, 160x200, grayscale</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>HR</td>
<td>Hires 256x239, three colors, interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>HR2</td>
<td>Hires 320x200, five colors, interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>ILC</td>
<td>APAC 80x192, 256 colors interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>INP</td>
<td>Interlace Picture 160x200, seven colors, interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>INT</td>
<td>INT95a, up to 160x239, 16 colors, interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>MCP</td>
<td>McPainter, 160x200, 16 colors, interlaced</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>MIC</td>
<td>Micropainter 160x192, 4 colors</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>PIC</td>
<td>Koala MicroIllustrator, 160x192, 4 colors, compressed</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>PLM</td>
<td>Plama 256, 80x96, 256 colors</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>RIP</td>
<td>Rocky Interlace Picture, up to 160x239</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>SXS</td>
<td>16x16 font, mono</td>
</tr>
<tr>
<td>Atari 8-bit</td>
<td>TIP</td>
<td>Taquart Interlace Picture, up to 160x119</td>
</tr>
<tr>
<td>C64</td>
<td>64C</td>
<td>Charset, mono or multi-color</td>
</tr>
<tr>
<td>C64</td>
<td>SPR</td>
<td>Sprite, mono or multi-color</td>
</tr>
</tbody>
</table>
</li>
<li>Viewer for GIF/JPG/BMP/PNG images.</li>
<li>Available via context menu including multi-file-selection to open several files simultaneously.<br />TODO: This is no longer the case. This part of the documentation must be tested and updated.<br /><img src="productions/java/ide/features/ide-common-context-menu-open-with-graphics-editor.png" alt="Open With Graphics Editor" /></li>
<li>The "Open With Graphics Editor" menu entry closes an existing editor in case the file is already opened, forcing the file to be opened with the graphics editor. In addition, the graphics editor is set as the default editor for this file. Consequently, double-clicking the file in the package explorer will open it automatically with the graphics editor, no matter which file type. This saves you from always using the context menu just because the file has no known file type. Using the "Open With" context menu entry, you can change the default editor again.</li>
<li>Available via hyperlink navigation for binary include statements.</li>
<li>Conversion from binary or 8-bit image files to GIF/JPG/BMP/PNG images.
<ul>
<li>Up to three source files, depending on the converter.</li>
<li>A configurable start offset for every source file helps extract character sets.</li>
<li>A configurable palette via the Image Palette view.</li>
<li>A configurable number of rows and columns.</li>
<li>Configurable spacing width and color to separate tiles and unused areas.</li>
<li>Separate aspect ratio for displaying and saving the image file.</li>
</ul>
<img src="productions/java/ide/features/ide-graphics-editor-files-to-image.gif" alt="Conversion from binary files or 8-bit images files to GIF/JPG/BMP/PNG images" /></li>
<li>Conversion from GIF/JPG/BMP/PNG images to binary files or 8-bit images using JavaScript.
<ul>
<li>Separate aspect ratio for loading and displaying the image file</li>
<li>Default scripts are included. They can be adjusted and saved along with the other parameters.</li>
</ul>
<br /><img src="productions/java/ide/features/ide-graphics-editor-image-to-files.gif" alt="Conversion from GIF/JPG/BMP/PNG images to binary files or 8-bit images files" /></li>
<li>The image palette view associated with the graphics editor displays the palette entries and the color histogram. It supports filtering unused colors, sorting by index and color frequencies, pre-settings, and editing the palette when displaying 8-bit images.<br /><img src="productions/java/ide/features/ide-graphics-editor-image-palette-view.gif" alt="Image palette view" /></li>
<li>Conversion files with the extension ".cnv" save the conversion direction and parameters.</li>
<li>Support for relative file paths. If the file path is in the same folder as the ".cnv" file, it is automatically converted to a relative file path when the file name is defaulted or picked from the file browser dialog. This allows us to move the ".cnv" and referenced source files together without breaking the saved paths.</li>
</ul>
<h5 id="PreferencesForEditing">Preferences for Editing</h5>
<p>The WUDSN IDE editor is configurable via language-specific preferences. They are a<span style="font-size: 1rem;">vailable via the entry "Preferences" from the menu "Window" (under Windows and Linux) or the menu "Eclipse" (under macOS) and include the following.</span></p>
<ul>
<li>Configuration of syntax highlighting colors and styles for comments, directives, all types of identifiers, legal opcodes, illegal opcodes, numbers, pseudo opcodes, and strings.</li>
<li>For non-unique identifiers, the syntax highlighting will try to be the best guess.</li>
<li>Configuration of default case in content assistance.<br /><img src="productions/java/ide/features/ide-assembler-preferences-editor.png" alt="Preferences for compilers" /></li>
</ul>
<h5 id="PreferenesForBuildingAndRunning">Preferences for Building and Running</h5>
<p>The build process of WUDSN IDE is configurable via language and assembler/compiler-specific preferences. They are available via the entry "Preferences" from the menu "Window" (under Windows and Linux) or the menu "Eclipse" (under macOS)</p>
<ul>
<li>Download links, configurable paths, and default parameters are provided for all assemblers and compilers.</li>
<li>The path to the downloaded executable file can be configured in the language preferences once for all target platforms.</li>
<li>If no path is configured, WUDSN IDE will look for the executable file in the "Tools" folder of the installation.</li>
<li>The default file extension filter for selecting executable files is "*.exe" on Windows and "*.*" on all other operating systems.</li>
<li>The "Apply Defaults" button explicitly does not reset the paths to the executable files.</li>
<li>Building preferences can be maintained for all assemblers/compilers where an executable file is configured.</li>
<li>The active editor's language and assembler/compiler tabs are activated automatically upon opening the language preferences.</li>
<li>Via the "Target" option, you can activate the support for illegal opcodes of the 6502 CPU and 16-bit opcodes of the WDC 65816 CPU in syntax highlighting and content assistance.<br />The selection is offered only if the assembler supports the respective feature.</li>
<li>Build parameters can be specified per assembler/compiler. If no explicit values are specified, predefined defaults to run out-of-the-box are displayed and used.</li>
<li>Variables provide access to the project or file-specific paths in parameters:
<ul>
<li>{$sourceFolderPath}<br />The absolute path to the source folder.</li>
<li>{$sourceFilePath}<br />The absolute path to the source file.</li>
<li>{$outputFolderPath}<br />The absolute path to the output folder.</li>
<li>{$outputFilePath}<br />The absolute path to the output file.</li>
<li>{$outputFileName}<br />The name of the output file, including its extension, for example, "TestFile123.asm".</li>
<li>{$outputFileNameWithoutExtension}<br />The name of the output file without an extension, for example, "TestFile123".</li>
<li>{$outputFileNameShortWithoutExtension}<br />The name of the output file without extension is shortened to 8 alphanumeric characters, for example, "TESTFILE".</li>
</ul>
Make sure that you don't remove parameters when you specify your values.<br />If not, creating the label definition file or parsing the compiler log may fail.
<ul>
<li>ATASM requires the "-s" parameter to be present".</li>
<li>MADS requires the "-p" parameter to be present.</li>
<li>ACME requires the "!to" directive in the source to be commented out to ensure the output file name from the command line is used.</li>
</ul>
</li>
</ul>
<p>In addition, the application to run the outcome of the build process, typically an emulator, can be configured. Download links for every supported application are offered in the preferences.</p>
<ul>
<li>The path to the downloaded application executable file can be configured in the language preferences once for all target platforms.</li>
<li>If no path is configured, WUDSN IDE will look for the executable file in the "Tools" folder of the installation.</li>
<li>The default file extension filter for selecting executable files is "*.exe" on Windows and "*.*" on all other operating systems.</li>
</ul>
<p>The preferences for the applications to run the result of the build process can be maintained for all assemblers/compilers in parallel. They include:</p>
<ul>
<li>Selection of the application to run the outcome of the build process:
<ul>
<li>Use the "Operating System Default Application" of the platform.<br />For Windows and macOS, choosing the "Operating System Default Application" means that for the ".xex" file extension, the emulator will be started automatically without any further configuration.</li>
<li>Use one of the predefined applications and optionally change the command line.</li>
<li>Use a user-defined application to open the output file.</li>
</ul>
</li>
<li>Run parameters per assembler/compiler and application can be specified. If no explicit values are specified, predefined defaults to run out-of-the-box are displayed and used.</li>
<li>Variables provide access to the project or file-specific paths in parameters:
<ul>
<li>{$runnerExecutablePath}<br />The absolute path to the executable of the application.</li>
<li>{$sourceFolderPath}<br />The absolute path to the source folder.</li>
<li>{$sourceFilePath}<br />The absolute path to the source file.</li>
<li>{$outputFolderPath}<br />The absolute path to the output folder.</li>
<li>{$outputFilePath}<br />The absolute path to the output file.</li>
<li>{$outputFileName}<br />The name of the output file, including its extension, for example, "TestFile123.asm".</li>
<li>{$outputFileNameWithoutExtension}<br />The name of the output file without an extension, for example, "TestFile123".</li>
<li>{$outputFileNameShortWithoutExtension}<br />The name of the output file without extension is shortened to 8 alphanumeric characters, for example, "TESTFILE".<br />TODO: Note that the images below are outdated and must be updated.<br /><img src="productions/java/ide/features/ide-assembler-preferences-compilers.gif" alt="Preferences for compilers" /></li>
</ul>
</li>
</ul>
<h5 id="AnnotationsForBuilding">Annotations for Building</h5>
<ul>
<li>For most use cases, the defaults provided for the compilers and in the preferences are sufficient. But suppose you want to develop in parallel in multiple projects for different platforms (e.g., Apple II and Atari 8-bit) or various output formats (".XEX" and ".BIN") with the same assembler/compiler. In that case, changing the preferences every time may become cumbersome. Therefore, WUDSN IDE offers annotations to put into the source code files. These annotations override the defaults and the settings from the preferences.</li>
<li>All language annotations start with the prefix "@com.wudsn.ide.lng." followed by the lower-case name of the annotation, an equals sign, and the unquoted value. Example: "@com.wudsn.ide.lng.hardware=ATARI8BIT"</li>
<li>In earlier versions of WUDSN, language annotations started with the prefix "@com.wudsn.ide.asm.". While they are still evaluated, adapting to the new prefix is strongly recommended.</li>
<li>All annotations can be placed in comment lines at the beginning of a source file. Some annotations are only relevant for the main source file. Some are only relevant in include source files. Some are relevant for all source files.</li>
<li>@com.wudsn.ide.lng.hardware
<ul>
<li>Defines the target hardware for which the preferences shall be evaluated, mainly which emulator runs the output file.</li>
<li>Allowed values are "APPLE2", "ATARI2600", "ATARI7800", "ATARI8BIT", "C64", "NES".</li>
<li>This annotation is relevant for all source files.</li>
<li>This annotation is only evaluated when a file is opened. So, if you add this annotation or change its value, you must close and re-open the file once.</li>
<li>Example: @com.wudsn.ide.lng.hardware=ATARI8BIT</li>
</ul>
</li>
<li>@com.wudsn.ide.lng.mainsourcefile
<ul>
<li>Defines the main source file to which the current source file belongs. When executing the "Compile" action, the primary source file is compiled instead of the active file.</li>
<li>Allowed values are file paths relative to the current folder, including source file and absolute file paths.</li>
<li>This annotation is only relevant in include source files.</li>
<li>Example: @com.wudsn.ide.lng.mainsourcefile=ExampleMain.asm</li>
</ul>
</li>
<li>@com.wudsn.ide.lng.outputfoldermode
<ul>
<li>Overrides the "Output Folder Mode" from the preferences.</li>
<li>Allowed values are "SOURCE_FOLDER", "TEMP_FOLDER", and "FIXED_FOLDER".</li>
<li>This annotation is only relevant in the main source file.</li>
<li>Example: @com.wudsn.ide.lng.outputfoldermode=SOURCE_FOLDER</li>
</ul>
</li>
<li>@com.wudsn.ide.lng.outputfolder
<ul>
<li>Overrides the "Output Folder" from the preferences and the "@com.wudsn.ide.lng.outputfoldermode" annotation.</li>
<li>Allowed values are file paths relative to the folder of the main source file and absolute file paths.</li>
<li>This annotation is only relevant in the main source file.</li>
<li>Example: @com.wudsn.ide.lng.outputfolder=..\out</li>
</ul>
</li>
<li>@com.wudsn.ide.lng.outputfileextension
<ul>
<li>Overrides the "Output File Extension" from the preferences.</li>
<li>Allowed values have to start with a period.</li>
<li>This annotation is only relevant in the main source file.</li>
<li>Example: @com.wudsn.ide.lng.outputfileextension=.bin</li>
</ul>
</li>
<li>@com.wudsn.ide.lng.outputfile
<ul>
<li>Overrides the "Output Folder" and "Output File Extension" values from the preferences and the automatic computation of the out file name based on the primary source file name.</li>
<li>Allowed values are file paths relative to the folder of the primary source file and absolute file paths.</li>
<li>This annotation is only relevant in the main source file.</li>
<li>Example: @com.wudsn.ide.lng.outputfile=..\out\output.bin</li>
</ul>
</li>
</ul>
<h5 id="PlannedFeatures">Planned Features</h5>
<ul>
<li>Planned features are listed as issues of category "enhancement" on <a href="https://github.com/wudsn/wudsn-ide/issues" target="_blank" rel="noopener">GitHub</a>. There, you can also request new features.</li>
<li>The table below shows the current core feature set that depends on the compiler. <br />Features not supported by the compiler itself and hence cannot be supported by the IDE are marked as "n/a". <br />
<table>
<tbody>
<tr>
<th>Compiler</th>
<th>Default Hardware</th>
<th>Auto-Completion Activation</th>
<th>Single-Line Comments</th>
<th>Block Comments</th>
<th>Strings</th>
<th>Opcodes</th>
<th>Directives</th>
<th>Compile Log Parsing</th>
<th>Content Outline</th>
<th>Label Definition File Format</th>
</tr>
<tr>
<td>ACME</td>
<td>C64</td>
<td>Yes: !</td>
<td>Yes: ;|</td>
<td>n/a</td>
<td>Yes: "</td>
<td>Yes</td>
<td><i>Partly</i></td>
<td>Yes</td>
<td><i>Partly</i></td>
<td>ACME</td>
</tr>
<tr>
<td>ATASM</td>
<td>Atari 8-bit</td>
<td>Yes: .</td>
<td>Yes: ;</td>
<td>n/a</td>
<td>Yes: "</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>XASM 3.0.1</td>
</tr>
<tr>
<td>MADS</td>
<td>Atari 8-bit</td>
<td>Yes: . #</td>
<td>Yes: ; * //</td>
<td>Yes</td>
<td>Yes: ' "</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>MADS</td>
</tr>
<tr>
<td>XASM</td>
<td>Atari 8-bit</td>
<td>n/a</td>
<td>Yes: ; * |</td>
<td>n/a</td>
<td>Yes: ' "</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>XASM 3.0.1</td>
</tr>
</tbody>
</table>
<h5 id="KnownBugs"></h5>
</li>
</ul>
<h5 id="KnownBugs">Known Bugs</h5>
<p>You can find all known bugs on <a href="https://github.com/peterdell/wudsn-ide/issues" target="_blank" rel="noopener">GitHub</a>. If you find new bugs, please report them on Github or contact me directly.</p>
Reference in New Issue View Git Blame Copy Permalink