Borland C++ Mobile Edition for Series 60

Release Notes

________________________

This file contains important supplementary information on installing and using Borland C++ Mobile Edition for Series 60. We recommend that you read this file in its entirety.

________________________

Contents

7      Installation Requirements

7      Installing Borland C++ Mobile Edition for Series 60

7      Uninstalling Borland C++ Mobile Edition for Series 60

7      Using the Borland C++ Mobile Edition Plug-in

7      Using the Emulator

7      Deploying Mobile Applications

7      Sample Applications

7      Working at the Command Line

7      Known Issues

________________________

Installation Requirements

Borland C++ Mobile Edition for Series 60 includes the Borland Mobile Edition plug-in (also referred to as the plug-in); the Series 60 SDK 0.9, Nokia Edition; JRE 1.3.1; and Perl 5.6.1. The Borland C++ Mobile Edition plug-in is an add-on to C++Builder that allows you to import, write, build, debug, test, and deploy applications for mobile devices. You use the API from the Series 60 SDK 0.9, Nokia Edition (hereafter referred to as the Series 60 SDK) within the applications. Borland C++ Mobile Edition for Series 60 provides an integrated development environment and the Series 60 SDK provides the classes and member functions that you use in your mobile applications.

The main installer for Borland C++ Mobile Edition for Series 60 is located in the Install folder. Note the following:

7      You must be logged in as a user with Administrator capabilities to run the installation.

7      The installation detects whether or not C++Builder 6 is installed on your system. If you already have it installed, you do not need to reinstall C++Builder 6.

7      The installation includes C++Builder 6 Update #4 (which contains all prior updates).
Update #4 is required to build any mobile applications.

7      If you previously installed Borland C++ Mobile Edition for Series 60, you need to uninstall it completely before proceeding (see the Uninstalling section later in this document).

Two versions of the Borland C++ Mobile Edition for Series 60 product are available:

7      One includes C++Builder 6 (Nokia edition)

7      One does not include C++Builder 6 (For C++Builder 6 customers)

If the version you received does not include C++Builder 6, you need to install it before installing Borland C++ Mobile Edition for Series 60. You can tell if your version has C++Builder if it includes the BCB6_MobileEdition folder.

________________________

Installing Borland C++ Mobile Edition for Series 60

Note: This release has only been tested on the Professional Editions of Windows XP and Windows 2000. It is recommended that you install it on these platforms.

Installing Borland C++ Mobile Edition for Series 60 includes the option to install Borland C++ Mobile Edition (C++Builder). If C++Builder 6 is already installed on your system, the install will detect it and it will not be installed by default.

To install Borland C++ Mobile Edition for Series 60:

1. Click Installsetup.exe to install Borland C++ Mobile Edition for Series 60, the plug-in, Series 60 SDK, JRE 1.3.1 (if not installed), Perl 5.6.1 (if not installed) and all related tools. You can choose which tools you want to install.

Note: If your distribution does not have an Install folder, click setup.exe in the Series 60 folder to begin your installation.

2. Follow through the installation.
The installation first installs Borland C++Builder (if included and not installed), then installs the Series 60 SDK to C:nokia_symbian6.1, installs the plug-in, then JRE, and Perl.

Note: If C++Builder is already installed but without the required update, only the update is applied.

During the Series 60 SDK installation, the EPOCROOT and Path environment variables are set making the Series 60 SDK the default tool. At the end of the Series 60 SDK installation, you will see a message saying that Symbian OS 6.1 tools are your default tools. If you are using multiple SDKs for mobile development, you will have to change your Path variable when you want to use an alternate SDK.

Note: Installing other SDKs may also reset the Path variable or EPOCROOT so you will need to make sure that they are set appropriately for using the Series 60 SDK.

If you prefer to install JRE and Perl separately, you may do so, by navigating to the appropriate folder and clicking on the installer located there. If you install Perl to a directory other than the default location or have more than one version of Perl on your system, you should ensure that the path to Perl 5.6.1 is correct (From the IDE, choose Tools|Mobile Options and check the path on the Path tab).

Installing Borland C++ Mobile Edition with Metrowerks CodeWarrior

Installing Borland C++ Mobile Edition for Series 60 on a system with Metrowerks CodeWarrior with Series 60 or Symbian SDKs already installed on it may cause problems to occur when building Series 60 or Symbian projects. CodeWarrior and Borland C++Builder use different makefile utilities that both have the same name make.exe.

To allow CodeWarrior Series 60 or Symbian projects to continue to build, you need to do the following:

1. Remove the EPOCROOT environment variable (Control Panel->Properties->Advanced-> Environment Variables).

2. Place the path to the Borland C++ Mobile Edition (C:Progra~1BorlandCBuild~1Bin; by default) after the path to CodeWarrior Series 60 and Symbian SDK tools (C:Program FilesCommon FilesSymbianTools, by default).

After performing these steps, you can no longer build Borland C++ Mobile Edition projects at the command line. However, Borland C++ Mobile Edition projects can still be built through the IDE.

If you want to make it so you can build Borland C++ Mobile Edition projects from the command line, EPOCROOT must be defined and the path to the Borland C++ Mobile Edition must be moved in front of the CodeWarrior SDK tool paths. If the Borland C++ Mobile Edition was installed in its default location, the default path to EPOCROOT is Nokia_Symbian6.1Series60.

________________________

Uninstalling Borland C++ Mobile Edition for Series 60

Borland C++ Mobile Edition for Series 60, Borland C++ Mobile Edition (C++Builder), the plug-in, and the Series 60 SDK must be uninstalled separately.

To uninstall Borland C++ Mobile Edition for Series 60, the plug-in, and the Series 60 SDK:

1. Make sure that C++Builder and all of the SDK tools are closed.

2. From the Windows Start menu, choose Control Panel, then Add or Remove Programs.

3. Select Series 60 SDK 0.9, Nokia Edition and choose Remove.

4. Select Borland C++ Mobile Edition plug-in and choose Remove.

If you do not need C++Builder for C++ application development, you must uninstall it separately. If you uninstall Borland C++ Mobile Edition (C++Builder), you must also remove the Series 60 SDK and the Borland C++ Mobile Edition plug-in.

If you have installed Perl and JRE and no longer need them, you need to uninstall these separately as well.

If you uninstall the Series 60 SDK, it is recommended that you also uninstall the plug-in. Otherwise, running C++Builder after uninstalling the SDK may disable the plug-in. If you later reinstall the SDK, you may not see the Mobile functionality in the IDE (no Mobile tab when using File|New|Other). If this happens, you can use BCB6RegClean in your CBuilderbin folder to clear out your HKEY_CURRENT_USER registry settings, and then rerun BCB6. Using BCB6RegClean restores the default settings back to HKEY_CURRENT_USER.

If you plan to reinstall Borland C++ Mobile Edition, you must run MobileEditionRegClean.exe located in the Extras folder at the root of your distribution to clean up the HKEY_CURRENT_USER registry settings from your previous install.

Uninstalling on Multiuser Systems

On multiuser systems, the Administrator who initially installed the products must uninstall it (using the Control Panel Add/Remove Programs applet); after that, all other users of the products must log in and run the provided BCB6RegClean.exe utility to remove user-specific data from the Windows registry.

Note: BCB6RegClean.exe is located in your CBuilderBin directory and on the Borland C++ Mobile Edition for Series 60 CD in the BCB6_MobileEditionInfoExtrasRegCleanUtility directory.

Caution: If working on a multiuser system, it is possible that users other than the one who installed these products may have already run C++Builder 6 and hence have C++Builder 6 registry entries. Since they didn't install the product, they will not have the new HKEY_CURRENT_USER registry entries from the SDK installer and the plug-in installer. In this case, these users may run BCB6RegClean.exe utility to force the IDE to refresh its settings from the global environment space. Note: Using this procedure restores the default settings.

On multiuser systems, uninstalling Borland C++ Mobile Edition does not remove all HKEY_CURRENT_USER registry entries. To remove these registry entries for C++Builder 6, run the provided BCB6RegClean.exe utility. To remove the entries for the Borland C++ Mobile Edition, Series 60 SDK, and plug-in, run MobileEditionRegClean.exe located in the Extras folder at the root of your distribution.

________________________

Using the Borland C++ Mobile Edition Plug-in

Note: This version of the Borland C++ Mobile Edition was developed and tested for English language usage only. Set your regional settings to English.

The Borland C++ Mobile Edition plug-in allows you to create a new mobile project from within the C++Builder 6 development environment (choose File|New|Other and on the Mobile tab, click New Mobile Application). You need to write the application code using the Series 60 SDK 0.9, Nokia Edition.

To build mobile applications from within C++Builder, you need to be sure that the path to Borland tools (C:Progra~1BorlandCBuild~1Bin; by default) appears before any other build tools in the Path. (You can check the Path using Start->Control Panel and select System. Choose the Advanced tab and select Environment Variables to view or edit the Path.) The Path could be affected by installing additional SDKs.

You can also import existing projects from the Nokia_Symbian6.1Series60Series60Ex directory using a wizard. The import wizard generates a set of C++Builder projects that include all .cpp, .c files, and project files used by the Nokia project. You can then save and build the imported project within the C++Builder development environment. A compiler progress dialog is displayed while you are building.

After you click OK on the compiler progress dialog, you will see a Built Results tab in the message view.

All project files including all .bprs and .bpgs must be saved in the same directory as the bld.inf. Otherwise, build errors will occur and you may receive a List index out of bounds error when reopening the project.

When building applications, you may see messages such as Cannot find <file>.RSG in the build results. These warning messages occur during makefile generation. RSG files, however, are resource headers that get created after makefile generation. These warnings are expected and are therefore ignored by the Compiling dialog which will not report them in the Missing summary. Messages concerning exports that must be frozen may also appear. If the application does not run, you may need to freeze them by choosing Tools|Mobile Build Tools|Execute ABLD Commands|Freeze Build Files.

Refer to the HTML help files in the Cbuilder6HelpMobileEdition directory for details on building mobile applications. Click on the index.html file in that directory or choose Help|Borland C++ Mobile Edition Help from the IDE to display the help.

________________________

Using the Emulator

Note: Users must have Administrative permissions in order to run the Emulator under Windows XP.

You can run the Emulator from the IDE or the command line. To run it from the IDE, you specify WINSB (udeb or urel) as the active configuration (under Project|Options, Build Configuration tab); choose Run|Run, click OK on the compiler dialog, and if your build was successful (you see Build Successful), the Emulator is automatically displayed. To run it from the command line, you can start it as follows:

EPOC

Note: By default, this brings up the debug version of the Emulator. See Nokia SDK Help for options available with epoc.exe.

If your active configuration is set to WINSB (udeb or urel), you can also start the Emulator from the IDE by choosing Tools|Mobile Build Tools|Run Emulator.

In the Emulator, for both Debug and Release builds, the MMSINBOX default application does not appear in the Other folder.

________________________

Deploying mobile applications

To deploy to a device, you need to use a tool such as Nokia PC Connectivity Suite (download from Nokia) with Infrared or Bluetooth.

When youre ready to deploy to the device, you need to create a package (.pkg) file which is used to make the .sis file that will be installed on the device. The package file must contain a Unique Identification (UID) number assigned to it as required by the Symbian OS to identify the file. C++Builder automatically creates a .pkg file when you choose Build Symbian Installation System. You need to make sure that the UID3 number is unique. Otherwise, when you load the application onto the mobile device, any other application with the same UID will be overwritten. For details on UIDs, see the help files in the Series60Doc folder (or choose Help|Series 60 SDK Help|Nokia Series 60 SDK for Symbian OS).

To deploy an application, the active configuration must be set to ARMIB urel or ARMIB udeb (in the Project|Options, Build Configuration tab) and you must have completed a successful build. To build the sis file, select Project|Build Symbian Installation System. To send the sis file to the device, choose Project|Deploy to Device. This command tries to execute an EPOCINSTALL using PC Connectivity Suite. If deployment fails, a message box asks you whether you want to manually deploy the .sis file. If you say OK, an Explorer view is displayed where you can manually drag and drop files onto the mobile device.

If you receive a system error after deploying an application, check your .sis file to be sure that it includes all necessary files. If it doesnt, add the missing files manually to the .pkg file and regenerate the .sis file.

________________________

Sample Applications

This release includes the Nokia sample applications in Nokia_Symbian6.1Series60Series60Ex which function properly (unless documented otherwise in this file). We recommend that you use these for testing. The Symbian sample applications (in Nokia_Symbian6.1Series60epoc32ex) are provided for reference, but Borland does not claim responsibility for their quality or functionality.

Issues with the Sample Applications

Some of the sample applications export libraries to the global library store. The convention for Symbian OS applications is to export libraries only if their interfaces have been frozen or if the Symbian project file (.mmp file) specifies the EXPORTUNFROZEN keyword. See the Symbian documentation for more details on freezing exports. Borland C++ Mobile Edition for Series 60 follows the Symbian convention. As a consequence, some of the sample applications will not successfully build for ARM targets until they have been frozen. The GuiEngine sample is an example of an application that must be frozen before it can be built successfully.

Note that you never need to freeze build files when building for WINSB.

Follow these steps:

1. Import the project by choosing File|New|Other, clicking the Mobile tab and selecting Import Mobile Application.

2. Choose Project|Options and on the Build Configuration tab, set the configuration to ARMIB (urel or urel).

3. Choose Project|Build All Projects.

4. If you receive messages that export files need to be frozen, choose Tools|Mobile Build Tools|Execute ABLD commands|Freeze Build Files.

5. Rebuild the project: Project|Build All Projects.

All Bluetooth Applications

You can run Bluetooth applications on the Series 60 Emulator and deploy them to mobile devices but you need the following:

7      Bluetooth card (either the Nokia Connectivity Card DTL-4 or the Socket Bluetooth CF Card)

7      Windows 2000

Before you can use Bluetooth, you need to install the Bluetooth card as a COM port (you don't need original card drivers). You must remove all Digianswer software and BT card drivers in advance. Download the Setting up and Using Bluetooth Testing Environment for Series 60 v1.2 document for further information on the installation of the card, configuration of the COM port and using Bluetooth examples with the Emulator:

http://www.forum.nokia.com/main/1,,1_43_40,00.html

This document refers to WINS targets rather than WINSB so you will have to change pathnames accordingly.

The following sample applications have problems at runtime on the Emulator.

Dialer:

1. Build project and deploy to the Emulator.

2. Open the application on the Emulator and select Options|Dial.

The application freezes.

3. Press the Apps button on the Emulator.

4. Open the application on the Emulator again.

This causes the Emulator to crash with a fatal application error.

Sockets:

1. Build project and deploy to the Emulator.

2. Open the application on the Emulator and select Options|Connect.

3. Enter a valid IP address and click OK

This causes the Emulator to crash with an Exception breakpoint error. Sockets applications such as this one do work on mobile devices.

________________________

Working at the Command Line

You can use the Series 60 SDK with the plug-in much as you are used to using it. Although you do not need to use command line tools, if you choose to, you need to replace WINS with WINSB and ARMI with ARMIB in places where you need to specify the platform explicitly.

WINSB builds your application for the Emulator using Borland tools (the Borland C++ compiler: bcc32, linker: ilink32, and Make tool: make).

ARMIB uses Borlands make and the GNU gcc cross-compiler to build your application for a mobile device (such as the Nokia 7650).

If your application code needs to distinguish between the Borland C++ compiler and other Windows C++ compilers, you can use this define: __BCPLUSPLUS__. Borland C++ internally defines this macro.

The __WINS__ macro can still be used to build for WINSB targets. You can also use __WINSB__ for Borland-specific builds.

For example, the following commands build an application with debug information for testing on the Emulator:

bldmake bldfiles
abld build winsb udeb

For example, the following commands build an application for the target device:

bldmake bldfiles
abld build armib udeb

________________________

Known Issues

7         Opening Projects: When you want to open a project, you can only do so by opening the project group (.bpg) files. Do not open individual project (.bpr) files! Opening a project using a .bpr file will cause an error.

7         Building applications: Do not execute Project|Make Clean on projects that have not yet been compiled. This will cause errors when you try to build the projects. When using CodeGuard for debugging previously compiled project, you must Make Clean before using Build All to compile the application.

7         Project Manager/MMP File Synchronization: Synchronization between the Project Manager and .mmp files is often unreliable. Synchronization only occurs if you use the following steps:

1. Add a file in the .mmp file

2. File|Save All

In all other instances (such as adding or deleting a file through the Project Manager, or deleting a file from the project using an .mmp file) synchronization will fail.

7         Emulator: Users must have Administrative permissions in order to run the Emulator under Windows XP. Running epoc.exe as a "Limited User" results in udeb epoc.exe crashing. Everything works OK for Administrative Users on XP or Power Users on Windows 2000. The urel epoc.exe may not crash right away, but does display system errors.

7         SDKs: At this time, the only SDK available is Series 60 SDK 0.9, Nokia Edition.

7         Menu items: You can only use the Explore Target Directory, Check Build Results, and Show Build Targets commands on the Tools|Mobile Build Tools menu after building or compiling your application. Otherwise, you will see an error saying that the directory cannot be found or abld is not recognized as an internal or external command.

7         Debugging: The IDE does not support remote debugging on mobile devices. You can use the included Series 60 SDK tools for this purpose. Refer to the Nokia documentation for more information.

7         Deploy: To deploy to a device, you need to use a tool such as Nokia PC Connectivity Suite (download from Nokia) with Infrared or Bluetooth. Before attempting to deploy to your device from the IDE, verify that you can send and receive information to the device using your PC connect software. For example, some laptops disable wireless connectivity when docked.

7         Packages: Sometimes the IDE creates incomplete packages so that not all necessary files are included in the .pkg or .sis files, so the application wont run. Here is an example of how an invalid package can be created:

1. Import and build the Spane sample application (in the Series60ex directory) for ARMIB/UDEB.

2. Choose Project|Build Symbian Installation System.

3. Transfer the resulting .sis file to the device, and launch the application.

A system error occurs.

If you have this problem, check your .pkg file to make sure it includes all necessary files. If it doesnt, add the missing files manually and regenerate the .sis file using Project|Build Symbian Installation System.

7 Borland C++Builder Applications: If you plan to create C++Builder applications in addition to mobile applications (File|New Application or File|New|CLX Application), make sure you close all mobile projects and restart C++Builder before creating and building a new VCL or CLX application. This resets the environment for using the appropriate build tools.

________________________

Copyright ) 2003 Borland Software Corporation. All rights reserved.