After this lesson, you will be able to:
■ Locate and analyze build reports.
■ Diagnose and solve build issues.
Estimated lesson time: 15 minutes.
Understanding Build Reports
When you perform a build either in the Visual Studio IDE or the command prompt, the build process outputs a significant amount of build information. The build system tracks this information in a Build.log file. Details about compilation or linker warnings and errors also can be found in the Build.wrn and Build.err files. If you started a complete build or a Sysgen operation for an OS design by using one of the corresponding commands on the Build menu in Visual Studio, the build system writes these files in the %_WINCEROOT% folder (by default, C:\Wince600). On the other hand, if you perform a build for only a particular component, such as by right- clicking a subproject folder in Solution Explorer and clicking the Build command from the context menu, the build system writes these files in that specific directory. In either case, the Build.wrn and Build.err files only exist if you encounter warnings and errors during the build process. However, you do not need to open and parse through these files in Notepad or another plain-text editor. Visual Studio 2005 with Platform Builder for CE 6.0 R2 displays this information during the build process in the Output window. You can also examine status messages, warnings, and errors in the Error List window that you can display by clicking Error List, which is available under Other Windows on the View menu.
Figure 2-6 shows the Output window and the Error List window in undocked view. The Output window displays the Build.log content if you select Build from the Show Output From list box. The Error List window displays the contents Build.wrn and Build.err files.
Figure 2-6 Output window and Error List window with build information in Visual Studio
Specifically, you can find the following information in the build log files:
■ Build.log Contains information about the individual commands issued within each phase during the build process. This information is useful for analyzing both the build process in general, and build errors in particular.
■ Build.wrn Contains information about warnings generated during the build process. If possible, try to eliminate or at least identify the reasons for the warnings. The information in Build.wrn is also included in Build.log.
■ Build.err Contains specific information about build errors encountered during the build process. This information is also available with additional details in Build.log. This file is created only when an error occurs.
The build system keeps track of skipped and entered build phases in the Build.log file. For example, the entry CEBUILD: Skipping directly to SYSGEN phase indicates that the build system skipped the Compile phase for a component. You can determine where the Sysgen phase begins, how the build process transitions from SYSGEN to BUILD, and how BUILD eventually leads to MAKEIMG.
Troubleshooting Build Issues
While analyzing build log files can give you great insight into the build process in general, it is most useful when troubleshooting build errors. If an error message is related to a source code file, you can jump to the relevant line of code by double- clicking the message entry in the Error List window. However, not all build errors are related to source code. Linker errors due to missing library references, sysgen errors due to missing component files, copy errors due to exhausted disk capacities, and make run-time image errors due to incorrect settings in run-time image configuration files can also cause a build process to fail.
Errors during the Sysgen Phase
Sysgen errors are generally the result of missing files. The Build.log file might provide detailed information about the reason. Components that you recently added to or removed from an OS design can cause this type of error if the required dependencies are unavailable. To diagnose a Sysgen error, it is a good idea to verify all changes related to catalog items and their dependencies. Also note that some components require you to perform a clean Sysgen build instead of a regular Sysgen cycle. Typically, you should not use the Clean Sysgen command because performing a clean Sysgen in Release or Debug build configuration requires you to perform a regular Sysgen in the other build configuration as well. However, when adding or removing catalog items and encountering Sysgen build errors afterward, during the next regular Sysgen, you might have to perform a clean Sysgen build to solve the issue.
Errors during the Build Phase
Build errors are typically caused by compiler errors or linker errors. Compiler errors are syntax errors, missing or illegal parameters in function calls, divisions by zero and similar issues that prevent the compiler from generating valid binary code. By double- clicking a compiler error, you can jump to the critical line of code. Keep in mind, however, that compiler errors can be the results of other compiler errors. For example, an incorrect variable declaration can cause numerous compiler errors if the variable is used in many places. It is generally a good idea to start at the top of the error list, fix the code, and recompile. Even small code changes can often eliminate a very large number of errors from the list.
Linker errors are harder to troubleshoot than compiler errors. They are typically the result of missing or incompatible libraries. Incorrectly implemented APIs can also result in linker errors if the linker cannot resolve external references to exported DLL functions. Another common cause has its root in incorrectly initialized environment variables. Build files, specifically the Sources file, use environment variables instead of hard-coded directory names to point to referenced libraries. If these environment variables are not set, the linker will not be able to locate the libraries. For example, %_WINCEROOT% must point to C:\Wince600 if you installed Windows Embedded CE in the default configuration and %_FLATRELEASEDIR% must point to the current release directory. To verify the values of environment variables, open the Build menu in Visual Studio and select Open Release Directory in Build Window, and then at the command prompt use the set command with or without an environment variable, such as set _winceroot. Running the set command without parameters displays all environment variables, but be aware that this list is long.