User:PhoenixTank/Setting up Eclipse for Wii Development

From WiiBrew
Jump to navigation Jump to search

The Eclipse Platform is a modern cross-platform & open source IDE with a built-in debugger GUI and support for several programming languages via plug-ins. Plug-ins can also be used to extend functionality. For many, Programmer's Notepad (PN) and Insight will suffice, but others may find the combination a little out of date. This wiki will guide you through each stage in the setup process, but assumes that you are using Windows, have already installed devkitPro (including devkitPPC) and are relatively familiar with the concepts of developing Wii Homebrew. Adapting for Linux and other platforms should not be difficult.

About

I needed a development environment to use while learning C/C++, and Eclipse fit my needs. The more I used Eclipse, the more I tired of using PN, and began to look for the means to develop homebrew from within Eclipse. Unfortunately for me, there was no solid set of instructions available, and the nearest thing I found was a French guide for PSP development in Eclipse. This guide is the result of my search for information, and has been pieced together from the web, or simply learnt by experimentation, and I very much hope that it is of use to others ~ PhoenixTank | talk | contribs |

Requirements

Getting Started

  • Extract the eclipse zip to a directory of your choice. I recommend C:\eclipse\ N.B. There is no installer. Create yourself a shortcut to C:\eclipse\eclipse.exe, for convenience.
  • Fire up Eclipse, and if all goes to plan you should be greeted with a box asking you to select a workspace. Pick wherever you like, but for the sake of this guide, we will choose C:\WiiDev\projects\. You should choose to make this the default if you aren't interested in using Eclipse for any other development projects.
  • You are greeted with the Welcome splash screen. There are some tutorials on using Eclipse, but leave them for now. Head to File > New > C++ project (Or C Project, if you prefer, but this guide will reference C++ primarily)
  • In the dialogue box, name your project "HelloWorld" and chose Makefile ¬ Empty Project, then hit Finish.
  • Head to the workbench by clicking the far right arrow icon.
  • You now see the main IDE with Project Explorer, File Editor, Console and others panes.
  • There will be an error and a probably warning in the problems pane. Don't worry about them for now, and open C:\devkitPro\examples\wii\template\ in Windows Explorer. Select the source folder and makefile, and copy them to clipboard. Return to Eclipse, right click the HelloWorld project in Project Explorer, and paste. The files should now be a part of your project.
  • Head to Projects > Properties, or do the same from the right click menu of HelloWorld. Click "C/C++ Build" then choose the "behaviour" tab. Here, change the value of "Build (Incremental Build)" to "build" or simply blank, then hit OK. Alternatively, use a custom make target instead of the built in build.
  • With default settings, Eclipse will immediately build your project. The error should no longer be there to pester you.
  • If you have a warning like: Error launching external scanner info generator (gcc -E -P -v -dD C:/WiiDev/projects/.metadata/.plugins/org.eclipse.cdt.make.core/specs.cpp) then the easiest way to fix this is to add C:\devkitPro\devkitPPC\powerpc-gekko\bin; to the start of your path environment variable.

Custom Make Targets

On the right hand side of Eclipse you have a panel containing the script outline and make targets. This is useful for adding specific make commands to run and this is equivalent to the project tools in Programmer's Notepad. Build and Clean are already built in to the project menu, but custom make targets are useful. As an example, we are going to set up a run/wiiload shortcut. This assumes that you are still using the same makefile & template.c

  • Bring the Make Target panel into focus if it is not already, then click the folder with a slash through it (Hide empty folders).
  • Right click the project name and choose "Add Make Target".
  • Enter Wiiload (or another name) into the first box, and "run" in the second box and hit create.

Provided you have wiiload set up correctly, double clicking this will allow you to easily send your most recently compiled .dol/.elf to your Wii. Your makefile entry for wiiload should look something like this, if not set up already: 

run: $(BUILD) 
	wiiload $(TARGET).dol

This is the same as the standard makefile from the template, but the $(BUILD) dependency is added simply to be sure we have a compiled version before trying to send our .elf/.dol file.

More Settings

Setting Environment Variables

Head to Control Panel, then (using classic view) System. Click the Advanced tab, then Environment Variables. After making changes here you may need to restart.

WIILOAD

This variable allows the wiiload program to send your .dol/.elf file over the network to be loaded by HBC (or other supporting loaders). Far simpler than removing a SD card and updating the file every time you want to test. Alternatively, there are GUI versions of Wiiload that do not require the variable to be set.

Under System Variables, add a new variable named "WIILOAD", with the value "tcp:xxx.xxx.xxx.xxx" where "xxx.xxx.xxx.xxx" signifies the IP of your Wii. For me, the value is "tcp:192.168.0.5", and thanks to my router, I can force my Wii to use that IP every time it connects (Look for something like "Address Reservation" in the router settings)

Path

This variable contains a list of paths, separated by a semi colon (;). The length and contents will vary but a fresh Windows XP install looks something like this: 

%SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem

The devkitpro installer should add "c:\devkitPro\msys\bin;" to the start, but you will likely have other paths added by other programs too. Be careful not to remove any of the existing paths.

Alternatively, for a less error-prone setup, you can use Path Editor, which allows you to see your individual path entries more clearly. Useful if you've already got a bulky path variable.

Enabling Auto Complete

Unfortunately, auto complete (known as "content assist" in Eclipse), needs a helping hand in order to work correctly. Open your project's properties, head to C/C++ General, then Paths and Symbols. You then need to add the following paths, making sure to select "Add to all languages". Note that the folder names you need may vary, such as the 4.2.4 being higher or lower, and of course you need to correctly alter the paths to point to the location that you installed devkitPro to. 

C:\devkitPro\libogc\include\
C:\devkitPro\devkitPPC\lib\gcc\powerpc-gekko\4.2.4\include\
C:\devkitPro\devkitPPC\powerpc-gekko\include\
C:\devkitPro\devkitPPC\powerpc-gekko\include\c++\4.2.4\
C:\devkitPro\devkitPPC\powerpc-gekko\include\c++\4.2.4\powerpc-gekko\

If you have subfolders within your project that contain source files, you may also need to add a path to your source folder. This should set up the majority of the locations for auto complete to work with. Default triggers are "." , "->" and "::" , but ctrl + space will also bring up auto complete.

Some Preferences

Eclipse is quite customisable, but the large amount of settings can be a struggle to wade through, in order to find what you are looking for. I have some personal preferences that may be of interest to others.

From Window > Preferences:

  • General ¬ Workspace. "Build automatically" unchecked, "Save automatically before build" checked.
  • C/C++ ¬ Code Style. I use BSD/Allman, but the other most common styles are there too.
  • C/C++ ¬ Editor ¬ Content Assist. Drop the delay to 200 ms.
  • C/C++ ¬ New CDT project wizard ¬ Makefile Project : Behaviour tab. Uncheck "Build on resource save"

Debugging

The Eclipse CDT has a nice integrated debugging GUI (which is half of the reason for this tutorial), but unfortunately does not support remote C/C++ applications "out of the box". To get around this Eclipse needs to be extended, and we are lucky enough to have a plug-in available to us. [3]

Zylin Plug-in

From Eclipse, head to Help > Software Updates.

  • On the Available Software tab click "Add Site..." , enter "http://opensource.zylin.com/zylincdt" and Hit OK. (You may need to add the zylin site via the "manage sites" section)
  • Next, check the box in the list next to "http://opensource.zylin.com/zylincdt" and hit Install... It will now go through the motions of downloading relevant files, and another box will pop up, letting you confirm the changes.
  • Hit next, accept the terms, then finish. It will install, and ask you if you want to restart Eclipse, and I suggest you do.

Debug Settings

In order to debug a Wii application, you have to connect your computer based debugger to it somehow. You can use a USB Gecko or a libogc wifi patch. Either way, the base setup is outlined here first.

  • Head to Project > Properties then C/C++ Build ¬ Settings.
  • On the Binary Parsers tab, check "GNU Elf Parser" and move it to the top of the list.
  • Select it and enter
C:\devkitPro\devkitPPC\bin\powerpc-gekko-addr2line.exe

in the addr2line field, and 

C:\devkitPro\devkitPPC\bin\powerpc-gekko-c++filt.exe

in the c++filt field.

  • Next, head to Run > Debug Configurations. Select "Zylin Embedded debug (Native)" and create a new configuration.
  • Name it HelloWorld GDB or other relevant name, but bear in mind that it will need to be unique across all Eclipse projects.

From here, I'll explain settings tab by tab, as there are several ways to achieve the same setup.

Main tab

  • Specify your project if it is not filled in for you already.
  • In C/C++ Application you can specify your project's .elf (not.dol) to be used by GDB as a symbol file. If your project is currently compiled you should be able to use "Search Project". An absolute path to the relevant .elf file will also work fine.
  • Alternatively you can specify the .elf in the commands tab, with a symbol-file command, instead of here.

Debugger tab

  • GDB debugger - enter the path "C:\devkitPro\devkitPPC\bin\powerpc-gekko-gdb.exe". This is required.
  • GDB command file - As an alternative to the commands tab, you can specify an external file containing GDB commands to run. Blank the field if you aren't going to use it. This may be useful if, for example, your Wii can't be assigned a static IP. Using a single command file that is updated to target the new Wii IP is easier than editing the config in each project.
  • Protocol - Keep it as "mi". I haven't tested for any differences yet.
  • "Verbose console mode" and "Use full file paths to set breakpoints" are pretty self-explanatory.

Commands tab

  • If you are not using an external gdb command file, "Initialize" should contain your target command, which varies depending on your debug method (see relevant example below).
  • If you did not specify a path to your project .elf in the C/C++ on the main tab, you also need a "symbol-file" command, like so:
symbol-file C:/WiiDev/projects/HelloWorld/HelloWorld.elf

The path does need to use forward slashes.

  • I don't personally use "run" for any gdb commands, but it probably has a use for more seasoned developers.

Source tab

By default your project path is added, but you can add other source folders for GDB to use if required.

Common tab

  • This tab allows you to save the configuration as an embedded part of the project (local) or as a shared file that can be used by other projects (shared).
  • You can add the debug configuration as a favourite and change the console encoding.
  • If you don't want to be able to use the Eclipse console to enter GDB commands, you have the option to disable it, but I'd recommend that you leave it enabled.
  • You can also have an external file process the output from GDB.

Debug Method

USB Gecko

I cannot provide instructions for this section as I have no USB Gecko (yet), but the instructions here should provide most of the relevant information.

Wifi Debugging Patch

AKA "The poor man's USB Gecko". This takes a little work to implement, but at a total cost of £0, who can complain?

Setting up the patch
Setting up example for debugging

By this point we have the template compiling nicely and our Wii sends greetings to the world, but to we have to follow some steps to actually get it working:

  • In your makefile's LIBS section add -ldb before -logc . For your CFLAGS/CXXFLAGS, change -O2 to -O0 for any debug builds.
  • You need to add "#include <debug.h>" in template.c

Debugging can be started by adding these lines to your application's code: 

DEBUG_Init(GDBSTUB_DEVICE_WIFI, 8000); // Port 8000 (use whatever you want)
_break();

There doesn't seem to be an issue with where you place it, but I'd advise that it is shortly after video is initialised and the console is ready. This allows the Wii-side of the debugger to output text: 

Getting Wii IP adress.
Wii IP address: 192.168.0.5
Port: 8000
Waiting for debugger to connect...Debugger connected.

When using the template and other applications, know that using 

printf("\x1b[2;0H");

or similar to position the console cursor is going to cause new output to overwrite the previous debugger output.

Example GDB target command
target remote 192.168.0.5:8000

A GDB command like the one above is needed in either your external GDBinit file (debugger tab), the internal Eclipse config (commands tab) or can be typed in to the GDB console manually. Without this, GDB doesn't know what to attach to.

Credits

To Do

  • Link to a helpful guide to using GDB (recommendations welcome)
  • New Wii Homebrew Project Wizard Plug-in (I'll need to learn Java, unless someone else steps up)
Retrieved from "https://wiibrew.org/w/index.php?title=User:PhoenixTank/Setting_up_Eclipse_for_Wii_Development&oldid=58139"