Uzebox Developement Under Eclipse

From Uzebox Wiki
Jump to navigation Jump to search

Windows

Debugging

Create an Eclipse project from an AVR Studio project

This procedure requires that you already have a Uzebox project created with AVR Studio.

  • Launch Eclipse and select your workspace location. If it's the first project you create, choose the "trunk" folder were you checked out the sources from SVN.
  • Select File->New->C Project
  • Enter a project name, the same name as the AVR Studio's project's folder
  • Uncheck the "Use default location" check box and browse to your AVR Studio's project folder (i.e: Megatris)
  • Click next twice, then choose Atmega644 for processor type and 28636360 as frequency. Click finish.
  • Right-Click your new project a select Properties...
  • Click C/C++ Build from the left property pane
  • Uncheck the "Use default build command" check box
  • Uncheck the "Generate Makefiles automatically" check box
  • In the build location section, click the "Workspace..." button and select your new project and then the "default" folder where the makefile resides.
  • Click apply, your project should build normally

Setting up Eclipse for Debugging

These settings are made for Eclipse IDE for C/C++ developers (Build id: 20100218-1602). More recent version may slightly vary. The setup involves creating a launch group that will, in turn, start the emulator in debug mode with your game and then start the gdb client debugger. We will use Megatris as an example.

Create the emulator launch configuration

  • Open menu Run->External Tools->External Tools Configuration...
  • Press the New button to create a new launch configuration
  • Name the configuration like "Run in emulator (Megatris)"
  • In the "Main" tab, under "location" browse to uzem.exe (i.e: C:\uzebox\trunk\bin\uzem.exe) or ${workspace_loc}\bin\uzem.exe if your workspace point to the trunk folder.
  • In working directory, browse to the "default" directory (i.e: ${workspace_loc:/Megatris/default})
  • In "Arguments", enter the "-d" switch followed with your game's HEX file (i.e: -d Megatris.hex)
  • Click apply

Create the GDB debugger client configuration

  • Open menu Run->Debug Configuration...
  • Select the "C/C++ Application" group in the left panel and press the new button
  • Name your configuration such as "Megatris Debug configuration"
  • Choose you project. "Build configuration" should be set to "Debug" and "C/C++ Application" should point to "default\megatris.elf"
  • Click the debugger tab
  • In the "Debugger" drop-down, choose "gdbserver Debugger"
  • Uncheck "Stop on startup" if you do not want the debugged to stop in main() when you start debugging
  • Under the debugger options, in the "Main" tab, set GDB debugger to "avr-gdb" or browse to your local copy (i.e: C:\winavr\bin\avr-gdb.exe)
  • Clear the field "GDB command file"
  • Enter the "Connection" tab
  • For type choose TCP, set hostname to "localhost" and port to "1284"
  • If you get a red "X" with something mentionning a process launcher, click "select other..." , check "use configuration specific settings" and choose the "standard create process laucher"
  • Click Apply

Create the launch group

  • Within the same Debug Configurations window, select "Lauch Group" in the left panel and click the new button
  • Name you configuration like "Debug on uzem (Megatris)"
  • In the right panel, click the "Add..." button
  • In the "Launch mode" drop-down, select "run"
  • Expand "Program", select "Run in emulator (Megatris)" and click Ok
  • Click "Add..." again
  • Expand "C/C++ Application", select "Megatris Debug configuration" and click Ok
  • Click Apply

Makefile parameters

To be able to fully use the uzem GDB debugging features (like variable visualization) your must set these debugging options in the Makefile:

ASMFLAGS += -g3 -Wa,-gdwarf2

CFLAGS += -g3 -gdwarf-2


Click the debug icon's little down arrow and select "Debug on uzem (Megatris)" from the list. Uzem will launch your game, then the debugger will start. You are now ready to debug!

From here you can set breakpoints (I personally, can't see any variables in the variables tab, but I can see the values of all the CPU registers, which is super useful);

Terminating the debugger will close the session, and the emulator.

Beware the optimizing compiler! Compiler optomizations will often, strip out of reorder code you have written. This can cause strange behavior in the debugger if you set a breakpoint to a piece of code that was removed, or want to check the value of a variable that was removed. This is especially bad if your fond of writing test functions like I am that perform computations but don't return a value.

You should do one of two things. 1.) set the optimizations switch in the MakeFile to -O0 to build without any optimizations. In my case, I could not do this, building without optimizations made my code too bug to fit on ROM. So I had to go with method 2.) make sure your code "does" something with the variable you want to look at.

I'm sure this is not the optimal work flow. Its probably possible to automate this by having eclipse copy your hex file to the right directory, and launch the emulator in debug mode for you. Experiment with your debugging environment and please update this article with any tips or tricks you learn!


External Links

TODO: add screen shots of the steps