Lesson 2: Configuring Windows Embedded CE Subprojects
A subproject is a Visual Studio project inserted into a parent project to include relatively independent components in an overall solution. In our case, the parent project typically corresponds to an OS design. Subprojects can take the following forms:
■ An application (managed or unmanaged).
■ A dynamic-link library (DLL).
■ A static library.
■ An empty project containing only configuration settings.
Subprojects are a good way to include a particular application, device driver, or other code module in an OS design and to maintain this code and the OS design together as one solution.
After this lesson, you will be able to:
■ Create and configure subprojects.
■ Build and use subprojects.
Estimated lesson time: 20 minutes.
Windows Embedded Subprojects Overview
Platform Builder for Windows Embedded CE enables you to create subprojects as part of an OS design. Because subprojects are both modular and easily redistributable, they provide a convenient way to add applications, drivers, or other files to your OS design without manually including them in the build tree as part of the BSP. You can also create subprojects for internal test applications and development tools to make it quick and easy to build these tools and run them on a test device.
Types of Subprojects
Windows Embedded CE supports the following subproject types:
■ Applications Win32® applications with a graphical user interface (GUI), programmed in C or C++.
■ Console applications Win32 applications without a GUI, programmed in C or C++.
■ Dynamic-link library (DLL) Drivers or other code libraries, loaded and used at run time.
■ Static library Code modules in the form of library (.lib) files that you can link to from other subprojects or export as part of the OS design's SDK.
■ TUX dynamic-link library Windows Embedded CE custom test components for the Microsoft Windows CE Test Kit (CETK), as explained in more detail in Chapter 4.
Creating and Adding Subprojects to an OS Design
It is straightforward to create a new subproject or add an existing project as a sub- project to an OS design. For the most part, you can use the Windows Embedded CE Subproject Wizard to accomplish this task, which you can start by right-clicking the Subprojects folder in Solution Explorer and clicking Add New Subproject or Add Existing Subproject. However, an understanding of the details, including the purpose of the various subproject types, the files and settings created by the CE Subproject Wizard, the build process, and customization possibilities for subprojects, is still helpful.
The CE Subproject Wizard creates a subfolder in the OS design folder, which contains all the required configuration files, including:
■ <Name>.pbpxml An XML-based file that contains metadata information about the subproject. This file references the .bib, .reg, sources, and dirs files to build the subproject.
■ <Name>.bib A binary image builder (.bib) file used during the makeimg step in the build process to dictate files to include in the binary image.
■ <Name>.reg A registry file with settings to be included in the final run-time image.
■ Sources A Windows Embedded CE sources file. This is a makefile that contains build options to control the Windows Embedded CE build process.
■ Makefile A file used in association with the sources file in the Windows Embedded CE build process.
To make a copy of a subproject for later use, open your OSDesigns folder (%_WINCEROOT%\OSDesigns), and then open the solution folder for your OS design. The solution folder typically contains the <OS Design Name>.sln file and a folder named according to the OS design. Within this folder, you can find the definition file of the OS design <OS Design Name>.pbxml and several subdirectories. One of these subdirectories should be your Subproject folder, as illustrated in Figure 1-4. It is a good idea to back up this folder. You can then add it to any OS design later by right-clicking the Subprojects container in Solution Explorer and selecting Add Existing Subproject.
Figure 1-4 A subproject folder in an OS design project
Creating Windows Embedded CE Applications and DLLs
To add a Windows Embedded CE application or DLL to an OS design, use the CE Subproject Wizard to create the corresponding subproject. Although you can start with an empty subproject, it is generally more convenient to select a simple console or GUI application template, adding your own code afterward as necessary.
Creating Static Libraries
The CE Subproject Wizard also provides you with an option to create a static library, which you can then link to another subproject or export as part of an SDK. This is helpful for dividing up more sophisticated subprojects or providing more options to application developers who develop solutions for your hardware and firmware. If other subprojects in your OS design rely on a static library, you might have to adjust the build order of the subprojects to use the library efficiently. For example, if a Windows Embedded CE application uses your static library, you should build the library first so that the application build process uses the updated library.
Creating a Subproject to Add Files or Environment Variables to a Run-Time Image
Some subprojects do not necessarily include source code. For example, you can create an empty subproject by using the CE Subproject Wizard, modify the sources file, and set TARGETTYPE=NOTARGET to indicate you do not want to generate binary target files. You can then add files to the run-time image by adding corresponding references to the subproject's .bib file. You can also add registry settings to the subproject's .reg file and you can add SYSGEN variables by editing the subproject's Projsysgen.bat file. Although it is generally faster and more convenient to modify the .reg and .bib files and project properties of the OS design directly, creating a subproject for this purpose can be advantageous if you are planning to reuse customizations in multiple OS designs in the future.
Configuring a Subproject
Visual Studio provides a number of options in the project properties that you can configure to customize the build process for subprojects. To configure these settings, display the Property Pages dialog box for your OS design, as explained earlier in this chapter. You can then find the subproject properties under Subproject Image Settings. For each subproject added or created in the current OS design, you can configure the following parameters:
■ Exclude From Build Activating this option excludes the subproject from the build process of the OS design, meaning the build engine does not process the source files that belong to the selected subproject.