CE5.0 - 创建Catalog Item和Adding It to an OS Design

Tutorial: Creating a Catalog Item and Adding It to an OS Design

This tutorial shows you how to do the following:

• Create a simple Catalog item for the Windows CE OS, using existing source code.

  In Platform Builder, a Catalog item is the smallest piece of functionality you can select and add to an OS design.

  To create a Catalog item, you must first write the code for technologies that constitute the item. Writing code for technologies is beyond the scope of this tutorial. This tutorial shows you how to create a simple Catalog item from existing source code that ships with Platform Builder.

• Include the Catalog item in an OS design.

If you want to use this tutorial as a guide in creating a Catalog item based on code for a technology you have written, the tutorial assumes that you have already written the code and that you want to create a Catalog item based on that code.

This tutorial makes the following assumptions:

• You are familiar with the following terms:
  • Catalog item: an item you can select from the Catalog
  • OS design: a selection of Catalog items that defines the characteristics of an OS and corresponds to a set of Sysgen variables
  • Configuration: a selection of Catalog items from an OS design, and a set of build options

  For more information, see .

• You included support for the Emulator when you installed Platform Builder for Microsoft Windows CE 5.0.

To create a Catalog item and add it to an OS design, you complete the following steps:

Tutorial Step 1: Creating a Catalog Item File

The Catalog for Windows CE is extensible. You can supplement the technologies available in the Catalog with Catalog items you create. After writing the code for your technology, you can add the Catalog item to the Catalog.

Platform Builder builds the Catalog from a collection of Catalog item (.cec) files. A .cec file is a text file that contains the information that allows Platform Builder to display the Catalog item in Platform Builder and add the Catalog item to an OS design.

For example, a .cec file might contain the following:

• The location of Catalog item in the Catalog
• Dependencies that the item has on other items
• Names and locations of files that must be included in an OS design to enable support for the item in the run-time image

To add your Catalog item to the Catalog, you first create a .cec file for your item.

To create a Catalog item file

1. From the Platform Builder Tools menu, choose CEC Editor.

   The CEC Editor window appears, opening a new .cec file.

2. In the CEC Editor window, from the Insert menu, choose Group.
3. In the Name box, type My Catalog Item Group.
4. In the Description box, type This is a sample Catalog item group.
5. In the Group box, type \New Item and choose OK.

   The Group box tells the Catalog where to display your Catalog item.

   Your item appears under a folder named New Item, which is under the top-level folder named Third Party.

6. From the File menu, choose Save As.
7. Navigate to the %_WINCEROOT%\Public\Common\Oak\Catalog\Cec directory.
8. In the File name box, type MyItem and then choose Save.

   This action creates a MyItem.cec file where you enter the information for your Catalog item.

You can now edit the .cec file to include additional information about your Catalog item.

Tutorial Step 2: Adding an Implementation

After creating a Catalog item (.cec) file for a Catalog item, you must add information to the .cec file that describes the item.

In this step you learn how to use the CEC Editor to add the implementation information that defines an instance of an item type.

To add an implementation

1. In the left pane of the CEC Editor window, navigate to Catalog\Third Party\New Item and select My Catalog Item Group.
2. From the Insert menu, choose Catalog Item.

   The Insert Catalog Item dialog box appears.

3. Choose the General tab; then in the Name box, type My Catalog Item.
4. In the Description box, type This is a sample item in the My Catalog item Group group.
5. Choose the Compatibility tab and select the CPU you want to support your Catalog item on.
6. Apply your changes by choosing OK.
7. To save the changes you made in the .cec file you created, from the File menu, choose Save.

   You have added an implementation to the .cec file for your Catalog item.

You can now add a build method.

Tutorial Step 3: Inserting a Link

After creating a Catalog item type and a Catalog item implementation, you can add links to the implementation that provide additional information used when the Catalog item is included in a run-time image.

This information can include the following:

• The location of additional Help documentation for the Catalog item
• The location of the Catalog item source files
• The location of a Platform Builder project (.pbpxml) file

The following procedures show you how to add two different links to the newly created My Catalog Item implementation, a source browsing link and a documentation link. For more information about elements of a build method, see BuildMethod Block.

To add a source browsing link

The following procedure shows you how to add a source browsing link to the implementation, which enables you to browse the source code for the Catalog item in Platform Builder.

1. In the left pane of the CEC Editor window, select the My Catalog Item node.
2. From the Insert menu, choose Source Browsing Link.

   The Insert Source Browsing Link dialog box appears.

3. In the Build File box, enter or browse to the location of the source code files for the Catalog item.

   File types you can enter include sources, dirs, and makefile (.mak) files.

4. In the Display Name box, enter a friendly name to display in Platform Builder.

To add a documentation link

The following procedure shows you how to add a documentation link to the implementation.

1. In the left pane of the CEC Editor window, select the My Catalog Item node.
2. From the Insert menu, choose Documentation Link.

   The Insert Help File Link dialog box appears.

3. Enter or browse to the path and name of an HTML Help (.chm) file to associate with the Catalog item.
4. Choose OK.
5. From the File menu, choose Save.

   You have added links to the My Item implementation that you created.

You can now add your .cec file to the Catalog.

Tutorial Step 4: Adding Support Information for a Catalog Item

After creating a Catalog item implementation, you must add information to the implementation that provides information about the CPUs that support the Catalog item and variables that are set.

To add support information for a Catalog item

1. In the CEC Editor window, in the left pane, select the My Item node.
2. In the right pane, choose the Compatibility tab.
3. From the CPUs list, select emulator.
4. Choose the Variables tab.
5. In the Variable box, type SYSGEN_MYITEM.
6. From the File menu, choose Save.

   You have added support information to the Catalog item implementation.

You can now add the item to the Catalog.

Tutorial Step 5: Adding the Catalog Item to the Catalog

After you create a Catalog item (.cec) file, you can add the associated Catalog item to the Catalog by adding the .cec file to the Catalog.

This enables you to add the item to an OS design from within Platform Builder.

To add the item to the Catalog

1. In the CEC Editor window, from the Catalog menu, choose Add to Catalog.

   You have added your Catalog item to the Catalog.

2. In the Platform Builder window, right-click in the Catalog window and then, from the context menu, choose Refresh Catalog.
3. Navigate to Third Party and expand the New Item node.

You can now create a basic OS design that you can use to create a run-time image.

Tutorial Step 6: Creating an OS Design

After adding your item to the Catalog, you can add the item to an OS design.

The following procedure shows how to create a basic OS design from the Internet Appliance design template.

If you have already created an OS design, skip to .

To create an OS design

1. From the Platform Builder File menu, choose New Platform.
2. Choose Next.
3. In the Platform Name box, type SampleOSDesign and choose Next.

   - or -

   In the Platform Name box, type a name of your choosing, and choose Next.

4. In the Available BSPs list, select EMULATOR: X86 and choose Next.
5. In the Platform Configuration list, select Internet Appliance and choose Finish.
6. Read the information displayed about Catalog items you have included in your OS design and then choose Next.
7. Choose Finish.

   You have created a basic OS design.

You can now add your Catalog item to the OS design.

Tutorial Step 7: Adding the Catalog Item to the OS Design

After creating an OS design you can add your Catalog item to the design.

To add the Catalog item to the OS design

1. From the Platform Builder View menu, choose Catalog.

   This action displays the Catalog, if the Catalog is not already displayed.

2. From the View menu, choose Workspace.

   This action displays the workspace for your OS design, if the workspace is not already displayed.

3. In the Catalog, navigate to Third Party\New Item and choose My Catalog Item.
4. Right-click My Catalog Item and choose Add to OS Design.

   You have created a Catalog item and added the item to the OS design.

You can now build your OS design.

Tutorial Step 8: Building the OS Design

After you add your Catalog item to the OS design, you can verify that the Catalog item appears in your OS design and build the modified OS design.

To build the OS design

1. From the Platform Builder Build OS menu, choose Set Active Configuration, select a configuration for your OS design, and then choose OK.
2. From the Platform menu, choose Settings and make sure the configuration is selected in the Configurations list.
3. Choose the Build Options tab and verify that the following check boxes are selected:
   • Enable CE Target Control Support
   • Enable Eboot Space in Memory
   • Enable Full Kernel Mode
   • Run-Time Image Can be Larger Than 32 MB
4. Save your changes and close the dialog box by choosing OK.
5. From the Build OS menu, verify that Copy Files to Release Directory After Build and Make Run-Time Image After Build are selected.
6. From the Build OS menu, choose Build and Sysgen.

   It can take up to 20 minutes to build the run-time image.

   You can observe the build process in Platform Builder. The progress of the build process is displayed on the Build tab of the Output window.

   When the build is complete, you see the following message: MyOSDesign - 0 error(s), XX warning(s).

7. After you build the run-time image, verify that the Catalog item appears in the OS design by doing the following:
   1. In the Workspace window, choose the OSDesignView tab.
   2. Navigate the tree view and verify that MyCatalogItem appears in your OS design.

You have completed this tutorial and successfully created a Catalog item and added the item to the OS design.