Building from the Command Line
Open a command prompt and change to the drive/folder that contains your Series 60 SDK. Navigate to the folder where the project definition (helloworld.mmp) and component description (bld.inf) files are located—for example:
for a Series 60 2.x project
for a Series 60 1.x project
After a second or two this command completes without any visual output. It uses the bld.inf and helloworld.mmp files to generate a new file: abld.bat. This command file is always generated in place, as required. Unlike the bld.inf and .mmp files, abld.bat is not portable between different IDEs and should never be edited by hand.
To compile and link the project, type:
abld build wins udeb //for Visual C++
abld build winsb udeb //for Borland C++
abld build winscw udeb //for CodeWarrior
The abld command will build the project (in other words, compile and link) for the Series 60 emulator (the wins, winscw or winsb variant) with debugging (udeb—Unicode debug) information included in the binary executable.
Building from an IDE
Projects, such as our example HelloWorld application, normally are built and run from within an IDE, so we need to create IDE-specific project files from the bld.inf and HelloWorld.mmp files. For Visual C++ this must be performed from the command line, using tools supplied by Symbian. For Borland and CodeWarrior this is optional, since both IDEs can import either the bld.inf or .mmp file, respectively, to create the IDE project files.
When working from the command prompt it may be necessary to create the abld.bat file if it does not exist already, or recreate it if the .mmp file or bld.inf file has changed. At a command prompt you create the abld command file by typing:
Building Using Microsoft Visual C++IDE
Open a command prompt and navigate to the drive/project folder for the HelloWorld project and then type:
abld makefile vc6
This will create project and workspace files (helloworld.dsp and .dsw files) suitable for Microsoft Visual C++. They will be located under the \Epoc32\Build sub-folder structure; the complete path will depend on the location of your SDK, for example:
By opening the workspace file (helloworld.dsw) in Visual C++, you can compile or link the application, either by pressing F7 or via the IDE menu option, Build|Build HelloWorld.app.
Building Using Borland C++IDE Builder 6
If you are using Borland C++Builder 6 Mobile Edition, which is based on C++Builder 6 Personal Edition with the Mobile plug-in, you can simply import the bld.inf file for the HelloWorld project into the IDE. Use the File|New|Other menu option. Then select the Mobile tab in the resulting dialog: Import Mobile Application. Browse to the location of the component description (bld.inf) file and open it.
Use Ctrl+F9, or Project|Make from the menu, to build. To build and run, use F9 or Run|Run from the menu. Note that F9 or Run|Run will cause a project rebuild each time! To just run the emulator, use Tools|Mobile Build Tools|Run Emulator. You may be prompted to save a number of project-related files, for example, Borland project (.bpr), Borland project group (.bpg) files. These files will be saved in the same folder as your bld.inf file.
It is also possible to execute individual abld commands and run other SDK tools such as aifbuilder and sisar from the Tools|Mobile Build Tools menu. These tools are described in Chapter 2.
Building Using Borland C++BuilderX
When using any of the commercial C++BuilderX products, you can simply import the bld.inf file for the HelloWorld project into the IDE.
Use File|New and click the Mobile C++ tab in the Object Gallery. Select Import Symbian C++ Project. Select the correct Series 60 SDK from the drop-down list, browse to the location of the project bld.inf file. Press the Next tab, give the project a name, press the Finish tab and the project will open. Press Ctrl+F9 or select Project|Make Project. To run, Press F9, or select Run|Run Project or use the toolbar tab to Make and Run the project.
Building Using CodeWarrior IDE
If you are using Metrowerks CodeWarrior for Symbian (Personal v2.5, other editions may vary slightly), you can simply import the HelloWorld.mmp file using the IDE menu option, File|Import Project from .mmp File.
This runs a project conversion wizard. Select the SDK to use with this project, select (or browse to) the .mmp file, and select a platform of WINSCW (or all by leaving it blank). The build variant will default to UDEB. Use F7 or Project|Make from the menu to build the project.
The CodeWarrior Project files (.mcp, .xml, .resources and .pref files) are created automatically in the same directory as the HelloWorld.mmp file.
Alternatively you can create a CodeWarrior IDE project from the command line. To do this, run bldmake bldfiles as described; then, to generate a CodeWarrior IDE project, use:
abld makefile cw_ide
This creates an importable project file HelloWorld.xml in the directory:
You can now use CodeWarrior to import this file and to generate a native project (.mcp) file. Choose the File|Import Project menu option, select the HelloWorld.xml file, and choose a name for the project (such as HelloWorld again). CodeWarrior will now generate and load the project, which you can build, run, debug and so on, using the normal IDE commands.
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.
Emulator Executable Locations
For a Series 60 1.2 SDK the release build emulator is typically located under the following:
For Visual C++
For Borland C++
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.
The debug build emulator is typically located under:
For Visual C++
For Borland C++
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:
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:
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:
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:
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 Build|Execute Epoc.exe. This will run the emulator in non-debug mode. Alternatively, you can use F5 or select Build|Start Debug|Go 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 Tools|Mobile Build Tools menu option, then select Run Emulator. Alternatively you can use the Run|Run 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 Run|Debug Project menu option or press Shift+F9. If you wish to rebuild the project and start the emulator, select Run|Run Project or press F9.
Running the Emulator from the CodeWarrior IDE
Select the Project|Run menu option or press Ctrl+F5 to run the emulator. Press F5 or use the Project|Debug 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.
Tip: 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 Help|Contents 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 Help|Borland C++ Mobile Edition Help page as well as the standard Borland help files. For C++BuilderX, select Help|Help Topics and choose Mobile Development.
For Metrowerks CodeWarrior there is a Help|Online 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/.