Carbide.c++: Setting up On Target Debugging

This tutorial will guide you through the configuration of your carbide.c++ IDE to enable on-target debugging. In order to have it working, you will need the following:
  a S60 3rd Edition handset (in this example, we will use a Nokia 3250),
  a Carbide.c++ Pro or Developper IDE (this will NOT work with the Express version) with a S60 3rd edition SDK properly configured...
  a Bluetooth dongle or the USB cable that comes with your mobile (Nokia DKU-2 or similar).

If you want to use Bluetooth, then you have to use the Widcomm Bluetooth driver that ships with your dongle, not the Microsoft one (we will not cover how to configure this in this article, but if you are running a Windows XP SP2 system, then you may need to google around or check your dongle documentation to configure this properly). USB is easier to configure (and quicker if you use a big project).

Step 1 - Intall the metroTRK on the device

This step has to be done only once for each device you need to debug on. Open a file explorer windows on your desktop and point it to (actual name may differ with future release of carbide):

Install the S60_3_0_App_TRK_2_6.sisx file to your device. A TRK application should have been added in your custom application directory.

Step 2: HelloworldBasic example fix

In this tutorial, we will use the HelloworldBasic example that is located in the S60Ex directory of the S60 SDK. Unfortunately, as most other examples delivered with any Nokia SDK, it does not compile directly with Carbide. Let's then fix a couple of things.

First fix the pkg files into sis directory. Go to :

C:\Symbian\9.1\S60_3rd_MR\S60Ex\helloworldbasic\sis

And :
  if you don't use the RVCT compiler (this is probably the case if you don't know what RVCT is), you can remove all the pkg files but helloworld_gcce.pkg.
  replace the "..\..\..\epoc32" strings in the remaining pkg file by the absolut path to your SDK location (should be "c:\symbian\9.1\S60_3rd_MR\epoc32").
  add also an absolut location in front of the backup_registration.xml file (should be "C:\Symbian\9.1\S60_3rd_MR\S60Ex\helloworldbasic\sis\").
  duplicate the helloworldbasic_gcce.pkg file into helloworldbasic_gcce_udeb.pkg
  edit the new helloworldbasic_gcce_udeb.pkg and replace the occurences of urel by udeb (there should be only one).

Then do a first build from the command line. This allows the toolchain to generate the icons and other options that may not be processed correctly by Carbide:
  Open a DOS command
  go to the place where the bld.inf file is located. In our example, this is

C:\Symbian\9.1\S60_3rd_MR\S60Ex\helloworldbasic\group

  check that the proper SDK is selected by default using the devices command. If you are using the same configuration as mine, then the proper line to enable the S60 3rd MR SDK is:

devices -setdefault @S60_3rd_MR:com.nokia.s60

  compile the project using the following commands:

Step 3 - Project Import

Select the File | Import... menu to import your project into the Carbide IDE. In our example, we are using the S60 3rd Edition MR (Maintenance Release) SDK and the HelloWorldBasic example:

Then select the SDK and target you want to use. If you do not know which buid configuration to use the right choices are probably:
  the Emulator Debug option : this allows you to compile and debug using the emulator on your desktop.
  the Phone (GCCE) Debug option: this is the configuration to use for on-target debugging so the only mandatory choice in your example.
  the Phone (GCCE) Release option: this is the choice for deploying your application on the phone but with no debugging capabilities (not selected in our example but you'll probably need it).

Sis file might not be added to your project. You can do this manually by adding the content of the sis directory to it. Select File | New | Folder from the Carbide menu. Specify sis as the folder name, and, in the Advanced>> section, check the "Link to folder in the file system" box and select the sis directory of the helloworld example:

Now, we have to specify the sis file we want to use to debug.

  make sure that the current target is set to Phone (GCCE) Debug. If not, select it from the Project | Active Build Configuration menu:

  open the debug options window with Run | Debug... and go to the Installation tab
  check that the selected sis file is the one that contains the UDEB binaries. If you have followed our example so far, simply select the helloworldbasic_gcce_udeb.sis file instead of the helloworldbasic_gcce.sis:

Step 4: Application Compilation

You are now finished with the dirty work. Modify the application if you want to add your own stuff. To begin, let's just add a breakpoint in the CHelloWorldBasicAppUi::HandleCommandL() function, when the EHelloWorldBasicCommand1 is selected:

Compile the application with Project | Build Project and check that everything goes well.

Step 5: TRK and Phone Configuration

Before really being able to start the debug, you need to establish a serial link between the device and your desktop. I am using bluetooth to do this :
  on your mobile, start the TRK application.
  the TRK shall perform then a search for surrounding bluetooth devices. Stop it once your desktop is found and select it (here, my desktop is called Nikopol):

This might popup some pairing request on the desktop computer if the mobile of your application are not already paired and - possibly - a second confirmation similar to the screenshot below to allow the serial connection. Check the option on the bottom of the window to avoid it the next time you connect the two (sorry for the french screenshot....):

Once accepted, the TRK screen should confirm the connection is OK. Setup from the mobile side is finished:

Step 6: Debugger Start

Before getting back to carbide, let's get the COM port value to use from the desktop side: right click on the Bluetooth icon in your system tray and select the Advanced Configuration option, then go to the Local Services tab. The display should be similar to the window below:

Note the value associated to the bluetooth serial link (here: COM10).

Now, we can start the serious stuff. Rebuild the application if needed, using the Project | Build Project command and start the debugger (F11 or Run | Debug). A first popup window appear, giving you the choices for the different TRK configuration:
  the App TRK is available in Carbide.c++ Pro and Developer edition. It allows to debug application installed on a production phone (the phone you can buy from your dealer)
  the System TRK is only available in the Carbide.c++ Pro edition and won't work on standard phones, but only on boards and prototypes. It allows to debug some system component in addition to applications.

Select the App TRK:

Then you will be asked to select a COM port. Select the port you have got from the bluetooth advanced configuration window:

Carbide will then upload your application to the phone and start it. By default, the debugger stops at the beginning at the E32Main function (the entry point of your application). This is still time to add a few breakpoint before continuing:

Resume the execution (F8) and the application shall show up on your phone:

Select the Options | Hello entry in the application.... The debugger should come up. You can now execute your the HandleCommandL step by step, see the content of the variables, the execution stack....

That's it... you are now debugging an application that runs on your phone. :-) :-) :-)