![]() |
HEL_ASSERT
mechanism evaluates an expression and, when the result is FALSE
, displays an errorscreen and aborts the program execution until you press a specific button. The error-screen displays several informations where in the source the assertion failed. This includes: HEL_ASSERT(expression, message ...)
Parameter:
expression : Expression that evaluates to TRUE or FALSE message : Message to display when expression is FALSE
The HEL_ASSERT
macro is typically used to identify logic errors during program development by implementing the expression argument to evaluate to FALSE
only when the program is operating incorrectly.
After debugging is complete, assertion checking can be turned off by undefine HAM_DEBUGGER
in 'ham/include/mygba.h':
#define HAM_DEBUGGER
Example:
In this program the SetHeroState
function uses HEL_ASSERT
to test if the passed pointer pHero
is NULL
and State
is lesser than HERO_STATE_ITEMS
.
typedef struct _THero { int State; }THero; enum { HERO_STATE_JUMP=0, HERO_STATE_WALK, HERO_STATE_STAY, HERO_STATE_ITEMS }HERO_STATE; THero gHero; void SetHeroState(THero *pHero, u32 State); void main(int argc, char *argv[]) { // Initialization and whatever ... // Does not raise an error! SetHeroState(&gHero, HERO_STATE_STAY); // Displays an error, because we // pass NULL as first parameter!! SetHeroState(NULL, HERO_STATE_STAY); } void SetHeroState(THero *pHero, u32 State) { HEL_ASSERT(pHero != NULL, "pHero must not be NULL"); HEL_ASSERT(State < HERO_STATE_ITEMS, "State must not be greater than HERO_STATE_ITEMS"); pHero->State = State; }
HEL
provides an easy to use mechanism to set program execution breakpoints, which are automatically turned off when you switch to releasemode. Please note that these breakpoints are currently only supported by NO$GBA emulator and must be explicit turned on!
Using such a breakpoint is easy, all you need is HEL_DEBUG_BRK
Example:
The following example shows how to stop the program execution using HEL_DEBUG_BRK
macro:
int main() { ham_Init(); // stop program execution! HEL_DEBUG_BRK; while(GameIsRunning) { // some fancy stuff ... } return 0; }
The program execution is stopped after ham_Init and before the while-loop. NO$GBA halts at this point and displays the assembler sourcecode in its debugger-window where you then can step through:
HEL's
breakpoint implementation with another emulator than NO$GBA, it will just leave the corresponsing opcode away, assuming you specified what emulator you use (see Debug Message Output) and therfore will not halt at the position where the breakpoint is set.NO$GBA shareware or professional version. "Source Code BReakpoints" must be turned on in no$gba Xcept setup.
debug
and release
library of HEL
.
HEL Library comes in two forms. One for debug purposes, using Assertion Checking and one for the final release, which does not include ASSERT
and is faster and smaller.
The debug
library consumes more memory (ROM/IWRAM/EWRAM) than the release
library and is also slower and bigger in its filesize. The more memory consumtion is archieved because it includes a few variables for reference-counting which are located in EWRAM (< 500byte) and some self-modifing-code which must be in IWRAM (< 400byte).
While working on a project, it's recommended to use the debug library. This is just because the debug library includes ASSERT
checking and so it will display an errormessage when you pass an invalid parameter to one of HEL's functions. ASSERT
calls seem to be a bit overhead for the little GBA, but they help a lot in the development process and therefore they are implemented in the debug version of HEL.
All ASSERT
calls, Reference-Counter variables as well as Debugging Functions are removed in the release library. Even a lot of functions get replaced with macros when you switch to release mode to gain maximum speed. As of version HEL 1.5, this includes the Object/Window/DMA/System/SpecialFX/etc... modules!
Switch between Debug and Release Library:
Since sooner or later you want to switch between the debug and release library, here is an explanation how this can be done.
Copy libhel.a as described in the Installation guide into the correct directory. Now, depending on what version you copied (debug or release) you have to either enable or disable HAM_DEBUGGER
which is located in mygba.h. The file mygba.h is the header file of HAM
and located into the 'ham/include' directory in your HAM installation. Make a stringsearch in this file for HAM_DEBUGGER
. You should come across this text:
#define HAM_DEBUGGER 1
That is the default setting! If you want to turn off debugging just comment out this line as demonstrated below:
//#define HAM_DEBUGGER 1
HEL is now also forced to use macros for a lot of functions, please see notes in this context.
When to use the Release Library:
A disadvantage of the debug library is that you don't have the full performance as mentioned earlier. At some point of time you want to see how your game really runs on the GBA. This is a good moment to rebuild the project in release mode and then watch it in all its glory and full speed on hardware. Basically, whenever I think my game is bugfree and I want to test it on hardware, I rebuild the entire project with the release library and switch back to the debug version when I continue developing by using an emulator.
Notes:
Due to the fact that several modules in HEL are almost entirely replaced with macros in release mode, you can encounter an error that it cannot find a symbol (function) in the library. This error occurs when you use the release library but you did not remove the HAM_DEBUGGER
define. In this case HEL still thinks it should use the functions which are located in the library instead of using the macros.
HEL
provides an easy to use mechanism to output formatted debug messages, which are automatically turned off when you switch to releasemode.The Debug-Message-System currently supports NO$GBA and VisualBoy Advance. Activating one or the other is easiely done:
HEL_DEBUG_MSG_TYPE_
(should be located around line 60) HEL_DEBUG_MSG_TYPE_VBA
for VisualBoy Advance DebugMessages, or HEL_DEBUG_MSG_TYPE_NOCHASH
for NO$GBA support.HEL_DEBUG_MSG_TYPE_NOCHASH
is the default setting when you just installed HEL
.Example:
The following example shows how to switch to VisualBoy Advance support. Once you have hel.h infront of you and scrolled a few lines down, you see:
//#define HEL_DEBUG_MSG_TYPE_VBA #define HEL_DEBUG_MSG_TYPE_NOCHASH
As you can see, at this time NO$GBA support is activated. To activate VBA, change it to:
#define HEL_DEBUG_MSG_TYPE_VBA //#define HEL_DEBUG_MSG_TYPE_NOCHASH
Usage:
To make use of Debug-Messages in your project, all you need is HEL_DEBUG_MSG
. It does not matter what Debug-System you activated (NO$GBA or VBA), just use HEL_DEBUG_MSG
. Everything else is done for you automatically!
Macro:
HEL_DEBUG_MSG(txt, args...)
Parameter:
txt : Format-control string args : Optional arguments
Example:
HEL_DEBUG_MSG("Hello World\n"); HEL_DEBUG_MSG("I am %d years old.\n", 28);
Output:
Hello World I am 28 years old.
Remarks:
HEL's Debug-Message-System only works, as the name already says, in Debug-Mode. To switch between Debug and Release-Mode, please see Debug and Release Library mystery. Another important part is to know that VisualBoy Advance Debug-Messages do not work on hardware! They freeze the GBA! Having Debug-Messages enabled when using it outside an emulator makes no sense anyway.
Requirements:
NO$GBA shareware or professional version, freeware version does not support debugmessages! VisualBoy Advance SDL (commandline tool).
hel_DebugSetOnAssert
function for this.Function:
hel_DebugSetOnAssert(PDebugAssertFunc pFunc)
Parameter:
pFunc : A pointer to the function that should be called before an assertion takes place
Example:
void main(int argc, char *argv[]) { // Initialization and whatever ... // set function that gets executed before // the assertion takes place hel_DebugSetOnAssert(OnAssert); // raise an assertion ASSERT(0==1, "0 cannot be 1"); } void OnAssert(TDebugAssertInfo *pInfo) { // just write some text to the console HEL_DEBUG_MSG("OnAssert called"); }