From b80e4141b6b897cfe1869f8419fb6bf5726b4e66 Mon Sep 17 00:00:00 2001 From: Peter Dell Date: Sun, 27 Aug 2023 14:49:19 +0200 Subject: [PATCH] Update HTML documentation --- .../help/ide-credits.section.html | 323 ++-- com.wudsn.ide.lng/help/ide-faq.section.html | 767 +++----- .../help/ide-features.section.html | 1648 +++++++---------- .../help/ide-installation.section.html | 489 ++--- .../help/ide-releases.section.html | 467 ++--- .../help/ide-tutorials-videos.html | 2 +- .../help/ide-tutorials.section.html | 169 +- .../src/com/wudsn/ide/lng/Texts.properties | 4 +- .../src/com/wudsn/ide/lng/Texts_de.properties | 2 +- 9 files changed, 1381 insertions(+), 2490 deletions(-) diff --git a/com.wudsn.ide.lng/help/ide-credits.section.html b/com.wudsn.ide.lng/help/ide-credits.section.html index 15453fe4..c4424d9b 100644 --- a/com.wudsn.ide.lng/help/ide-credits.section.html +++ b/com.wudsn.ide.lng/help/ide-credits.section.html @@ -1,180 +1,147 @@ -

A project like WUDSN IDE is not possible and not worth anything - without the contributions provided by others. So here's the list of - credits of all involved people and related projects.

+

A project like WUDSN IDE is not possible and not worth anything without the contributions provided by others. So here's the list of credits of all involved people and related projects.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Aseembler / CompilerContributor
ACMEMarco Baye (Mac Bacon), Krzysztof Dabrowski (BruSH/ElysiuM)
ATASMM. Schmelzenbach (schmelze)
DASMMatthew Dillon, Olaf Seibert (Rhialto), Andrew Davie, Peter - H. Froehlich (pfh), the DASM team
KickAssMads Nielsen (Slammer)
MADS and Mad PascalTomasz Biela (tebe)
XASMPiotr Fusik (fox)
Linux compilingCarsten Strohmann (cas)
Mac OS X compilingSpookt
Graphic Library or ToolContributor
RECOILPiotr Fusik (fox)
Grafx2Adrien Destugues (PulkoMandy), Yves Rizoud (yrizoud)
  
Sound LibraryContributor
ASAPPiotr Fusik (fox)
JSIDPLAY2Ken Händel (kenchis)
File system libraryContributor
AppleCommanderRobert Greene (robgreene)
  
EmulatorContributor
AppleWin (Apple II)Nick Westgate (sicklittlemonkey)
Altirra (Atari 8-bit)Avery Lee (phaeron)
Atari800Win (Atari - 8-bit)Marcin Lewandowski (jaskier)
CCS64 (C64)Håkan Sundell (phs)
JACE (Apple II)Brendan Robert (BLuRry)
Stella (Atari VCS)Stephen Anthony, Bradford Mott, Eckhard Stolberg, Brian - Watson
Virtu (Apple II)Sean Fausett (fool), Nick Westgate (sicklittlemonkey)
Eclipse plugin or libraryContributor
EclipseEclipse Foundation
x86 ASM PluginAndy Reek, Daniel Mitte
Rhino JavaScript engineMozilla Foundation
Eclipse Hex Editor Plugin (used as - inspiration)Marcel Palko (randallco)
Java Hex Editor & - PluginPordi Estaqual (pestatije)
Java - Expression Language ParserAaron Gadberry (aaron)
Aseembler / CompilerContributor
ACMEMarco Baye (Mac Bacon), Krzysztof Dabrowski (BruSH/ElysiuM)
ATASMM. Schmelzenbach (schmelze)
DASMMatthew Dillon, Olaf Seibert (Rhialto), Andrew Davie, Peter H. Froehlich (pfh), the DASM team
KickAssMads Nielsen (Slammer)
MADS and Mad PascalTomasz Biela (tebe)
XASMPiotr Fusik (fox)
Linux compilingCarsten Strohmann (cas)
Mac OS X compilingSpookt
Graphic Library or ToolContributor
RECOILPiotr Fusik (fox)
Grafx2Adrien Destugues (PulkoMandy), Yves Rizoud (yrizoud)
  
Sound LibraryContributor
ASAPPiotr Fusik (fox)
JSIDPLAY2Ken Händel (kenchis)
File system libraryContributor
AppleCommanderRobert Greene (robgreene)
  
EmulatorContributor
AppleWin (Apple II)Nick Westgate (sicklittlemonkey)
Altirra (Atari 8-bit)Avery Lee (phaeron)
Atari800Win (Atari 8-bit)Marcin Lewandowski (jaskier)
CCS64 (C64)Håkan Sundell (phs)
JACE (Apple II)Brendan Robert (BLuRry)
Stella (Atari VCS)Stephen Anthony, Bradford Mott, Eckhard Stolberg, Brian Watson
Virtu (Apple II)Sean Fausett (fool), Nick Westgate (sicklittlemonkey)
Eclipse plugin or libraryContributor
EclipseEclipse Foundation
x86 ASM PluginAndy Reek, Daniel Mitte
Rhino JavaScript engineMozilla Foundation
Eclipse Hex Editor Plugin (used as inspiration)Marcel Palko (randallco)
Java Hex Editor & PluginPordi Estaqual (pestatije)
Java Expression Language ParserAaron Gadberry (aaron)
\ No newline at end of file diff --git a/com.wudsn.ide.lng/help/ide-faq.section.html b/com.wudsn.ide.lng/help/ide-faq.section.html index 0962f3c1..90918e10 100644 --- a/com.wudsn.ide.lng/help/ide-faq.section.html +++ b/com.wudsn.ide.lng/help/ide-faq.section.html @@ -1,557 +1,218 @@ -

Here, you can find the answers to frequently asked questions. If - your question is unanswered, please review the video tutorials or - contact me.

+

Here, you can find the answers to frequently asked questions. If your question is unanswered, please review the video tutorials or contact me.

Installation

-

How do I install Java?

-

- I recommend you visit OpenJDK - and follow the instructions to download and install the latest - version. Make sure the Java version, the Eclipse version, and your - operating system have the same architecture. Newer versions of Java - only support 64-bit architectures. -

-
-

Nothing happens When I try to start a .jar file via - double-click. What is wrong?

-

You probably have the wrong Java version installed or set a - default. Open a shell window and enter "java -jar - <yourfile.jar>". If this works, then you have the wrong program - or Java version associated with the ".jar" file extension in the - registry. You can fix that by setting the path to the correct Java - installation folder using "REGEDIT.EXE" for - "Compute\HKEY_CLASSES_ROOT\jarfile\shell\open".

-

- Java jar file registry entry -

-

If starting from the command line does not work, you should see - a more detailed error message about why.

-
-
-

How do I install Eclipse?

-

- If you are unfamiliar with Eclipse, ensure you have installed the Eclipse - platform distribution without Java or J2EE tools. This distribution - is much smaller (typically around 60-80 MB instead of 170 MB) and - will not confuse you with many features and buttons you do not need. - See the "Installing Eclipse" section for the required steps on the " - Installation " tab. If you use Windows, you can use one of the zero - installation distributions of WUDSN IDE, which are linked on the tab - "Installation". They are ".zip" archives containing Eclipse and - everything else." -

-
-
-

When I try to start Eclipse, I get an error like "Failed to - load the JNI shared library 'C:\Program Files - (x86)\Java\jre6\bin\client\jvm.dll'". What is wrong?

-

The Eclipse version and the Java version on your system are not - compatible. The Eclipse is not pure Java but uses platform-specific - native libraries to run and debug Java efficiently. For example, you - must install the 64-bit version of Java (JRE or JDK) if you want to - use the 64-bit version of Eclipse. This is a frequent issue under - Windows 7 because, by default, only the 32-bit version of Java is - installed. See the "Installing Eclipse" section for the required - steps on the " Installation " tab.

-
-
-

How do I use Eclipse at?

-

Start the built-in help of Eclipse via the "Help/Help Content" - menu and read the "Workbench User Guide" section.

- Workbench user guide -
-
-

Why is WUDSN IDE not available via the update site?

-

You likely typed in the wrong update site URL, for example, - using "wusdn" instead of "wudsn". The correct URL is - "http://www.wudsn.com/update". In addition, you should uncheck the - checkbox "Hide items that are already installed" to see what is - there. See the "Installing WUDSN IDE" section for the required steps - on the " Installation " tab.

- Installation dialog with update site -
-
-

Why do I get "Unable to read repository at ... Read timed - out" when accessing the update site?

-

This error message indicates the Eclipse program is somehow - blocked from accessing the site. If you are behind a proxy server, - check the general proxy server settings in the Eclipse preferences. - If you use a firewall or internet security tool, make sure - "Eclipse.exe", "java.exe", "javaw.exe," or the corresponding program - on your host platform are allowed to cannot to the internet. Maybe - you have to change the settings so you are prompted to allow access - interactively.

-
-
-

Why do I get "Cannot complete the install because one or more - required items could not be found" when updating the plugin from the - update site?

-

- This error message indicates that the Eclipse version you are running - is too old. Check the releases page for the - required minimum Eclipse version for every WUDSN IDE release. -

-
-
-

Why is the "Assembler" section not visible in the - preferences?

-

- If the WUDSN IDE sections and features are not visible after a - successful installation, you probably use an outdated Java version. - For example, Java 1.6 has been out of maintenance - since 2013/02. This seems to be a common problem on Mac OS X, even - in Mavericks (10.9), which still uses Java 1.6 by default. Ensure you - have at least the Java version mentioned in the installation section - for the IDE installed and that Eclipse has started using that - version. -

-
-

Configuration

-
-

Why do I see wrong messages in the "Problems" view?

-

The default configuration of the "Problems" view shows all - errors from all files in the current project. While this is a good - default for Java programming, it is unsuitable for compiling single - independent assembler files. Therefore, you have to configure the - "Problems" view accordingly. See the "Installing Eclipse" section for - the required steps on the " Installation " tab.

-
-
-

How do I associate my source file extensions with the correct - editor?

-

- The IDE supports many different compilers and provides a specialized - editor for each. Typically, you have some preferred source file - extension (".asm" or ".a") and a preferred compiler. The procedure to - associate the file extension with the editor via the preferences is - described in this video tutorial WUDSN IDE - Tutorial 3: Setting up Editors and File Extensions correctly. -

-
-
-

Why must I put ";@com.wudsn.ide.lng.hardware=..." in the - source file?

-

The association with the file extension with your compiler's - editor (done in the preferences; see before) does not determine which - platform you want to create output. Therefore, this additional - annotation in the main source file must tell the IDE, which is the - target platform. It is used to find the correct compiler and emulator - settings, which can differ per platform. Every compiler has a default - platform (see the online help in the IDE), but it can also be used on - every other platform. Therefore, you must specify the target platform - in the main source file if you use a non-default platform.

-
-

Editing

-
-

Why is editing sometimes slow, or is everything blocked, - showing the wait cursor?

-

The core of WUDSN IDE uses the Eclipse Platform Runtime only - and does not require any additional plugins. It starts quickly and - dashes with that configuration, and I use it daily. So, if you - experience performance problems, try to download and run the zero - installation distribution of WUDSN IDE. Performance problems are very - likely caused by additional plugins or themes installed. Often, these - plugins are not only slow but broken. Check the ".metadata/.log" file - in the workspace folder. In some Eclipse versions, this is available - via "Window/Show View.../Error Log".

-
-
-

Is there support for source version control?

-

Yes, several plugins are available to connect Eclipse to CVS or - subversion. Also, the "Local History" feature is installed by - default. You can configure it in the preferences. It automatically - records all changes to the source file and lets you compare versions - in place.

- Source version control -
-
-

Is there support for a block selection mode?

-

Yes, a toolbar button and the shortcut "ALT+SHIFT+A" to toggle - block selection mode in all text editors. This can be useful for - adding and removing common prefixes such as line numbers.

- Toggle block selection mode -

If the toolbar button is not visible, you have to set it to - visible via the menu entry "Customize Perspective" in the context - menu of the main toolbar. In the customizing dialog, you must - activate the "Editor Presentation" command group and the toolbar - entries you want to see.

- Toggle block selection mode -
-
-

Why does "CTRL-Space" not open content assist?

-

There is a known keyboard assignment conflict when using - Messenger Plus Live! v4.85.0.386 with Microsoft Messenger 2009 on - Windows 7 Ultimate. This may also occur in other versions, of course. - Justin Payne has provided the following description of the solution.

-
    -
  1. Startup and log into MS Messenger.
    2. -
  2. From the main window, hit the ALT key to bring up the main - menu and select "Plus! | Preferences & Options".
    3. -
  3. From the Preferences windows, Select the Messenger tab and - uncheck "Activate Messenger Lock with a system-wide shortcut" OR - change the value in its text box to something other than "CTRL + - Space".
    4. -
  4. Press the "OK" button.
    5. -
-
-

Why do CTRL-SHIFT-0/9 and other key combinations not work?

-

You probably have another program outside of Eclipse that has - already captured these keys or key combinations. A frequent problem - is the Windows Input Methods Editor (IME), which is used to switch - keyboard layouts. For example, if you use multiple keyboard layouts, - the CTRL-Space is mapped to allow you to cycle between the different - keyboard regional keyboard layouts. You should be aware of how to - turn the feature off since you're probably using this feature, but - if you don't...

-

Windows 7

-
    -
  1. Within "Windows Control Panel", open "Region and Settings".
    2. -
  2. Select the "Keyboard and Languages" tab and "Change - Keyboards...".
    3. -
  3. In the "Text Services and Input Languages" windows, select - "Advanced Key Settings".
    4. -
  4. In the "Hot Keys for input languages" list box, select - "Between input languages" and then select "Change Key Sequence..."
    5. -
  5. In the "Change Key Sequence" window, choose another radio - button other than the one next to CTRL+Shift. At best, you choose - "(None)".
    6. -
  6. Click OK until you close all popup windows.
    7. -
-

Windows 10

-
    -
  1. Open "Control Panel\Clock, Language, and - Region\Language\Advanced settings.
    2. -
  2. Click the "Change Language bar hot keys".
    3. -
  3. Set all key sequences to "(None)".
    4. -
  4. Click OK until you close all popup windows.
    5. -
-

- Of course, this is Windows 7/10, and we know how Microsoft loves to - change its layouts and names, but this option is available back to - Windows XP.
Configure Windows IME hot keys -

-
-

Compiling

-
-

Why is MADS the primary compiler?

-

When I started with WUDSN IDE, ATASM was the first supported - compiler. The reason was simple: 90% of my sources are in ATASM - format. ATASM is very comprehensive and fast. Its capabilities to - define constants and byte sequences are extensive (".BYTE", ".WORD", - ".DBYTE", ".FLOAT", ".SBYTE" for ATASCII, ".CBYTE" for terminated - strings, separate offset for all constants). Over time, additional - platform compilers have been added, and their support will be - completed step by step. When the support for MADS was relatively - complete, I found it the most powerful compiler I have ever seen and - used. The support for ".PROC/.ENDPROC" has revolutionized how I - write assembler code. It allows logical structuring and visibility - control without any runtime overhead. At the same time, MADS is - compatible with MAC/65 and XASM, and even ATASM sources can be - adapted to MADS with a few minor changes described below. Therefore, - MADS has been the primary compiler since WUDSN IDE version 1.6.0.

-
-
-

Why do I get the error "No ORG defined" when compiling the - example from the tutorial?

-

Since WUDSN IDE version 1.6.0 MADS is the primary compiler - registered for the file extensions ".asm" upon installation. You are - trying to run the code example for version 1.5.0 or before, which is - in ATASM format. Therefore, you can either.

- -
-
-

Why are the errors and warnings from an included file - assigned to the primary source file in the problems view?

-

You use a case-insensitive file system and have used different - upper or lower-case writing in the statement than in the actual file - system. For example, you have written "ICL 'example.asm'" for a file - named "Example.asm" on the file system. In Eclipse, the file names - of all resources are treated as case-sensitive, even if the - underlying file system is case-insensitive. Therefore, the file name - issued by the compiler will not match the file name. The IDE assigns - the error message to the primary source file as a fallback. To fix - this, you must adapt the spelling of the file name in the source - include statement.

-
-
-

How do I convert from ATASM format to MADS format?

-

Because both ATASM's and MADS's syntax are based on the MAC/65 - syntax. There are not many differences. Therefore, manual conversion - using "Find/Replace (CTRL-F)" is easy.

-
    -
  • Replace the origin definition "* = address" with "ORG - address".
    • -
  • Replace ".INCLUDE" with "ICL" for source includes.
    • -
  • Replace ".INCBIN" with "INS" for binary includes.
    • -
  • Replace "* = $2E0; .WORD address" with "RUN address" to - specify the run address.
    • -
  • Replace "* = $2E2; .WORD address" with "INI address" to - specify the initialization address.
    • -
  • Check the quotes of ".BYTE" and "DTA" statements. In MADS, - single quotes result in ASCII codes and double quotes in ATARI - screen codes.
    • -
  • Remove all ".BANK" statements. While ATASM sorts and merges - all segments within one bank statement, MADS uses the order of - segments defined in the source file. Every "ORG" statement - automatically generates a new file segment.
    • -
-
-
-

How does ATASM generate segments in executable files?

-

A helpful feature for small projects is that, by default, - ATASM sorts the segments by address and warns if the same address is - overwritten by code or data. Since version 1.05, the ".BANK" - directive is available, which allows you to create COM files with - "INITAD" segments and arbitrary segment counts. If you don't use the - ".BANK" directive, ATASM will sort the segments by their address and - put consecutive blocks into a single segment by default. While this - saves some bytes, it might be unclear if you are used to other - assemblers. Note that you must use the ".SET 6" directive to set the - assembler origin offset in every bank if you use it in one of the - banks.

-
- ; Bank 0
.bank
.set 6,0
* = $8000
start - lda #0
jmp *

; Bank 1
.bank .set 6,0
* - = $2e0
.word start;

; Bank 2
.bank
.set - 6,$4300-$C000
* = $C000
lda #1
sta label+1
label - lda #2
jmp * -
-
-
-

How do I compile into ROM images?

-

Plain ROM Images do not have header bytes by default, or at - least they do not have the same header bytes as executable files. - Compiler-specific options must be used to create raw object files - without headers. Some cases are listed below. See the manual of the - specific compiler for more details.

-
    -
  • ACME: Use the compiler parameter " -f plain " - instead of "-f cbm" (default) to switch to "plain" mode without a - header -
    • -
  • ATASM: Extend the compiler parameter "-o${outputFilePath}" - to " -r -o${outputFilePath}" to switch to "raw" mode without - header -
    • -
  • MADS: Use " OPT h-f+ " at the very beginning of the - source file to turn off the COM header and enable "fill" mode, - i.e., no segments are created if there are gaps in the object code -
    • -
-
-
-

How do I compile into disk images?

-
Atari 8-bit
-

- For Atari 8-bit, the ATASM compiler has a dedicated parameter to - write the executable file directly into ".ATR" or ".XFD" disk - images. The disk image must be formatted with Atari DOS 2.0S, DOS - 2.5, or a compatible DOS. All Atari 8-bit disk formats can be - created using the "dir2atr.exe" tool of the AtariSIO tools by Matthias Reichl - (hias). The command line tool can create a complete disk image with - arbitrary DOS (Atari DOS 2.5, MyDos, SpartaDOS) and size based on a - folder that contains "DOS.SYS", "DUP.SYS" (or the equivalent files - of the respective DOS) and all other files requires. I have packaged - an example, including the "dir2atr" tool, a batch script to call the - command line tool and emulator, and this archive's "files" folder. - Unpack the archive to your output folder. Double-click - "makefile.bat" to see how the disk image is created and started. - Read the section "How to run a - makefile script instead of an emulator?" for the details on - configuring the call to "makefile.bat". For productive usage, you - should put the "hias" folder into a central location and use the - most recent version from Matthias Reichl's website. For MacOS X - users, the download also contains a "makefile.sh" script and MacOS X - binaries of Matthias Reichl's tools. The binaries have been provided - by Fredrick Holst (freetz), and you can find the latest versions on - his website. -

-
Apple II
-

- For Apple II, WUDSN IDE automatically generates a bootable AppleDos - 3.3 disk image with the extension ".dsk" if one of the predefined - emulators is used for execution. If you want to use another DOS or - disk size or if you're going to put more files onto the disk after - compilation, you can use the command line version of AppleCommander to - achieve this. Create and configure a makefile script as described in - "How to run a makefile script instead - of an emulator?". In the case of Apple Disk images, always remember - to use the correct file content/load/run address. The IDE needs to - know the load address of an executable file to store this - information in the directory entry. The IDE evaluates the file - extension to detect the load address from the executable file. - Supported extensions are ".b", ".prg," and ".xex". Here's the logic - for the built-in disk image creation: -

-
    -
  • File extension ".b"
    // AppleDos 3.3 binary file: - start-lo, start-hi, length-lo, length-hi, data
    address = - getWord(outputFileContent, 0);length = length - 4;content = - getData(outputFileContent, 4); -
    • -
  • File extension ".prg" and length > 2
    // C64 - program file: start-lo, start-hi, data
    address = - getWord(outputFileContent, 0);length = length - 2;content = - getData(outputFileContent, 2); -
    • -
  • File extension ".xex" and length > 6 and - (getWord(outputFileContent, 0) & 0xffff) == 0xffff)
    // - AtariDOS 2.5 binary file:$ff, $ff, start-lo, start-hi, end-lo, - end-hi, data
    address = getWord(outputFileContent, 2);length - = length - 6;content = getData(outputFileContent, 6); -
    • -
-
Other hardware
-

- If you find a tool similar to "dir2atr.exe" for the Atari 8-bit or - "AppleCommander" for the Apple II, you can create your script and - run it as described in "How to run a - makefile script instead of an emulator?". -

-
-
-

How can I run a makefile or script instead of an emulator?

-

- Sometimes, running a makefile script instead of the emulator is - helpful, for example, if the output file is combined with other - files into a single ATR file. To execute such a script, select "User - Defined Application" as the "Default Application to open Output - File". Specify the path to the shell as "Path to Application". On - the command line, you can then use the standard variables to start - the command shell and pass the script's name and the file path of - the compiled output file. Since the working directory during - execution is the compiler's output folder, you must place the script - file there or specify the script file with its absolute path. If you - are using Windows and "cmd.exe" as your shell, you must add "/c" - before the name of the script to prevent "cmd.exe" from remaining as - a process after the script has finished. The resulting command line - is "${runnerExecutablePath} /c makefile.bat ${outputFilePath}", - assuming "makefile.bat" is located in the output folder". See - section "How do I compile into disk - images?" for the description of how to use this for compiling - complete disk images. -

- Configure makefile script -
-

Emulation

-
-

How can I use other emulators?

-

You can "re-use" the existing tabs and specify another - emulator's executable. Using "User Defined Application", you can - select whatever you want. When using "User Defined Application", no - disk image is created or updated. You can use this setting to have - your script, which puts the executable file onto a disk image of - your choice, using additional tools like "dir2atr.exe" or - "AppleCommander," for example.

-
-
-
\ No newline at end of file +

How do I install Java?

+

I recommend you visit OpenJDK and follow the instructions to download and install the latest version. Make sure the Java version, the Eclipse version, and your operating system have the same architecture. Newer versions of Java only support 64-bit architectures.

+ +
+

Nothing happens When I try to start a .jar file via double-click. What is wrong?

+

You probably have the wrong Java version installed or set a default. Open a shell window and enter "java -jar <yourfile.jar>". If this works, then you have the wrong program or Java version associated with the ".jar" file extension in the registry. You can fix that by setting the path to the correct Java installation folder using "REGEDIT.EXE" for "Compute\HKEY_CLASSES_ROOT\jarfile\shell\open".

+

Java jar file registry entry

+

If starting from the command line does not work, you should see a more detailed error message about why.

+
+
+

How do I install Eclipse?

+

If you are unfamiliar with Eclipse, ensure you have installed the Eclipse platform distribution without Java or J2EE tools. This distribution is much smaller (typically around 60-80 MB instead of 170 MB) and will not confuse you with many features and buttons you do not need. See the "Installing Eclipse" section for the required steps on the "Installation" tab. 

+
+
+

When I try to start Eclipse, I get an error like "Failed to load the JNI shared library 'C:\Program Files (x86)\Java\jre6\bin\client\jvm.dll'". What is wrong?

+

The Eclipse and Java versions on your system are incompatible. The Eclipse is not pure Java but uses platform-specific native libraries to run and debug Java efficiently. For example, you must install the 64-bit version of Java (JRE or JDK) if you want to use the 64-bit version of Eclipse. This is a frequent issue under Windows 7 because, by default, only the 32-bit version of Java is installed. See the "Installing Eclipse" section for the required steps on the " Installation " tab.

+
+
+

How do I use Eclipse at?

+

Start the built-in help of Eclipse via the "Help/Help Content" menu and read the "Workbench User Guide" section.

+Workbench user guide
+
+

Why is WUDSN IDE not available via the update site?

+

You likely typed in the wrong update site URL, for example, using "wusdn" instead of "wudsn". The correct URL is "http://www.wudsn.com/update". In addition, you should uncheck the checkbox "Hide items that are already installed" to see what is there. See the "Installing WUDSN IDE" section for the required steps on the " Installation " tab.

+Installation dialog with update site
+
+

Why do I get "Unable to read repository at ... Read timed out" when accessing the update site?

+

This error message indicates the Eclipse program is somehow blocked from accessing the site. If you are behind a proxy server, check the general proxy server settings in the Eclipse preferences. If you use a firewall or internet security tool, make sure "Eclipse.exe", "java.exe", "javaw.exe," or the corresponding program on your host platform are allowed to cannot to the internet. Maybe you have to change the settings so you are prompted to allow access interactively.

+
+
+

Why do I get "Cannot complete the install because one or more required items could not be found" when updating the plugin from the update site?

+

This error message indicates that the Eclipse version you are running is too old. Check the releases page for the required minimum Eclipse version for every WUDSN IDE release.

+
+
+

Why is the "Assembler" section not visible in the preferences?

+

If the WUDSN IDE sections and features are not visible after a successful installation, you probably use an outdated Java version. For example, Java 1.6 has been out of maintenance since 2013/02. This seems to be a common problem on Mac OS X, even in Mavericks (10.9), which still uses Java 1.6 by default. Ensure you have at least the Java version mentioned in the installation section for the IDE installed and that Eclipse has started using that version.

+
+

Configuration

+
+

Why do I see wrong messages in the "Problems" view?

+

The default configuration of the "Problems" view shows all errors from all files in the current project. While this is a good default for Java programming, it is unsuitable for compiling single independent assembler files. Therefore, you have to configure the "Problems" view accordingly. See the "Installing Eclipse" section for the required steps on the " Installation " tab.

+
+
+

How do I associate my source file extensions with the correct editor?

+

The IDE supports many compilers and provides specialized editors. Typically, you have some preferred source file extension (".asm" or ".a") and a preferred compiler. The procedure to associate the file extension with the editor via the preferences is described in this video tutorial WUDSN IDE Tutorial 3: Setting up Editors and File Extensions correctly.

+
+
+

Why must I put ";@com.wudsn.ide.lng.hardware=..." in the source file?

+

The association with the file extension with your compiler's editor (done in the preferences; see before) does not determine which platform you want to create output. Therefore, this additional annotation in the main source file must tell the IDE, which is the target platform. It is used to find the correct compiler and emulator settings, which can differ per platform. Every compiler has a default platform (see the online help in the IDE), but it can also be used on every other platform. Therefore, you must specify the target platform in the main source file if you use a non-default platform.

+
+ +

Editing

+
+

Why is editing sometimes slow, or is everything blocked, showing the wait cursor?

+

The core of WUDSN IDE uses the Eclipse Platform Runtime only and does not require any additional plugins. It starts quickly and dashes with that configuration, and I use it daily. So, if you experience performance problems, try to download and run the zero installation distribution of WUDSN IDE. Performance problems are very likely caused by additional plugins or themes installed. Often, these plugins are not only slow but broken. Check the ".metadata/.log" file in the workspace folder. In some Eclipse versions, this is available via "Window/Show View.../Error Log".

+
+
+

Is there support for source version control?

+

Several plugins are available to connect Eclipse to CVS or subversion. Also, the "Local History" feature is installed by default. You can configure it in the preferences. It automatically records all changes to the source file and lets you compare versions in place.

+Source version control
+
+

Is there support for a block selection mode?

+

A toolbar button and the shortcut "ALT+SHIFT+A" to toggle block selection mode in all text editors. This can be useful for adding and removing common prefixes such as line numbers.

+Toggle block selection mode +

If the toolbar button is not visible, you have to set it to visible via the menu entry "Customize Perspective" in the context menu of the main toolbar. In the customizing dialog, you must activate the "Editor Presentation" command group and the toolbar entries you want to see.

+Toggle block selection mode
+
+

Why does "CTRL-Space" not open content assist?

+

There is a known keyboard assignment conflict when using Messenger Plus Live! v4.85.0.386 with Microsoft Messenger 2009 on Windows 7 Ultimate. This may also occur in other versions, of course. Justin Payne has provided the following description of the solution.

+
    +
  1. Startup and log into MS Messenger.
    2. +
  2. From the main window, hit the ALT key to bring up the main menu and select "Plus! | Preferences & Options".
    3. +
  3. From the Preferences windows, Select the Messenger tab and uncheck "Activate Messenger Lock with a system-wide shortcut" OR change the value in its text box to something other than "CTRL + Space".
    4. +
  4. Press the "OK" button.
    5. +
+
+
+

Why do CTRL-SHIFT-0/9 and other key combinations not work?

+

You probably have another program outside of Eclipse that has already captured these keys or key combinations. A frequent problem is the Windows Input Methods Editor (IME), which is used to switch keyboard layouts. For example, if you use multiple keyboard layouts, the CTRL-Space is mapped to allow you to cycle between the different keyboard regional keyboard layouts. You should be aware of how to turn the feature off since you're probably using this feature, but if you don't...

+

Windows 7

+
    +
  1. Within "Windows Control Panel", open "Region and Settings".
    2. +
  2. Select the "Keyboard and Languages" tab and "Change Keyboards...".
    3. +
  3. In the "Text Services and Input Languages" windows, select "Advanced Key Settings".
    4. +
  4. In the "Hot Keys for input languages" list box, select "Between input languages" and then select "Change Key Sequence..."
    5. +
  5. In the "Change Key Sequence" window, choose another radio button other than the one next to CTRL+Shift. At best, you choose "(None)".
    6. +
  6. Click OK until you close all popup windows.
    7. +
+

Windows 10

+
    +
  1. Open "Control Panel\Clock, Language, and Region\Language\Advanced settings.
    2. +
  2. Click the "Change Language bar hot keys".
    3. +
  3. Set all key sequences to "(None)".
    4. +
  4. Click OK until you close all popup windows.
    5. +
+

Of course, this is Windows 7/10, and we know how Microsoft loves to change its layouts and names, but this option is available back to Windows XP.
Configure Windows IME hot keys

+
+

Building

+
+

Why is MADS the primary assembler?

+

When I started with WUDSN IDE, ATASM was the first supported compiler. The reason was simple: 90% of my sources are in ATASM format. ATASM is very comprehensive and fast. Its capabilities to define constants and byte sequences are extensive (".BYTE", ".WORD", ".DBYTE", ".FLOAT", ".SBYTE" for ATASCII, ".CBYTE" for terminated strings, separate offset for all constants). Over time, additional platform compilers have been added, and their support will be completed step by step. When the support for MADS was relatively complete, I found it the most powerful compiler I have ever seen and used. The support for ".PROC/.ENDPROC" has revolutionized how I write assembler code. It allows logical structuring and visibility control without any runtime overhead. At the same time, MADS is compatible with MAC/65 and XASM, and even ATASM sources can be adapted to MADS with a few minor changes described below. Therefore, MADS has been the primary compiler since WUDSN IDE version 1.6.0.

+
+
+

Why do I get the error "No ORG defined" when compiling the example from the tutorial?

+

Since WUDSN IDE version 1.6.0 MADS is the primary compiler registered for the file extensions ".asm" upon installation. You are trying to run the code example for version 1.5.0 or before, which is in ATASM format. Therefore, you can either.

+ +
+
+

Why are the errors and warnings from an included file assigned to the primary source file in the problems view?

+

You use a case-insensitive file system and have used different upper or lower-case writing in the statement than in the actual file system. For example, you have written "ICL 'example.asm'" for a file named "Example.asm" on the file system. In Eclipse, the file names of all resources are treated as case-sensitive, even if the underlying file system is case-insensitive. Therefore, the file name issued by the compiler will not match the file name. The IDE assigns the error message to the primary source file as a fallback. To fix this, you must adapt the spelling of the file name in the source include statement.

+
+
+

How do I convert from ATASM format to MADS format?

+

Because ATASM's and MADS's syntax are based on the MAC/65 syntax. There are not many differences. Therefore, manual conversion using "Find/Replace (CTRL-F)" is easy.

+ +
+
+

How does ATASM generate segments in executable files?

+

A helpful feature for small projects is that, by default, ATASM sorts the segments by address and warns if the same address is overwritten by code or data. Since version 1.05, the ".BANK" directive is available, which allows you to create COM files with "INITAD" segments and arbitrary segment counts. If you don't use the ".BANK" directive, ATASM will sort the segments by their address and put consecutive blocks into a single segment by default. While this saves some bytes, it might be unclear if you are used to other assemblers. Note that you must use the ".SET 6" directive to set the assembler origin offset in every bank if you use it in one of the banks.

+
; Bank 0
.bank
.set 6,0
* = $8000
start lda #0
jmp *

; Bank 1
.bank .set 6,0
* = $2e0
.word start;

; Bank 2
.bank
.set 6,$4300-$C000
* = $C000
lda #1
sta label+1
label lda #2
jmp *
+
 
+
+
+

How do I compile into ROM images?

+

Plain ROM Images do not have header bytes by default, or at least they do not have the same header bytes as executable files. Compiler-specific options must be used to create raw object files without headers. Some cases are listed below. See the manual of the specific compiler for more details.

+ +
+
+

How do I compile into disk images?

+
Atari 8-bit
+

For Atari 8-bit, the ATASM compiler has a dedicated parameter to write the executable file directly into ".ATR" or ".XFD" disk images. The disk image must be formatted with Atari DOS 2.0S, DOS 2.5, or a compatible DOS. All Atari 8-bit disk formats can be created using the "dir2atr.exe" tool of the AtariSIO tools by Matthias Reichl (hias). The command line tool can create a complete disk image with arbitrary DOS (Atari DOS 2.5, MyDos, SpartaDOS) and size based on a folder that contains "DOS.SYS", "DUP.SYS" (or the equivalent files of the respective DOS) and all other files requires. I have packaged an example, including the "dir2atr" tool, a batch script to call the command line tool and emulator, and this archive's "files" folder. Unpack the archive to your output folder. Double-click "makefile.bat" to see how the disk image is created and started. Read the section "How to run a makefile script instead of an emulator?" for the details on configuring the call to "makefile.bat". For productive usage, you should put the "hias" folder into a central location and use the most recent version from Matthias Reichl's website. For MacOS X users, the download also contains a "makefile.sh" script and MacOS X binaries of Matthias Reichl's tools. The binaries have been provided by Fredrick Holst (freetz), and you can find the latest versions on his website.

+
Apple II
+

For Apple II, WUDSN IDE automatically generates a bootable AppleDos 3.3 disk image with the extension ".dsk" if one of the predefined emulators is used for execution. If you want to use another DOS or disk size or if you're going to put more files onto the disk after compilation, you can use the command line version of AppleCommander to achieve this. Create and configure a makefile script as described in "How to run a makefile script instead of an emulator?". In the case of Apple Disk images, always remember to use the correct file content/load/run address. The IDE needs to know the load address of an executable file to store this information in the directory entry. The IDE evaluates the file extension to detect the load address from the executable file. Supported extensions are ".b", ".prg," and ".xex". Here's the logic for the built-in disk image creation:

+ +
Other hardware
+

If you find a tool similar to "dir2atr.exe" for the Atari 8-bit or "AppleCommander" for the Apple II, you can create your script and run it as described in "How to run a makefile script instead of an emulator?".

+
+
+

How can I run a makefile or script instead of an emulator?

+

Sometimes, running a makefile script instead of the emulator is helpful, for example, if the output file is combined with additional files into a single ATR file. To execute such a script, select "User Defined Application" as the "Default Application to open Output File". Specify the path to the shell as "Path to Application". On the command line, you can then use the standard variables to start the command shell and pass the script's name and the file path of the compiled output file. Since the working directory during execution is the compiler's output folder, you must place the script file there or specify the script file with its absolute path. If you are using Windows and "cmd.exe" as your shell, you must add "/c" before the name of the script to prevent "cmd.exe" from remaining as a process after it is finished. The resulting command line is "${runnerExecutablePath} /c makefile.bat ${outputFilePath}", assuming "makefile.bat" is located in the output folder". See section "How do I compile into disk images?" for the description of how to use this for compiling complete disk images.

+Configure makefile script
+

Emulation

+
+

How can I use other emulators?

+

You can "re-use" the existing tabs and specify another emulator's executable. Using "User Defined Application", you can select whatever you want. When using "User Defined Application", no disk image is created or updated. You can use this setting to have your script, which puts the executable file onto a disk image of your choice, using additional tools like "dir2atr.exe" or "AppleCommander," for example.

+
+ diff --git a/com.wudsn.ide.lng/help/ide-features.section.html b/com.wudsn.ide.lng/help/ide-features.section.html index 403f6c18..4afffe47 100644 --- a/com.wudsn.ide.lng/help/ide-features.section.html +++ b/com.wudsn.ide.lng/help/ide-features.section.html @@ -1,1032 +1,670 @@

The latest version contains the following features:

-
- General IDE enhancements   » top -
+
General IDE Enhancements   » top
-
- Fully integrated assembler editor   » top -
+
  • The "Open Folder" context menu is available for all folders and files.
    • +
  • The "Sort" context menu with sub-menu is available for all text files, including
    -
    - Content outline and source folding   » top -
    +Open folder action in context menu Sort action in text editor context menu
    • +
  • The online help contains the "WUDSN IDE Guide" with the following multiple sections. -
    - Content assist and code completion   » top -
    +
  • WUDSN IDE
    This is the documentation from the website. - +
    • +
  • Assemblers
    This is the information on the supported assemblers and their properties. -
    - Hex Editor   » top -
    +
    • +
  • Hardware Platforms
    The information on the supported hardware platforms and the corresponding emulators and links. -
    - Graphics Editor   » -
    +
    • + +
    Integrated Help + +
    Fully Integrated Assembler Editor   » top
    -
    - Preferences for editing   » top -
    +
  • 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.
    IDE editors, content types and file associations
    • +
  • Content types and file associations for Atari 2600 compilers  -
    - Preferences for compiling   » top -
    +
    • +
  • Content types and file associations for Atari 8-bit compilers -
    - Annotations for compiling   » top -
    +
    • +
  • Content types and file associations for C64 compilers -
    - Known bugs   » top -
    +
    • +
  • New content types and file associations for NES compilers + +
    • +
  • The default editor for a file extension can be configured in the "File Associations" section of the preferences with the "Default " button.
    IDE file associations
    • +
  • Syntax highlighting provides colors and styles for comments, directives, different types of identifiers, legal opcodes, illegal opcodes, pseudo opcodes, and strings.
    • +
  • Single-line comments for the current line selection can be toggled using "CTRL-7" or the editor context menu entry "Toggle Comment".
    • +
  • Support for illegal opcodes of the 6502 CPU is configurable.
    • +
  • Support for 16-bit opcodes of the WDC 65816 CPU is configurable.
    • +
  • Built-in support for ATASM assembler, MADS assembler, XASM assembler, ACME assembler
    • +
  • Built-in support for running compiler output files with the operating system default application without configuration effort
    • +
  • Built-in support for Altirra emulator, Atari800Win emulator, Atari800MacX emulator, Atari++ emulator
    • +
  • Adding support for new compilers and applications is possible via Eclipse extension points.
    IDE compiler extensions
    • +
  • Build or build and run with a single keystroke or via the menu.
    • +
  • 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.
    • +
  • 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.
    Run with... for Atari 2600 Run with... for Atari 8-bit Run with... for C64
    • +
  • The "Open Source Folder" and "Open Output Folder" entries the respective folder directly from the menu.
    • +
  • 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.
    TODO: Note that the images below are outdated and must be updated.
    IDE assembler menu
    • +
  • The complete list of assembler/compiler errors and warning messages in the problems view.
    • +
  • Direct navigation to the source location is supported by double-clicking the problem message.
    • +
  • Problem markers in the scroll area, including the tooltip with the problem message.
    IDE example source
    • +
  • German localization is available for all Eclipse plugin texts. The original compiler messages are not translated, but some are mapped automatically.
    + +
    • +
  • 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.
    IDE compiler console view
    • + +
    Content Outline and Source Folding   » top
    +

    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.

    + +
    Content Assistance and Code Completion   » top
    +

    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.

    + + +

    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.

    + +
    Hex Editor   » top
    +

    The Hex Editor allows inspection of arbitrary files on the binary level. It has the following features.

    + +
    Graphics Conversion Editor   »
    +

    The Graphics Conversion Editor views and converts many binary and image file formats. It has the following features.

    + +
    Preferences for Editing   » top
    +

    The WUDSN IDE editor is configurable via language-specific preferences. They are available via the entry "Preferences" from the menu "Window" (under Windows and Linux) or the menu "Eclipse" (under macOS) and include the following.

    + +
    Preferences for Building and Running   » top
    +

    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)

    + +

    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.

    + +

    The preferences for the applications to run the result of the build process can be maintained for all assemblers/compilers in parallel. They include:

    + +
    Annotations for Building   » top
    + +
    Planned Features   » top
    + +
    Known Bugs   » top

    Open bugs:

    -

    Fixed bugs:

    +

    Fixed bugs per release:

    \ No newline at end of file diff --git a/com.wudsn.ide.lng/help/ide-installation.section.html b/com.wudsn.ide.lng/help/ide-installation.section.html index 7600bd45..93b974b2 100644 --- a/com.wudsn.ide.lng/help/ide-installation.section.html +++ b/com.wudsn.ide.lng/help/ide-installation.section.html @@ -1,358 +1,157 @@ -

    - The recommended way to install WUDSN IDE is the WUDSN IDE Installer. It - is available for Windows 64-bit, macOS and Linux. -

    -

    If you use another operating system, want to use an older version - of WUDSN, or wish 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 get in touch with - me.

    +

    The recommended way to install WUDSN IDE is the WUDSN IDE Installer. It is available for Windows 64-bit, macOS and Linux.

    +

    If you use another operating system, want to use an older version of WUDSN, or wish 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 get in touch with me.

    -
    - Installing Eclipse   » top -
    +
    Installing Eclipse   » top
    -
    - Installing WUDSN IDE   » top -
    +
    Installing WUDSN IDE   » top
    -
    - Installing assemblers and compilers like ATASM, MADS, XASM...   » top -
    +
    Installing Assemblers and Compilers like ATASM, MADS, XASM...   » top