Uzebox Developement Under Eclipse: Difference between revisions

From Uzebox Wiki
Jump to navigation Jump to search
No edit summary
(Added config of mcu type)
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
==Windows==
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 [http://sourceforge.net/projects/winavr/files/ latest WinAVR] -- Currently WinAVR-20100110
* Install the [http://sourceforge.net/projects/winavr/files/ latest WinAVR] -- Currently WinAVR-20100110
* Install [http://www.eclipse.org/cdt/downloads.php Eclipe CDT (C Developement Toolkit)] -- Currently 6.0.x. Be sure to install the GDB options.
* Install [http://www.eclipse.org/cdt/downloads.php Eclipe CDT (C Developement Toolkit)] -- Currently 6.0.x. Be sure to install the GDB options.
Line 5: Line 7:
* If using the AVRISP mkII under Windows XP, you will also need [http://sourceforge.net/projects/libusb-win32/files/ libusb-win32 drivers]. '''Important''': *do not* install on Vista or Win7, some have reported crashes and BSODs.
* If using the AVRISP mkII under Windows XP, you will also need [http://sourceforge.net/projects/libusb-win32/files/ libusb-win32 drivers]. '''Important''': *do not* install on Vista or Win7, some have reported crashes and BSODs.


==Developing==
==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 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:
To fully use the code editor's features, setup the path to the Uzebox kernel:
* In Eclipse select Windows->preferences
* In Eclipse select Windows->preferences
* Expand C/C++->Build->Build Variables
* 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 checked out from SVN, i.e: c:/work/uzebox/trunk/kernel . '''IMPORTANT''': enter the path with forward slashes, or it will not be recognized in eclipse. Click Apply and Ok.
* 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.
* In the project explorer, right click your project and select Properties.
* Expand C/C++ General->Paths and Symbols
* Expand C/C++ General->Paths and Symbols
Line 15: Line 26:
* Click the Variables... button and select UZEBOX_KERNEL_DIR from the list. Click Ok.
* Click the Variables... button and select UZEBOX_KERNEL_DIR from the list. Click Ok.
* Click Apply, Ok and rebuild the project
* 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==
==Debugging==


===Create an Eclipse project from an AVR Studio project===
===Create an Eclipse project from an existing project===
This procedure requires that you already have a Uzebox project created with AVR Studio.
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.
* 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
* Select File->New->C Project
* Enter a project name, the same name as the AVR Studio's project's folder
** 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)
** 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.
** As Project Type, Select "AVR Cross target Application" -> Empty project
* Right-Click your new project a select Properties...
* 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
* Click C/C++ Build from the left property pane
* Uncheck the "Use default build command" check box
* Uncheck the "Use default build command" check box
Line 32: Line 54:
* In the build location section, click the "Workspace..." button and select your new project and then the "default" folder where the makefile resides.
* 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
* 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===
===Setting up Eclipse for Debugging===
Line 41: Line 73:
* Press the New button to create a new launch configuration
* Press the New button to create a new launch configuration
* Name the configuration like "Run in emulator (Megatris)"
* Name the configuration like "Run in emulator (Megatris)"
* Click the "Variables" button and select "uzem_loc" from the list. Click Ok.
* 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"
** 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).
** 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 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 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)
* 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
* Click apply


Line 54: Line 86:
* Name your configuration such as "Megatris Debug configuration"
* 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"
* 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
* Click the debugger tab
* In the "Debugger" drop-down, choose "gdbserver Debugger"
* 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
* 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)
* 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"
* Clear the field "GDB command file"
* Enter the "Connection" tab.
* Enter the "Connection" tab.
** If you don't see a "Connection tab", look at the bottom of the pane for the string "Using GDB (DSF) Create Process Laucher".
** Click "Select Other", then check box "Use configuration specific settings.
** Select "Standard Create Process Laucher", click Ok.
* For type choose TCP, set hostname to "localhost" and port to "1284"
* 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"
* 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"
Line 74: Line 107:
* Expand "Program", select "Run in emulator (Megatris)" and click Ok
* Expand "Program", select "Run in emulator (Megatris)" and click Ok
* Click "Add..." again
* Click "Add..." again
* Expand "C/C++ Application", select "Megatris Debug configuration" and click Ok
* Expand "C/C++ Application", select "Megatris Debug configuration" ("Launch mode" drop-down should be "debug") and click Ok
* Click Apply
* Click Apply


Line 84: Line 117:
CFLAGS += -g3 -gdwarf-2
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!  
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);
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);

Latest revision as of 00:00, 9 September 2018

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