Share via

Migrating to the eVC 4.0 Environment

  • Article

 

Yaroslav Goncharov
Microsoft MVP

November 2003

Summary: This article describes basic considerations for migration from eVC 3.0 to eVC 4.0 and outlines new features of Microsoft eMbedded Visual C++. (11 printed pages)

Applies To:

    Microsoft® eMbedded Visual C++® 4.0 SP2
    Microsoft Visual Studio® .NET
    Microsoft .NET Compact Framework
    Microsoft Windows® Powered devices
    Windows Mobile™-based devices
    Windows Mobile 2003 Second Edition software for Pocket PCs
    Windows Mobile 2003 Second Edition software for Smartphones

Contents

Introduction
Migrating from an eVC3 Project to eVC4
Using eVC 3 and eVC 4 in One Project
Using eVC 4 to Build for Windows CE 3.0
Side-by-Side Issues
New Features
Conclusion

Introduction

The Microsoft® Windows® Mobile 2003-based Pocket PCs and Smartphones are a big step forward since they are based on the next version of the Microsoft Windows CE operating system, Windows CE .NET 4.2. Microsoft eMbedded Visual C++® 4.0 (eVC 4) is a new development environment for Windows CE .NET 4.2 native code development. It introduces lots of new features, but since it is new and completely independent, there are several non-trivial aspects in migrating from the previous set of tools, eMbedded Visual C++ 3.0 (eVC3), and creating projects targeting both operating systems.

In this article, I explore basic considerations for migration from eVC 3.0 to eVC 4.0, and how to structure a project to support both 2002 and 2003 platforms. I also outline new features of eVC4.

Migrating from an eVC3 Project to eVC4

The first possibility is to move your existing eVC3 projects to the new eVC4 environment. Unfortunately, old project files are not compatible with the new environment and there is no way to convert a project file automatically. The steps below will help you port basic projects from eVC3 to eVC4:

  • Create a new, empty, project file in eVC4.
  • Add the files from your eVC3 project including .h, .cpp, .rc, .rc2, .def.

Figure 1. Adding the files to the new eVC4 project

  • Update linker and compiler settings (the "Link" and "C/C++" tabs of the project settings dialog) for your new project with the settings from eVC3. Particularly pay attention to the following settings:
    • Additional include directories (C/C++ -> Preprocessor)
    • Object/library modules (Link -> General)
    • Additional library path (Link ->Input)
    • Precompiled headers settings (C/C++ -> Precompiled Headers)

These steps will let you build your application for Pocket PC 2003 and Smartphone 2003; however, you will lose support for Pocket PC 2002 and Smartphone 2002.

Using eVC 3 and eVC 4 in One Project

If you want to support Pocket PC 2002 and Pocket PC 2003 in one project, or Smartphone 2002 and Smartphone 2003, you should consider sharing source between separate eVC3 and eVC4 projects. In this scenario, you must be careful about the use of platform dependent code. The preprocessor can be used to conditionally compile bits of code that is common for both operating systems. In the default project settings the UNDER_CE symbol is defined as $(CEVersion). The value of the $(CEVersion) macro is 300 under eVC 3.0 and 420 under eVC 4.0. The code snippet below demonstrates this technique:

// CeSetProcessVersion requires Windows CE .NET 4.2 and later
#if UNDER_CE>=420
    CeSetProcessVersion(hProcess, dwVersion);
#else
    TRACE(_T("CeSetProcessVersion is not supported\n"));
#endif

Using eVC 4 to Build for Windows CE 3.0

There is a linker option (/subsystem=windowsce,3.00) that allows building an application that runs on Windows CE 3.0–based platforms. Using this unsupported feature you can develop applications for older platforms using the new eVC 4 environment. You can use new C++ compiler features and, what is more important, you can target all platforms using one project file and one IDE. However, these advantages are not free, this workaround has some significant drawbacks and restrictions.

The new eVC4 IDE does not support old Windows CE 3.0 emulators; therefore, there is no way to debug an application for Windows CE 3.0-based platforms. Even a separate project file for eVC 3.0 will not help if you use new features of the C++ compiler.

You need to be careful with the APIs you use in your project. An API that is specific to Windows CE .NET–based platforms must be excluded from Windows CE 3.0 builds; otherwise, you may experience unpredictable behavior on old platforms. Consider the following situation: you use CeSetProcessVersion API function from coredll.dll. This function requires Windows CE .NET 4.2 and later. If you use this function in a Windows CE 3.0 build the linker will report no error. The resulting binary can cause a crash since coredll.dll does not export this function under Windows CE 3.0.

Another problem is that the Windows CE .NET 4.2 header files do not provide complete forward compatibility. For example, under Windows CE .NET 4.2 the NM_RECOGNIZEGESTURE message is defined as (NM_FIRST-50), but formerly (under Windows CE 3.0) it was defined as (NM_FIRST-16). If you need to use this constant in your code you can use conditional compiling to resolve this issue.

To use this linker feature it is necessary to create a new project configuration for each target CPU. You may also want to create two configurations for each CPU to support release and debug builds.

For example, if you have an eVC4 project, the following steps will add a release configuration that targets a Windows CE 3.0–based device:

  • On the Build menu, click Configurations.
  • Click the Add button.
  • Select "Win32 (WCE ARMV4)" in the first drop-down menu.
  • Select "… – Win32 (WCE ARMV4) Release" in the "Copy settings from" menu.
  • Type ReleaseWCE30 in the "Configuration" field and click OK.

Figure 2. Add Project Configuration dialog

  • Click the Close button.
  • On the Project menu, click Settings.
  • Select the "Win32 (WCE ARMV4) ReleaseWCE30" configuration.
  • Under the C/C++ tab, select the General category.
  • Under "Preprocessor definitions," replace a value of the UNDER_CE symbol with 300 (the original value of UNDER_CE is $(CEVersion)).

Figure 3. Redefining the UNDER_CE symbol in the Windows CE 3.0 configuration

  • Select the Link tab. In the Project Options field, replace $(CESubsystem) with windowsce,3.00 (/subsystem option).

Figure 4. Redefining the /subsystem linker option in the Windows CE 3.0 configuration

After these steps you will be able to perform conditional compiling based on the UNDER_CE symbol using the technique demonstrated in the previous code snippet (see Using eVC 3 and eVC 4 in One Project).

Side-by-Side Issues

If the eVC 3 and the eVC 4 environments are installed on one computer, you can experience some problems. The new emulator cannot run side-by-side with previous versions. You may need to restart the Windows session to switch the emulator version.

Also, the project and workspace extensions have not changed in eVC 4; therefore, only one environment can be used to open projects and workspaces using the Windows Explorer open command.

New Features

The new development environment has almost the same look and feel as the previous one, but the new features are really exciting.

New Debugger

The most interesting feature in the new debugger is a possibility to attach to a running process. Using just in time (JIT) debugging, you can attach to a process that has crashed and examine its state.

To enable JIT debugging on a Windows Mobile-based device or emulator:

  • On the Tools menu, click Options.
  • Click the Download tab.
  • Select the "Always download JitDebugger," "Always download binaries to target," and "Always download dependencies to the target" check boxes.

Figure 5. Enabling JIT debugging

Now you can investigate the reason for an application crash even if the application is running outside the debugging environment. After a fault the JIT debugger will show you the dialog box on the device asking if you want to debug the crashed application.

Figure 6. The dialog box shown by the JIT debugger on the device

To attach to the crashed process:

  • On the Build->StartDebug menu, click "Attach to WCE Process."
  • Select the device where the failure occurred.
  • Select the crashed process from the process list.
  • Enter the path to the corresponding .exe file on the desktop computer, and then click OK.

Figure 7. Attaching to the crashed process

After these steps, the eVC4 debugger will stop on the line where the problem occurred and you will be able to examine the application state.

Figure 8. Investigating the reason of the application crash

New Emulator

The new emulator extends the range of applications that can be debugged and tested without a real device. With the new emulator it is possible to test and debug desktop installations, ActiveSync filters/providers, desktop applications that use RAPI, applications that require a storage card, games, and other applications that use direct access to the device.

Almost every application can be launched on the new emulator that makes the development process more efficient. The connection to the emulator is much faster than a typical connection to the device. Therefore, debugging in the emulator is an instant process in contrast to debug sessions via an USB cable when it can take time to move from one breakpoint to another.

Folder Sharing

A folder on your PC can be mounted to emulator file system. So you can emulate a storage card and access desktop files from a device-side program without copying them to the emulator image regardless of the folder size.

Files and folders from a mounted folder will be available on the emulator at path "\Storage."

Figure 9. Files and folders from the shared desktop folder appear on the emulator at path "\Storage"

To share a folder, select the emulator->Folder Sharing menu item of the emulator and follow instructions.

Figure 10. Step 1: Select "emulator->Folder Sharing" menu item

Figure 11. Step 2: Select a folder to share

ActiveSync Via Ethernet

You can now connect ActiveSync to the emulator without a loopback serial cable. Compared to the previous version of the emulator this is faster and configuration is simpler, and you do not need a loopback cable and a PC with two serial ports. Now you can more easily test your desktop installations, ActiveSync filters/providers, and RAPI applications against the emulator.

For more information, see Using ActiveSync Over Virtual Switch

GAPI Emulation

The emulator now supports GAPI emulation. You can debug games and other applications that use direct access to the device display without needing a real device.

Figure 12. A GAPI application running in the Smartphone 2003 emulator

To use GAPI emulation you will need to copy the X86 version of gx.dll from the SDK to the emulator. It must be placed into the "\Windows" folder or to the folder your application will run from. You can find the download directory for an application on the "Debug" tag of the Project Settings dialog (the Project->Settings menu item). After default installation gx.dll for the emulator can be found under "C:\Program Files\Windows CE Tools\wce420\SMARTPHONE 2003\Target\X86" for Smartphone 2003 and under "C:\Program Files\Windows CE Tools\wce420\POCKET PC 2003\Target\X86" for Pocket PC 2003.

You can use the Remote File Viewer (the Tools->Remote File Viewer menu item) to copy gx.dll to the emulator.

Figure 13. Using the Remote Filer Viewer to copy gx.dll to the emulator

Touch Screen Emulation

Taps are disabled for devices that do not support a touch screen. For example, Smartphone 2003 emulator does not emulate a touch screen, ensuring that you navigate through your application exactly the same way as you would on the device.

Conclusion

The eVC 4.0 development environment is completely independent from the previous set of tools and introduces lots of new features for efficient embedded development. It should not be a problem to migrate from eVC 3.0 or use both environments side by side, but there are some aspects to consider.