Running the Emulator

In a Series 60 SDK two versions of the emulator executable are available: a version built containing symbolic debugging information, and another built as a release variant. The release emulator is limited to evaluation and demonstration of applications ”it starts up considerably quicker because of the absence of the debugging information.

Both versions are called epoc.exe , but they are located in their own subdirectories. The name epoc is historical ”it was the name of the operating system prior to Symbian OS.

In normal development activities, it is usual to use the debug variant of the emulator. Depending on your choice of IDE, you may be able to run the debug version normally or in "debug mode." To be able to run the same "debug emulator" in two modes may seem a little confusing at first.

Sometimes you may want to start the emulator, locate the application and run it (as described later) simply for testing purposes. If a serious error occurs, the emulator and application will shut down in a controlled way.

Other times you may want to put a breakpoint in your code at a specific point where you think a problem exists, and then have the IDE run the emulator in "debug mode." You then locate the application and run it as before. Suitable interaction with your application will cause the breakpoint in the code to be reached. At that point, the source code will be displayed in the IDE along with all of the symbolic debug information associated with the application. Then you can use the debugging features of the IDE to step through sections of code, in a controlled manner. All the while you are able to view the application source code, data, call stack and other debug- related information displayed by the IDE to assist you in tracking down errors in code or logic.

The appearance of a typical Series 60 emulator is shown in Figure 1-3. Debugging an application under an emulator using the Microsoft Visual C++ IDE is illustrated in Figure 1-4.

Figure 1-3. Applications grid and list views of Series 60 Platform 1.2 debug emulator.

Figure 1-4. The HelloWorld application on the emulator in debug mode under the Microsoft Visual C++ IDE.

Emulator Executable Locations

For a Series 60 1.2 SDK the release build emulator is typically located under the following:

For Visual C++

 \Symbian.1\Series60\Epoc32\Release\wins\urel\epoc.exe 

For Borland C++

 \Symbian.1\Series60\Epoc32\Release\winsb\urel\epoc.exe 

For CodeWarrior

 \Symbian.1\Series60\Epoc32\Release\winscw\urel\epoc.exe 

The debug build emulator is typically located under:

For Visual C++

 \Symbian.1\Series60\Epoc32\Release\wins\udeb\epoc.exe 

For Borland C++

 \Symbian.1\Series60\Epoc32\Release\winsb\udeb\epoc.exe 

For CodeWarrior

 \Symbian.1\Series60\Epoc32\Release\winscw\udeb\epoc.exe 

The exact paths will depend on the options you choose during the installation of the SDK. In the case of the Series 60 2.x SDK the paths to the emulator will be very similar ”for example: \Symbian\Series602_0\Epoc32\release\wins\udeb\epoc.exe .

Figure 1-3 shows the Series 60 1.2 emulator. It starts up showing the Applications main menu as either a grid view or a list view.

The Series 60 2.0 emulator starts with a mock-up of the phone application, and you have to navigate to the applications menu by pressing the applications button shown in Figure 1-3. Whatever version of Series 60 Platform you are using, always specify the debug ( udeb ) version of the emulator executable as the default for development projects ”for example: \Epoc32\Release\wins\udeb\epoc.exe .

Emulator Debug Mode

When running the application in debug mode under the emulator, the source code, function call stack, variable information and so on are shown as soon as the breakpoint in the code is reached, as shown in Figure 1-4. The emulator window itself may disappear (it is minimized) if the application code is not at a point where user input is required.

Running the Emulator from a Command Prompt

To run the debug emulator from the command line, open a command prompt, change to the folder in your Series 60 SDK where the epoc.exe application is located (for example, \Symbian\6.1\Series60\Epoc32\Release\wins\udeb ) and type the following:

 epoc 

This will start the debug emulator and you can then locate and run your application, but not in debug mode. To debug an application you need to run the emulator in debugging mode and this can only be done from within an IDE. To run the release emulator enter the following:

 epoc rel 

Running the Emulator from the Visual C++ IDE

From within the Visual C++ IDE you can start the debug version of the emulator by pressing Ctrl+F5 , or from the menu use BuildExecute Epoc.exe . This will run the emulator in non-debug mode. Alternatively, you can use F5 or select BuildStart DebugGo from the menu to run the emulator in debug mode.

The first time you run the emulator for a Visual C++ project, a dialog will appear asking you to supply the name of the executable. Navigate to epoc.exe in the folder \Epoc32\Release\wins\udeb in the root of your SDK.

Running the Emulator from the Borland C++Builder 6 and C++BuilderX IDEs

You can start the debug version of the emulator using the ToolsMobile Build Tools menu option, then select Run Emulator . Alternatively you can use the RunRun menu option ( F9 ), but it will cause a project rebuild each time ”this can be a lengthy and time-consuming process! Using this option, you will need to cancel the build dialog ("Compiling") before the emulator will start up.

If you are running the emulator from C++BuilderX, use the RunDebug Project menu option or press Shift+F9 . If you wish to rebuild the project and start the emulator, select RunRun Project or press F9 .

Running the Emulator from the CodeWarrior IDE

Select the ProjectRun menu option or press Ctrl+F5 to run the emulator. Press F5 or use the ProjectDebug menu option to run the emulator in debug mode.

Locating and Running the Application

Navigate to, and select the HelloWorld application by clicking on the image of the cursor keys on the emulator fascia bitmap, or by using the PC keyboard cursor (arrow) keys. Click on the Selection button (in the middle of the cursor controls) to start the application.

Applications that do not have their own specific icon (as specified in an .aif file, detailed in Chapter 2) will be given a default icon, which looks like a piece of a jigsaw puzzle, by the system.

Under some SDK/IDEs (for example, versions of Borland and CodeWarrior), the application you have built may be located in a folder called " Other " rather than on the main desktop. If so, navigate to and select the Other folder and then open it by clicking on the Selection button. Navigate to and select the HelloWorld application and click on the Selection button to invoke the application.

The HelloWorld application will run and should appear as shown in Figure 1-5.

Figure 1-5. The "Hello World" application.

Debugging the Application

Alternatively, you could run the application on the emulator from within an IDE in debugging mode ”the procedure will vary depending on the IDE in use. Typically you would first set a breakpoint at an appropriate point in the source code.

Start the emulator in debugging mode. Since it is the application ( essentially a dynamic link library ” DLL ) that will be debugged , not the emulator itself, navigate to and run the application as described earlier in "Locating and Running the Application." The application will start up, and then execution will stop at the breakpoint you set earlier. You can the use the facilities of your chosen IDE to step through the execution of the application source code.

Further IDE Help

Further explanation of the various IDE functions is beyond the scope of this chapter, so for more details refer to the IDE help information, available through the Help menu option.

For Microsoft Visual C++ this is accessed through the HelpContents menu option, provided you installed MSDN with your IDE.

For Borland C++Builder 6 this is accessed through the Help menu option. You will find a separate HelpBorland C++ Mobile Edition Help page as well as the standard Borland help files. For C++BuilderX, select HelpHelp Topics and choose Mobile Development .

For Metrowerks CodeWarrior there is a HelpOnline Manuals menu option that contains lots of valuable information on working with Symbian OS.

Additional specific IDE information can be obtained online ”for example, for Visual C++ information go to http://msdn.microsoft.com/, for Borland C++ go to http://bdn.borland.com/ and for CodeWarrior go to http://www.metro-werks.com/MW/Develop/Wireless/.