
                              BasicX Ramalyzer(tm)
                                     v0.5

The BasicX Ramalyzer is fairly simple to use.  From a command prompt and with
the current directory set to the directory containing your BasicX project file
(e.g. myproj.bxp), you may simply use the command:

Ramalyze myproj

This will cause the Ramalyzer to read each of the files listed in the project
file myproj.bxp and the information in the file myproj.mpp.  From this
information, an estimate the RAM usage of sub main() will be made and displayed
on the console.  Of course, you may redirect the output to a file thusly:

Ramalyze myproj > ramuse.txt

Error messages, if any, are written to stderr so they will still appear on
the console even with stdout redirected.

To get more details, such as which subroutines or functions are invoked and
an itemization of the usage of the subordinate routines, invoke with the
-d option.

Ramalyze -d myproj > ramuse.txt

If you wish to analyze only a portion of the calling tree, specify the target
thusly:

Ramalyze -t mysub myproj

or

Ramalyze -tmysub myproj

You may use the -d option and/or redirection in this case, too.

Only the routines that are referenced are included in the normal output.  This
corresponds to the behavior of the BasicX compiler which automatically excludes
unused routines.  To get a list of the unused routines, add the -u option.

Ramalyze -u -d myproj

The output produced by the -d option is a "calls" list, listing each routine
that is potentially called by a given routine.  If you wish to see a "called by"
list, use the -c option.  This lists, for each routine, all the routines that
call it directly.

Ramalyze -c -d myproj


Notes:

The Ramalyzer will only produce useful results from .bas files that compile
cleanly.  The parser does very little syntactic analysis and assumes that
the program is syntactically correct.  It is suggested that you run the
Ramalyzer immediately after a clean build of your application.

When the .mpp file is read, certain strings are detected and used as cues
to extract useful information.  If the .mpp file has been modified or the
format is changed in the future, it may break the program.

Currently, the Ramalyzer does not add in contributions to RAM usage by the
System Library routines.  I may be able to add estimates for these in the
future from empirical data.

The Ramalyzer only performs static analysis.  It assumes that all subroutines
and functions referenced in the body of a routine will be called.  In reality,
of course, they may not be.  Moreover, the contribution to stack usage by
recursion, either direct or indirect, is only partially accounted for.  Direct
recursion will add zero to the estimate.  Indirect recursion will add usage
from all of the intermediate routines and none for the ultimate recursion.

This is beta-level software.  It is believed to function correctly and to
produce reliable results but it may do neither.  Please inform the author
of any peculiar or unexpected behavior that is observed.  Details are
helpful, even necessary, in order to analyze, diagnose and resolve problems.

Disclaimer

This program is provided as is and without any warranty whatsoever.  It is
believed to be benign with respect to existing files but no such guarantee
can be made.  For your protection you should perform frequent backups to
mitigate the loss in case of unexpected side effects.  By using this
program you confirm that you freely accept any and all risk of use of
this program and that the author, his heirs and his estate will be held
harmless in all respects.

Copyright 2003 Donald Kinzer All rights reserved.
email:don@kinzers.com

Change History
v0.1 - Initial version.

v0.2 - Added code to suppress the display of information about unreferenced
       routines.  Since the .mpp contains no parameter and local variable
	   information, the information that was being displayed was incorrect.

	 - The sorting of called routines was not always in order of decreasing
	   usage, particularly when there were only two called routines listed.

v0.3 - Added -u option to display a separate list of unused routines.

v0.4 - Added -c option to display a called-by list each routine.

v0.5 - Corrected the calling overhead - 9 bytes not 11.

v0.6 - Added section to report minimum stack requirement for tasks.

v0.7 - Fixed a bug, introduced in the last revision, that caused the program
       to lose track of which routine it was analyzing when a CallTask
	   statement was encountered.