How to Use the Command Line to Create, Customize, and Build a Run-Time Image (Windows CE 5.0)

  • Article

Platform Builder includes a set of command-line tools that serve as the foundation for the integrated development environment (IDE). These tools make up the build system that the IDE calls when creating, customizing, and building a run-time image.

You can directly call many of these tools from a command-line prompt build window to create and customize an OS design. After you complete customizing your OS design, you can use your OS design to build a run-time image. If you use the command-line to work with an OS design, you gain a finer degree of control over which parts of your OS design are built. This increased control can improve build times by building only modified files and then by creating the final run-time image from files in the release directory.

Regardless of whether you use the command line or the IDE to work with an OS design, you must use the IDE to download the run-time image to a target device for debugging and testing. The target device that you select can be any of a variety of devices, such as the Emulator or a Windows CE PC-based hardware platform (CEPC).

For information about the Emulator, see Emulator.

Note   If your target device is the Emulator, it does not require additional hardware because it runs on the development workstation.

For information about setting up a CEPC, see How to Set Up a CEPC.

Hardware and Software Assumptions

  • You are familiar with the Platform Builder directory structure.

    For information about the Platform Builder directories, see Run-Time Image and OS Directories.

  • Your CEPC has a mouse or other input device.

  • Your CEPC has an NE2000-compatible Ethernet card.

    For information about using a CEPC with a DMA-compatible Ethernet controller, see article Q317432 at this Microsoft Web site.

  • Your CEPC has 32 MB of RAM for a typical run-time image built from a Release configuration.

    - or -

    Your CEPC has 64 MB of RAM for a typical run-time image built from a Debug configuration.

    Run-time images built from Debug configurations can be larger than those built from Release configurations because they include support for debugging, and can require more memory to run.

    For information about the levels of debugging support that are available, see Levels of Debugging Support.

To track your progress in the following table, select the check box next to each step.

  Step Topic
1. To create a workspace and build environment for your OS design, do one of the following:

  • Select or create an OS design; then use the PBXMLUtils.exe executable from a command-line prompt to set up a build environment. For more information, see Creating an OS Design and Setting Up a Build Environment From the Command-Line.

    It is recommended that you use this method because the Platform Builder workspace (.pbxml) file you create is fully compatible with both the IDE and a command-line prompt build window.

    - or -

  • From a command-line prompt, use the Windows CE Build Environment tool to create a workspace. For more information, see Creating a Workspace from the Command-Line.
 Not applicable.
2. (Optional) Add Catalog items to your OS design by setting Sysgen variables.

For example, add the application Microsoft® FreeCell to your OS design by typing the following command.

Set SYSGEN_FREECELL=1
 Sysgen Variables

Setting or Clearing a Sysgen Variable
3. Make sure no conflicts exist in your OS design by checking the dependencies of the included Catalog items. How to Check the Dependencies of a Catalog Item

Cesysgen Batch File
4. Configure settings for your OS design by setting environment variables.

For example, if your run-time image will require more than 64 MB of RAM to run, enable a larger run-time image size by typing the following command.

Set IMGRAM64=1
 Environment Variables
5. (Optional) Duplicate the %_WINCEROOT%\Public directories that contain the source code you want to modify in the directory for your workspace. How to Duplicate a Public Directory as an OS Design Directory
6. (Optional) Include the directories that contain the modified source code that you want to build by setting an environment variable.

For example, if the original source code you duplicated in your workspace is in the %_WINCEROOT%\Public\Shell\Oak\<Explorer_name> directory, set the BUILD_OPTIONS environment variable by typing the following command.

Set BUILD_OPTIONS=Explorer_name
Note   Verify that the name of the new build directory is unique as compared to all file, directory, and subdirectory names within your %_WINCEROOT% directory.
Duplicate names can cause the build system to skip a directory or improperly locate the binary file that results from the build when the run-time image is created.
Not applicable
7. Configure the run-time image configuration files for your OS design. OS Design Configuration Files
8. (Optional) Localize your OS design. OS Localization
9. Set the type of run-time image that you want to build.

For example, set the active configuration to Debug by typing the following command.

Set WINCEDEBUG=debug

This results in a run-time image with debugging enabled. This increases the size of the image, and can affect the time required to complete the build process.

 Build Configurations
10. Build the run-time image for your OS design by typing the following command. 
Blddemo

This instructs the Build Demo Tool to build source code in the %_WINCEROOT%\Public and %_WINCEROOT%\Private dependency trees.

The amount of time that Platform Builder requires to build the run-time image for your OS design depends on the size of your OS design.

To include later modifications to source code, type the following command.

  Blddemo -c clean cleanplat

This instructs the Build Demo Tool to execute a clean build.

 Build Demo Tool
11. Determine the contents and physical characteristics of the run-time image you built. How to Determine the Contents of a Run-Time Image
12. Start Platform Builder and load the binary file, Nk.bin, for your run-time image. The follwing list shows the steps to take:
  • From the File menu, choose Open.
  • In the Files of Type list box, choose Kernel Files (.bin;.cem;.lst).
  • Navigate the directory tree to %_FLATRELEASEDIR%. Select the file Nk.bin, and then choose Open.
 Not applicable
13. Select and configure a connection to a target device.

For information about setting a configuration if your target device is a CEPC, see How to Configure and Download a Run-Time Image to a CEPC.

For information about setting a configuration if your target device is the Emulator, see Downloading a Run-Time Image to the Emulator.

 Configuring a Connection for Downloading and Debugging
14. Configure a terminal emulation application, such as Microsoft HyperTerminal, to receive debug messages. Configuring HyperTerminal for BSPs
15. Download the run-time image that you have built to the target device. Downloading a Run-Time Image
16. Use remote tools to test the run-time image.

For example, you can use the Remote Process Viewer to list processes and threads running on a target device. For more information about remote tools you can use, see Remote Tools.

 Debugging and Testing a Run-Time Image

See Also

How-to Topics | Command-Line Tools | Introducing Windows CE | Developing an Operating System | Developing a Device Driver | Developing an Application | How to Duplicate a Public Directory as an OS Design Directory

Last updated on Thursday, February 02, 2006

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.