Lesson 4: Managing Catalog Items
One of Windows Embedded CE's most useful features is its catalog system. By using the catalog, developers can quickly and conveniently customize the Windows Embedded CE firmware to suit their needs. If you create a custom catalog item for each of your components, you can facilitate the installation and configuration of your components. This is a differentiating factor between ad-hoc and professional Windows Embedded CE solutions. For ad-hoc solutions, it might be sufficient to provide basic installation notes and a list of required SYSGEN variables, but professional software should include catalog items with proper values for SYSGEN variables and configuration settings.
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.
Catalog Files Overview
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.
Creating and Modifying Catalog Entries
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 catalog files manually outside of Platform Builder is unnecessarily time-consuming.
Catalog Entry Properties
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 Id A unique identifier string.
■ Name The name of the catalog component as it appears in the Catalog Items View.
■ Description An expanded description of the component, which appears when the user hovers the mouse pointer over the catalog item for several seconds.
■ Modules A list of files that belong to this catalog component.
■ Sysgen variable An environment variable for the catalog item. If your catalog component sets a SYSGEN variable, this is where to put it.
■ Additional Variables A 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 directory The location of the catalog item files. For a new BSP, set this property to the name of the BSP's directory.
Figure 1-6 Catalog 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.
Adding a New Catalog Item to an OS Design
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.
Using a Catalog Item for BSP Development
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 CDEFINES entry. 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.