Creating a Software Development Kit for Windows CE .NET

Mike Hall
Microsoft Corporation

Steve Maillet
Entelechy Consulting

March 5, 2002

Why the Need for an SDK?

Writing applications for Microsoft® Windows® desktop operating systems is straightforward; you know exactly which APIs are supported. This is defined by the Windows Platform Software Development Kit (SDK), which can be downloaded from https://www.microsoft.com/msdownload/platformsdk/sdkupdate/. Windows CE .NET is componentized. The number of APIs exposed on a Windows CE device is determined by the components included in the platform. This could make it tricky for application developers to write code that will run on a platform, since there isn't an easy way to determine which APIs are exposed on a given device. This is where building a Software Development Kit for Windows CE comes in…

**Note   **Microsoft has introduced the "Standard SDK" for Windows CE .NET. A developer can choose to include the Standard SDK component in their Windows CE .NET device, which will include a baseline set of components that developers can target, making it easier to write cross-device applications. Microsoft® eMbedded Visual C++® 4.0 ships with support for the Standard SDK.

Windows CE .NET SDKs

Windows CE developers can typically be divided into two groups: platform developers and application developers. The Windows CE .NET product ships with two development tools, each designed to cater to the appropriate developer audience.

Platform Builder is the tool used to configure, build, download, and debug the Windows CE operating system to a reference board (or to emulation). Platform Builder contains everything a platform developer would need to configure the operating system, write device drivers, and debug the operating system (including 1.5 million lines of Windows CE source code to aid device bring up, and to help developers understand how the Windows CE operating system works). Platform Builder also contains a set of application wizards that can be used to build 'simple' Win32 applications and DLLs (drivers, and function or resource DLLs).

You may be interested in having some of your in-house developers or customers build applications for your device, or a custom shell for the device, either in parallel to the development of your reference hardware or after the device ships. For the most part, application developers don't care about the underlying hardware on a platform. Take the simple operation of writing some data out of the serial port of a device: The Win32 API abstracts you away from the underlying hardware (through the use of device drivers), so the serial write operation simply translates into calls to the following three APIs:

• CreateFile
• WriteFile
• CloseHandle

Application developers need a tool that can be used to write applications without having to build and download an operating system image. They therefore need access to the header files and libraries that define which APIs are supported on a platform.

The second tool that ships with Windows CE .NET is eMbedded Visual C++ 4.0. This tool is designed for application developers, and in many respects is similar to Visual C++ 6.0 for the desktop, containing wizards for building the following project types:

• WCE Application
• WCE ATL COM Object
• WCE Dynamic Link Library
• WCE MFC ActiveX ControlWizard
• MFC AppWizard (dll)
• MFC AppWizard (exe)
• WCE Static Library

The WCE Application and WCE Dynamic Link Library wizards are the same as the Platform Builder wizards in that they give the ability to build 'simple' applications and DLLs (drivers, and function and resource DLLs).

**Note   **eMbedded Visual C++ 4.0 cannot be used to write applications for desktop Windows, nor can it be used to write applications for Windows CE 3.0-based devices (such as the Pocket PC). eMbedded Visual C++ 4.0 can, however, be used to write applications for Windows CE .NET-based devices. We've added the following support to eMbedded Visual C++ 4.0: STL, RTTI, and structured exception handling.

So, the question is: How does an application developer know which APIs are exposed on a platform? Platform Builder provides a mechanism for building a custom software development kit (SDK); this defines which APIs are exposed on a platform, and also builds a custom help file that lists the APIs. Assuming that I'm building a platform in Platform Builder called 'MyDemo', this workspace would be located in the \Wince400\public\MyDemo folder. When an SDK is built from Platform Builder, this is created in the \Wince400\public\MyDemo\SDK folder. The SDK can be freely distributed; a typical SDK is approx 32 MB in size and is packaged as a self-installing .msi file.

We've discussed the need for an SDK. There is probably at least one person somewhere out there ready to ask: "How do I create an SDK for my platform?" That's a great question. To find out how, read on…

Creating Your SDK

Exporting an SDK requires two stages:

1. Configure the SDK.
2. Build the SDK.

You must configure an SDK before you can build it, so in Platform Builder, on the Platform menu, click Configure SDK. (This option is only available when you have a workspace open. You must have a Platform Builder workspace for the platform in order to export an SDK. There is no documented method of exporting an SDK from a command-line-only build—at least not yet; we may tackle that in another article. Let us know if that would have value.) The first time you configure the SDK, you are greeted with a wizard with a few basic options. The first wizard screen is the usual "Welcome to the wizard," explaining what it does. The second page sets up the basic installation information for the SDK setup.

Figure 1. Export Wizard—selecting the product name and manufacturer

The Microsoft® Installer (MSI) is used in the installation of an SDK. This page provides information about the product name as it will appear to the installer (and thus to the user for uninstall). It also provides the manufacturer name and version of the installation.

The second page in the wizard prompts for language support in the SDK.

Figure 2. Choice of development languages

You can include the .NET Framework support and eMbedded Visual C++ support for Active Template Library (ATL) and Microsoft Foundation Class (MFC).

**Note   **As of the time of this writing, the .NET compact Framework that ships with Windows CE .NET is still only a technology preview, and you are not allowed to ship it in your device, nor include support for it in any SDK you release outside of your organization.

Once the initial wizard is complete, you can build the SDK. On the Platform menu, click Build SDK. However, you can provide additional configuration; on the Platform menu, click Configure SDK a second time, or select the option to make further customizations from the final page of the initial wizard. The second time you configure the SDK, you get a tabbed dialog with many more options. The "Product Properties" tab and the "Development Languages" tabs are identical to the pages in the initial wizard.

Figure 3. Advanced SDK settings

The Install tab contains information about the installation. The "Export SDK to" is a nice new option that defaults to the "SDK" folder under your project's folder. This keeps the SDK with the project. Also of importance are the two radio buttons for compression or leaving files uncompressed. If you are delivering your SDK on a CD, it will install significantly faster if you do not compress the files. (It will, however, take up more space on your development system.) If you compress the files, they will all be packaged into a single .exe file for distribution. This is the preferred approach for an Internet download of the SDK. Since everything is compressed, it will take longer to install.

We won't go into the details of all of the tabs, as most are fairly straightforward, but the following table is a summary:

Of particular interest to device vendors are the Additional Files tab and the Help tab. These allow you to add headers, libraries, and other files and documentation for your device-specific functionality. Many vendors have rugged handheld devices that third parties can create applications for. These devices are usually targeted to a specific market segment and contain specific functionality that third-party applications might need to have access to.

For instance, if the device is intended for extreme cold weather climates, there might be a thermometer and a heater for the LCD, so that it can operate in colder environments. You might want to expose an API set to allow developers to read the temperature and enable the heater as needed. (Although that probably should be something you handle automatically already!) You may also want to allow third-party driver support.

Let's say you have a custom expansion bus (like the Compaq iPAQ™) and you want to allow developers to create drivers. You will need to provide them with the appropriate headers and .lib files. The normal SDK contains some of the headers, but it does not contain the libraries needed to build device drivers for a platform. Windows CE does not have a DDK like other Windows systems, because the hardware platforms can vary so much; therefore, you must create one based on the filtered headers and libraries for your particular project. (Refer to the SYSGEN phase of the build in our earlier article, Customizing the Windows CE Build System Using DIRS, SOURCES, and CECs, for more information on the filtering.) Click the Additional Files tab to add in the necessary pieces.

**Note   **Debugging device drivers using eMbedded Visual C++ is a tricky process, as device drivers all load in the device manager's process space, and you cannot attach to the device manager. Instead, you need to create an application to load the driver and test it from within that application. (We won't get into that in this article. If there is enough interest we can cover that at a later point. As always we encourage your feedback.)

Figure 4. Adding additional files to the SDK

Though cesysgen\ddk\inc files are included in the SDK automatically, a number of libraries that are needed, and several headers, are not included. To add files or entire folders, click Add to open the Additional Files Detail dialog box.

Figure 5. Selecting additional files and folders for the SDK

The Source folder field of this dialog identifies the folder or file to add. You can use the "…" browse button to navigate to the folder in your project. The Target path field specifies where the files should be placed in the structure of the SDK, as it will be installed on the end user's system. For DDK files, I usually put the files in a DDK folder. Once you've added the files/folder, you will see that the Include Subfolder column has a check box to indicate whether subfolders should also be included in the installation. For a DDK you should include the following folders:

X:\WINCE400\public\<platform name>\wince400\cesysgen\DDK\inc

X:\WINCE400\public\<platform name>\wince400\cesysgen\OAK\inc

X:\WINCE400\public\<platform name>\wince400\cesysgen\OAK\lib

Be sure to check the option to include the subfolders for each of these.

Adding help files is fairly easy as well. You can have a master help file that may include other help files. This is really useful for documenting your extensions added into the SDK files. The end user won't need to search around to find a separate help file to locate your device-specific documentation. This approach is highly recommended. The master help file is inserted into the help system as a top level "Book" in the contents of the help system. In eMbedded Visual C++, any help files referenced are included as subtopics in whatever location they appear in the master file table of contents. Place only one master help file per platform to avoid confusing the end user as to which topics belong to what devices.

We've described why SDKs are important and how to build an SDK. It may also be interesting to figure out where the SDK files live on my development PC once they are installed. SDKs are installed to the following folder: \Program Files\Windows CE Tools\wce400.

I've recently created a platform called SDKDemo. Here's the folder listing for the SDKDemo Windows CE SDK:

Directory of C:\Program Files\Windows CE Tools\wce400\SDKDemo

02/11/2002 05:20 AM <DIR> .
02/11/2002 05:20 AM <DIR> ..
02/11/2002 05:18 AM <DIR> Atl
02/11/2002 05:19 AM <DIR> Emulation
02/11/2002 05:20 AM <DIR> Help
02/11/2002 05:18 AM <DIR> Include
02/11/2002 05:18 AM <DIR> Lib
02/11/2002 05:18 AM <DIR> Mfc

You can clearly see the folders that contain the include and library files, help files (CHM files), and support for MFC and ATL for the platform. In this example I've built an SDK for emulation. The Windows CE operating system image (NK.BIN) ships with the SDK. This is included in the Emulation folder and is given the name of NK.CEM (the CEM file type is associated with the emulator). Double-clicking the CEM file will launch the Emulator with the Windows CE .NET image.

SDKs are uninstalled using Control Panel, Add/Remove Programs.

Time to market can be reduced for a Windows CE device if you have application development taking place in parallel to the hardware development. There are a number of ways in which you can do this; perhaps the quickest and easiest option is to make use of the Windows CE .NET emulation environment. Once you have chosen the core operating system components for your platform, you can simply export an SDK and have your internal developers and customers writing applications for your device.

Get Embedded

Mike Hall is a Product Manager in the Microsoft Embedded and Appliance Platform Group (EAPG). Mike has been working with Windows CE since 1996—in developer support, Embedded System Engineering, and the Embedded product group. When not at the office, Mike can be found with his family, working on Skunk projects, or riding a Honda ST1100.

Steve Maillet is the Founder and Senior Consultant for Entelechy Consulting. Steve has provided training and has developed Windows CE solutions for clients since 1997, when CE was first introduced. Steve is a frequent contributor to the Microsoft Windows CE development newsgroups. When he's not at his computer burning up the keys, Steve can be found jumping out of airplanes at the nearest drop zone.