» home
» bugs
» git

The way I (Tobbe) debug modules

Setting up LiteStep

First you have to compile LiteStep. Obviously you should compile a Debug binary as we want to debug stuff.

Next thing to do is to set your normal LiteStep path as the working directory for your debug build of liteStep in your IDE. I'm going to describe how to do that using my IDE of choice, Visual C++ 2008.

  • Rightclick on the liteStep project
  • In the tree menu to the left, choose Configuration Properties→Debugging
  • Set Working Directory to the folder where you have your normal litestep.exe. In my case that's C:\Program\LiteStep\
  • Click OK and you're done with that.

It should now be possible to run LiteStep from within your IDE. In my case I press F5 and the debug build of LiteStep starts with my normal theme.

You can try setting a breakpoint in the CLiteStep constructor. Run it again and make sure it stops on the breakpoint, just to make sure everything works.

Stop debugging

Preparing your module

Build a debug version of your module.

Put LoadModule "C:\Path to the\Debug Version\of Your\module.dll" in one of the .rc files your normal LiteStep installation uses (like step.rc or theme.rc)

Make sure you aren't running any debug version of LiteStep.

Start your normal litestep.exe by double clicking on it and make sure your module gets loaded (check with !about or something).

!Quit LiteStep

Debugging your module

Load up LiteStep in your IDE again, as if you were to compile it.

Open one of the source files from the module you want to debug.

Set a breakpoint somewhere in the file you just opened.

Now launch the debug version of LiteStep (i.e. by pressing F5 in my case).

If everything is working it should stop at the breakpoint in your module and you can step through the code and look at variables and what not.

Making changes

If you want to make any changes to the code in your module you should have your module's project open in another IDE instance.

Make the changes you want, !quit LiteStep (so your module isn't loaded), and finally compile your module.

Going back to the IDE instance with LiteStep it should notice that you have edited your modules sources and offer to reload the source files.

Let it do that, make sure the breakpoints are where you want to have them, and start LiteStep from within the IDE again to continue debugging.

Old text (2008-01-07)

[00:32] The whole point of debugging litestep is to root out those stupid bugs

[00:33] the way most people have been doing it, even if they have a full featured IDE is to quit litestep, build, copy, start litestep, wait for crash, yadda yadda yadda

[00:33] The following is meant to make it much easier for you people out there to debug litestep and litestep modules in a much more efficient fashion

[00:34] This "tutorial" of sorts is highly bent towards Microsoft Developer Studio

[00:34] I don't know the shortcuts in other IDEs, and I won't be learning them for you :P

[00:34] Okay, so here goes

[00:35] The first thing you should do is to retrieve the latest litestep source files from http://litestep.ru.ac.za/builds/ or from http:// lsdev.litestep.net

[00:36] These source files come pre-packaged as a developer studio project

[00:36] After unarchiving the package, open the litestep project file for developer studio and build both the Debug and Release versions

[00:37] (the litestep project file is located in /ls-b24/litestep.dsw in the source archive)

[00:37] Now, note that the Debug version of the project contains *debug* version of the main modules, lsapi.dll, and litestep.edxe

[00:38] -d

[00:38] this is the key to debugging litestep

[00:38] These files contain debugging information that you can use later on when debugging your own modules

[00:38] Once you have done this, you can open up your own module's project files

[00:39] In developer studio, there is a way to make developer studio's debugger 'see' the source files for litestep

[00:40] I believe it is under Tools → Options → Directories Tab

[00:40] There, you will find a drop down list that has some options such as Library Files, Source Files, and Header Files

[00:41] Add the following directories to the corresponding category:

[00:42] - /ls-b24/litestep and /ls-b24/lsapi to both the Source and Header Files Categories

[00:43] Once that is done, hit OK to save those changes

[00:43] Note: you don't have to do this for each of your own projects, this is a one time change to Developer Studio

[00:44] Another Note: Developer Studio *might* recursively search directories, so it might be possible to just add /ls-b24/ to the Source & Header Files categories

[00:45] Now, go to your project options

[00:45] This can be done by going to Project → Settings

[00:45] Here, you will probably have to change many options depending on your project and system, but the following should work

[00:46] If you opened the Project Settings and the name of your project is selected in the tree on your left,

[00:47] you will notice that the first tab shown on the right is one that asks for which executable you would like to run as a debugging executable

[00:48] Minor Note: make sure you are editing settings for the Debug version of the project, and not the Release version

[00:48] There should be a pull down somewhere in this dialog (I believe in the upper left) that differentiates the two

[00:48] Moving on…

[00:49] For the debugging executable, put the path to the *Debug* version of Litestep you built from the sources you downloaded

[00:49] For instance, if you unarchived the sources to C:\Litestep\Source, you should have the following path in that field:

[00:49] C:\Litestep\Source\ls-b24\litestep\Debug\litestep.exe

[00:50] In the arguments field, place "-nostartup" (without quotes)

[00:50] Note: This just disables the running of startup applications

[00:51] After this is done, move on to the "Link" tab of this dialog

[00:52] I do not remember all the options available in the drop-down list on the Link page, so please bare with me during this portion

[00:52] Select the last option in the drop-down list

[00:52] I believe toward the bottom of the page, there is a text box which asks you which directories the linker should look in for library files

[00:53] in this directory, add the following directory to the box (using the example):

[00:53] C:\Litestep\Source\ls-b24\lsapi\Debug

[00:54] IMPORTANT NOTE: I am *not* sure about the above path. This path is *supposed* to be the path in which the *Debug* version of LSAPI.LIB resides

[00:56] Another Note: This assumes that you previously have been able to get your module to compile and link correctly. If you haven't done this, you need to add lsapi.lib to the files which your project links against elsewhere on the Link tab of this dialog

[00:56] Next, change the drop-down list on the top left from Debug to Release

[00:57] Once again, make these two changes to the project options

[00:57] only this time, replace Debug with Release

[00:57] For instance, the path to Litestep would be C:\Litestep\Source\ls-b24\litestep\Release\litestep.exe

[00:58] A handy trick which I like to do is the following:

[00:59] Developer Studio allows for small "scripts" to be run after the project has been successfully built

[01:00] What I like to do is have the built module copied over to a directory that is relevant to my current theme

[01:00] For instance, my step.rc points to a loadmodule in C:\Litestep\Themes\Luxo\Modules\lsxcommand.dll

[01:01] When I am debugging LSXCommand, I have Developer Studio copy newly built copy over to C:\Litestep\Themes\Luxo\Modules\lsxcommand.dll

[01:01] (Note that you can't be running Litestep at the same time as this since lsxcommand.dll would be running in memory)

[01:02] (Continuing that note - use !Quit to quit Litestep before building your project)

[01:02] MSDN can help you with figuring out the "language" the scripts use - it's quite simple

[01:02] Moving on

[01:03] What's all this mean?

[01:03] Well, if you are at the moment, NOT in Litestep and ARE in Developer Studio,

[01:03] it means that you've now got Debug versions of litestep, lsapi, the main modules, and the modules which you are about to debug

[01:04] AND, Developer Studio can find all the *source code* to these files

[01:05] This means that when the debugger hits a crash, you can see *exactly* where it crashed - be it in litestep.exe, lsapi, or another module… you can even walk the heap, examine registers, and manipulate the stack

[01:06] At this point, you should make sure that the step.rc you normally use is in the same directory as the debug version of litestep.exe (C:\Litestep\Source\ls-b24\litestep\Debug)

[01:06] also, make sure that this step.rc references almost everything via full paths

[01:07] for instance, to go back to the lsxcommand example, "LoadModule lsxcommand.dll" would not work when I run the debug version of litestep.exe - it just won't be able to find it

[01:07] that's why I make sure to reference it with the full path

[01:07] You can still use environment variables (like $ModulePath$\lsxcommand.dll)

[01:08] Just make sure that the entire thing turns out to be a full path

[01:08] With that caveat aside, you *should* be able to hit the F5 button in your project and debug litestep more efficiently!

[01:09] Thanks for listening in everyone, and I guess I should put up an edited version of this on MindJunction

[01:09] bravo

[01:09] wicked

[01:09] thanks man

[01:09] =)

[01:10] you are empowered now

[01:10] heh

[01:10] go forth and do great things

Session Close: Sat Jan 08 01:10:15 2000

lsdev/tutorials/module_debugging.txt · Last modified: 2009/01/31 20:00 by jugg
Recent changes RSS feed Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki