RapidDBG v1.41  7 June 2011

RapidDBG.exe is a gui wrapper that controls a debugging "session".

The bulk of the work in parsing the users source code is done
using fbDBGParser.dll.  The dll source has been compiled/tested
using FreeBasic v0.21.0 dated 07-24-2010.

The actual "running debugger" is the compiled <users source code> WITH
<debug code> PLUS <RapidDBG.dat> PLUS <some "on the fly" code> generated
by the dll.

The zip file contains all of the source files necessary to create
the new dll and RapidDBG.exe (including example "make" batch file).
A pre-made fbDBGParser.dll is also included.

Unzip all files to an empty folder and check/modify the "make" file.
Create the dll (or use supplied one) then create RapidDBG.exe.
You can move the exe file to any folder you wish.  The dll can be moved
to the same folder, or, you can place it in your RapidQ LIB folder.

When RapidDBG.exe is run for the very FIRST time, you will be asked for your
RapidQ environment. A small "ini" file will be created for all future calls.
However, if running from FreeQ IDEa, RapidDBG will get its environment from
your Freeq.ini file.

Usage:
[Stand-alone]
    RapidDBG.exe with no parameters
    Select a file to debug from a File Select Dialog box.
    Only "bas" or "rqb" file types supported.

[IDE or Editor or Batch file]
    RapidDBG.exe <switch> <filename> [-b]

    Parameters:
    filename: <bas> or <rqb> file and MUST include the FULL path    

    switch: one of the following (case non-sensitive)
        -t = syntax Test the original source file (display results on errors)
        -c = Compile to exe (if no errors)
        -r = compile to exe and Run the original source file (if no errors)
        -d = compile debug+source code, if no errors, run the Debugger

    Optional switch to -d:
        -b = preset Breakpoints in the form of a CSV string of line numbers,
        order is not important, but see limitations note 1 below
        eg -b 237,126,1348,23456 sets four breakpoints

As of v1.40, the (running) debugger will now debug code outside of subs & fns, and
will allow breakpoints to be set as well.


RapidDBG will NOT debug source code with line numbers.
RapidDBG does NOT debug "$INCLUDE ....." files.

_______________________________________________________________________________
Debugging:

[RapidDBG]
RapidDBG will FIRST compile YOUR source code, using rc.exe, and ensure that
there are NO syntax errors (the resultant exe is deleted).
ANY ERRORS WILL BE DISPLAYED AND RapidDBG WILL TERMINATE.

RapidDBG, using the supplied dll, will then parse your source code into a
temporary file (in the same folder as your source code), adding debug
information. RapidDBG will then compile this temporary file. If there are
errors in the compile, they will be displayed and RapidDBG will terminate.
If there are no errors, the resultant executable (the debugger) will be 
"run" while RapidDBG terminates.

[Debugger]
If the debugger runs successfully, it will either pause at the first line of 
the FIRST global variable declared, or, IF valid preset breakpoints have been
set (with the -b switch), will pause at the FIRST breakpoint encountered
during execution.

Pausing the debugger may involve a user action (eg button click) depending
on the source code you are debugging!
If RapidDBG does not stop (when you think it should) try the Function F4 key
(HALT), if unsuccessful, then try a user action (eg button click).
In certain circumstances nothing may work, and the program may have to be
exited via your program's normal exit mechanism, or "killed" via Task Manager.

On exit, by default, the debugger will "clean-up" the temporary files it has 
created in the folder of your source code. To examine these temporary files,
exit the debugger via your program's normal exit mechanism (not via the debugger). 
NB The current version of FreeQ IDEa v1.10 cleans up ALL temporary files, so
this does not work.

Error message "### RapidDBG FAILURE ###" displayed:
IF there is a problem compiling the debug+source file (a bug in RapidDBG), this
temporary file will NOT be deleted.  An extract from this file around the designated
error line, emailed to me, would be invaluable, and appreciated, for the benefit of all.
_______________________________________________________________________________
For the novices:

The "$OPTIMIZE ON" directive is not recommended (personal preference).

The "$ESCAPECHARS ON" directive ONLY if your code actually uses "escape" chars in
strings eg DEFSTR mystring="This is a newline\r\nThis is a backslash \\"

The "$TYPECHECK ON" directive is HIGHLY recommended.
This forces you to declare your variables at the expense of some extra typing,
however with copy/paste the little extra effort can save you a lot of time in
finding those "typo" errors!

Local variables:
When the debugger FIRST stops inside a sub/function, any local variables (variables
declared inside the sub/function) will display RANDOM DATA (whatever "junk" is on
the stack). This is NORMAL.
Until your sub/function initialises these variables that "junk" is real and valid,
but it IS random, hence, do NOT count on it being the same, on every call to the
sub/function!  The obvious exception to this is when you declare & initialise a
variable in the same step eg DEFINT a=1

Arrays in RapidQ (and the debugger):
1.  There are no bounds checking in RapidQ when writing/reading to/from arrays, and
    hence there will be no syntax error generated, if your code steps outside of the
    array bounds.

2.  MyArray(1 to 5) indicates that you are using ONLY 5 elements and the debugger
    will ONLY display 5 elements.
    If you choose to write to MyArray(0), or anything above MyArray(5), RapidQ will
    allow this, and will also allow you to read back this data, as well!
    However, you may be corrupting the memory of some other variable(s), which could
    give some weird results. Care, especially in loops, should be taken to prevent this.
    
3.  MyArray(5) and MyArray(0 to 5) are equivalent and indicates that you are using
    6 elements for this array. The debugger will display all 6 elements.
    If you do not choose to use MyArray(0) in your code, then it will contain random
    "junk" data, and the debugger will display this, but there will not be any problems.

4.  The above applies to array dimensions 1,2 & 3 (current max limit of 3)

5.  Initialised arrays.
    Initialisation starts at the first element, hence:
    DEFINT MyArray(5)={1,2,3,4,5} => MyArray(0)=1, MyArray(1)=2,...,MyArray(5)=undefined
    Whereas:
    DEFINT MyArray(1 to 5)={1,2,3,4,5} => MyArray(1)=1, MyArray(2)=2,...,MyArray(5)=5

6.  The debugger does NOT parse (nor display) arrays that have a variable as one
    of its dimensions (compare this to a REDIM statement, which equally is not parsed).
    

Window "on top":
If your source code does not set the "minimize" function of your form correctly,
your form will remain on top (of the debugger), and you will need to manually
minimize it, to see the full debugger screen.  I have not found a "fix" for this.
Adding the following to your source file, at the appropriate place, with your form
name, WILL fix the problem.

    SetWindowLong(Your_Form_Name.Handle, -8, 0)
    SetWindowLong(Application.Handle, -8, Your_Form_Name.Handle)

If you get this far, hit the F1 key (or mouse click "Help") for commands available.
_______________________________________________________________________________

KNOWN LIMITATIONS (BUGS?):

1. Any preset breakpoints that are set on non-executable lines of source code,
   (eg a "DIM" statement inside a sub/function), will be ignored.
   If none of these breakpoints are valid then RapidDBG will default to act
   as if NO preset breakpoints were set.

2. Objects and structs (user types) are NOT parsed.

3. "$INCLUDE ...." files, within your source code, are not parsed!
   Generally speaking, you should never NEED to debug these.
   However, to debug an include file, copy the entire code into a "bas" file,
   add some "wrapper" code (to test the include code), and then proceed to
   debug this "bas" file created.
   When you are happy with the results, write the debugged include code back
   into the original "inc" file.
   Note: RapidQ2.inc is ~7500 lines with 1000+ constants & defined constants.
   Not a good idea trying to debug this AND some creation of your making.

4. NO "watch points" as these would definitely slow down the running code.
   Maybe later.

5. Unable to change any variable value "on the fly". Maybe later.

6. REDIM is not parsed. Only the ORIGINAL array bounds are displayed.

7. SELECT CASE .. END SELECT anomaly
   Any "case" statement line, with multi-statement code separated by the ":"
   character, is not parsed by the debugger and it will NOT pause at this line.
   If you must debug these lines you will need to "split" them in your source code.
        eg SELECT CASE something
                CASE 1: do stuff: do more stuff      ' Debugger will NOT pause here
                CASE 2
                    do even more stuff               ' Debugger WILL pause here...
                    and lastly do more stuff         ' ...and here
                CASE .....etc
    I am not sure why, but believe it is the way that RC.EXE optimises the 
    "Select case .. end select" block as a whole, for the interpreter.
    Apologies to William if this is not the case!
    Anyway, the debugger skips these lines when detected.


Finally:
If you haven't already - check out JohnK's IDE (FreeQ IDEa) - available from
http://rapidq.phatcode.net/FreeQ/
FreeQ IDEa is based on the scintilla codebase and tailored for RapidQ. If you
are serious about developing code, get this great IDE.
Currently, RapidDBG is the default debugger for the IDE.

Bugs, comments, suggestions etc welcome.
Contact: d_homans@yahoo.com.au

Happy coding (and bug fixing?)
Rgds to all
Don
