Uzebox Developement Under Eclipse

From Uzebox Wiki
Jump to: navigation, search

Eclipse is an open source IDE for many language like Java and C/C++. Eclipse can be setup to use the GCC toolchain (compiler & debugger) in order to ease game development for the Uzebox. Specifically, you can debug and step-trace your programs live, straight on the uzem emulator.

Setup for Windows

Install the AVR Eclipse Plugin

  • In Eclipse go to menu Help->Install New Software... and click the add button
  • In the "Work with" box enter the URL: http://avr-eclipse.sourceforge.net/updatesite
  • Check the AVR Eclipse Plugin checkbox, click next twice, accept the EULA and click Finish.

Note that the plugin is required to locate the AVR-GCC toolchain and ease further setup.

Preparing the IDE

To fully use the code editor's features, setup the path to the Uzebox kernel:

  • In Eclipse select Windows->preferences
  • Expand C/C++->Build->Build Variables
  • Click Add... For variable name enter: UZEBOX_KERNEL_DIR and for variable value enter the path to the uzebox /kernel directory checked out from GIT, i.e: c:/work/uzebox/git/kernel. IMPORTANT: enter the path with forward slashes, or it will not be recognized in eclipse. Click Apply and Ok.
  • Expand C/C++->Build->Environment
  • Click Add... For variable name enter: UZEBIN_DIR and for variable value enter the path to the uzebox /bin created by the main Makefile, i.e: c:/work/uzebox/git/bin/ . IMPORTANT: enter the path with forward slashes, or it will not be recognized in eclipse. Click Apply and Ok.
  • In the project explorer, right click your project and select Properties.
  • Expand C/C++ General->Paths and Symbols
  • Under the Includes tab, insure GNU C is selected and click Add...
  • Click the Variables... button and select UZEBOX_KERNEL_DIR from the list. Click Ok.
  • Click Apply, Ok and rebuild the project

New Projects

When creating the project initially, it's important to set the MCU type in order to avoid Eclipse reporting missing symbols (like PORTA, etc.).

  • Right-click the project in the Project Explorer Pane and select Properties
  • Under AVR->Target Hardware, set the MCU type to Atmega66
  • Click Apply and close

Debugging

Create an Eclipse project from an existing project

This procedure requires that you already have a Uzebox project created either in plain C or 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)
    • As Project Type, Select "AVR Cross target Application" -> Empty project
  • Click next, uncheck "Debug" in the Configurations section then click Advanced Settings.
    • 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 or where the makefile resides. Click Apply then Ok.
  • Click next, then choose Atmega644 for processor type and leave the frequency as-is (it is not used). Click finish.
  • Right-Click your new project and 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

Add the kernel files to the project paths

Although the project will build, you will probably have errors in the IDE that include files or symbols can not be found.

  • Right-Click your new project a select Properties...
  • Navigate to C/C++ General -> Paths and Symbols
  • Select Includes tab - > Languages
  • Select "GNU C", click "Add..." button
  • In the pop-up window, check boxes "Add to all configurations" and "Add to all languages". Click "Variable...", select UZEBOX_KERNEL_DIR, Click Ok twice
  • Click Apply then Ok. Select Yes it Eclipse asks to rebuild.
  • All errors should be gone.

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, "Location" section, click the "Variables" button and select "uzem_loc" from the list. Click Ok.
    • If "uzem_loc" does not exist, click "Edit Variables"
    • Click "New". For variable name enter "uzem_loc" (without the double-quotes). For the Value, click "Browse" then locate the directory on your system that contains the uzem executable (i.e: uzem.exe).
  • In the "Location" field, append the executable name to the substitution variable such as: ${uzem_loc}/uzem.exe
  • 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). The -d switch will start the gdb server in uzem.
  • 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"
  • Look at the bottom of the pane for the string "Using GDB (DSF) Create Process Laucher" or "Standard Create Process Laucher".
    • If you see "Using GDB (DSF) Create Process Laucher", click the "Select Other..." link, then check box "Use configuration specific settings.
    • Select "Standard/Legacy Create Process Laucher", click Ok.
  • Click the debugger tab
  • In the "Debugger" drop-down, choose "gdbserver"
  • 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 the "GDB debugger" field 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" ("Launch mode" drop-down should be "debug") 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

Debugging your program

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! If you don't see the entry in the list, you will have to run it a first time from the Run->Run Configurations dialog.

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 that perform computations but don't return a value. In this case you may want to set the optimization to -O0 instead of -Os in the makefile. But beware, this will make your code much bigger and slower.


External Links

TODO: add screen shots of the steps