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.
Exporting a Catalog Item from the Catalog
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.
Catalog Component Dependencies
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_DISPLAY and 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_DISPLAY in the Catalog Editor and add BSP_BACKLIGHT to 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.
Lesson Summary
Platform Builder for Windows Embedded CE 6.0 R2 comes with a file-based catalog system that you can use to contain your own catalog items by including them in separate catalog files in the Platform or 3rdParty directory within the %_WINCEROOT% directory tree. The file format of catalog files is XML and the file-name extension is .pbcxml. Platform Builder automatically enumerates the .pbcxml files when you start Visual Studio or refresh the Catalog Items View in Solution Explorer. To add a new catalog item to the Windows Embedded CE catalog, you can start with a new catalog file or create a copy of an existing catalog item and then edit the file content by using the Catalog Editor. There is no need to edit .pbcxml files by using a text editor, such as Notepad, because all settings are available directly within Platform Builder. Among other things, you can specify SYSGEN and additional environment variables for conditional C/C++ build directives, registry modifications, and dependency definitions.
Lesson 5: Generating a Software Development Kit
Developers who want to create applications for a target device require a Software Development Kit (SDK).
