Nicolas Besson: Microsoft Windows Embedded CE 6.0 Exam Preparation Kit

After this lesson, you will be able to:

■ Customize the content of the catalog.

■ Add a new component entry to a BSP catalog.

Estimated lesson time: 20 minutes.

The Windows Embedded CE catalog uses files in Extensible Markup Language (XML) format with a .pbcxml file-name extension. The catalog includes a large number of .pbcxml files, located inside the WINCEROOT directory. Platform Builder automatically enumerates these files to generate the Catalog Items View in Solution Explorer.

Platform Builder parses the following directories to enumerate catalog items:

■ Public catalog files%_WINCEROOT%\Public\< any subdirectory> \Catalog\

■ BSP catalog files%_WINCEROOT%\Platform\< any subdirectory >\Catalog\

■ Third-party catalog files%_WINCEROOT%\3rdParty\< any subdirectory >\Catalog\

■ Common system-on-chip (SOC) files%_WINCEROOT%\Platform\Common\Src\soc\< any subdirectory >\Catalog\

The 3rdParty folder usually contains standalone applications or source applications that can be included and distributed as part of an OS design. By enumerating the .pbcxml files in the 3rdParty folder, Platform Builder provides a way to add entries to the Catalog Items View for those components.

To add a new catalog item to the Windows Embedded CE catalog, you can create a copy of an existing catalog file (.pbcxml file) and then edit the file content by using the Catalog Editor provided with Platform Builder. You can also create a new catalog file in Platform Builder if you open the File menu in Visual Studio, point to New, and then select File. In the New File dialog box, under Platform Builder for CE 6.0 R2, select Platform Builder Catalog File, and then click Open.

Always edit catalog files by using the Catalog Editor provided with Platform Builder. There are no settings that require you to work with a text editor such as Notepad. Opening and editing cata­log files manually outside of Platform Builder is unnecessarily time-consuming.

Each catalog entry has a number of properties that you can modify in Platform Builder, as illustrated in Figure 1-6. The most important properties include the following

■ Unique IdA unique identifier string.

■ NameThe name of the catalog component as it appears in the Catalog Items View.

■ DescriptionAn expanded description of the component, which appears when the user hovers the mouse pointer over the catalog item for several seconds.

■ ModulesA list of files that belong to this catalog component.

■ Sysgen variableAn environment variable for the catalog item. If your catalog component sets a SYSGEN variable, this is where to put it.

■ Additional VariablesA collection of additional environment variables for the catalog item. This is possibly the most important part of the catalog component in a BSP, because this field enables you to set environment variables used in sources, .bib, and .reg files to control the build process. You can also use this field to generate dependencies on other components.

■ Platform directoryThe location of the catalog item files. For a new BSP, set this property to the name of the BSP's directory.

Figure 1-6Catalog item properties

Each catalog component must have a unique ID, typically composed of the vendor and the component names. When you clone a BSP by using the Clone Catalog Item feature, Platform Builder creates a unique name for the cloned component automatically; however, when editing catalog files manually, be sure to use unique identifiers.

To use a new catalog file or catalog item, ensure that the corresponding .pbcxml file exists in a subfolder called Catalog under a subdirectory of the 3rdParty or Platform directories, and then click the Refresh Catalog Tree button in the Catalog Items View in Visual Studio. Platform Builder dynamically regenerates the catalog by traversing the 3rdParty and Platform directories and processing any existing catalog files. With the new component listed in the Catalog Items View, you can include it in the OS design by selecting its check box, as explained earlier in Lesson 1.

Now that you have added your new catalog component and learned how to set item- specific environment variables, you can use this technique to include the component in a BSP, set C/C++ build directives, and modify system registry settings in the runtime image. When other developers using this BSP select your catalog item in an OS design project, they will implicitly use the settings you specified. To include a catalog component in a BSP, you need to edit the BSP's Platform.bib file and add a conditional statement based on your settings. You can choose to include a component if a variable is or isn't defined by using if-else statements. Note that it might be necessary to run the Rebuild Current BSP and Subprojects command, which you can find in Visual Studio on the Build menu, under Advanced Build Commands, for changes to the .bib and .reg files to take effect. Chapter 2 covers the Rebuild Current BSP and Subprojects command in more detail.

To set a C/C++ directive based on an environment variable that you specified in the catalog item's properties, you can use a conditional statement in the sources file based on the variable and add a CDEFINESentry. You should generally try to avoid setting C/C++ build directives based on catalog item properties, as this approach will make it difficult to distribute a binary version of your BSP in the future.

You can also change entries in the system registry by using conditional statements. You only need to edit the .reg files to include or exclude certain registry files related to the new component.

Some catalog items do not support direct cloning. To clone these components, you must create either a new catalog file, if you are creating a new entry under the 3rdParty folder, or a new entry in a BSP's existing catalog file. In any case, you should verify that the original values for all SYSGEN and additional environment variables are preserved. Do not forget to change the ID, because each item in the catalog must have a unique ID, as mentioned earlier in this lesson.

The catalog in Platform Builder for Windows Embedded CE 6.0 R2 supports component dependencies. To specify that a component is dependent on another component, you must set the SYSGEN or Additional Variables field for the component of the catalog item, and then include this value in the form of an additional environment variable in the dependent component. For example, if you have catalog components in your BSP for both a display driver and a backlight driver for the display, you can set the Additional Variables field for the display driver to BSP_DISPLAYand the Additional Variables field for the backlight driver to BSP_BACKLIGHT.If you now want the display driver to be dependent on the backlight driver, you can edit the catalog entry for BSP_DISPLAYin the Catalog Editor and add BSP_BACKLIGHTto the additional environment variables. Then, whenever you include the display driver in an OS design, Platform Builder automatically includes the backlight driver as well. The Catalog Items View will show the check box of the backlight driver with a green square to indicate that this component is included as a dependency of the display driver.