Build from the Top Down (Compact 7)
3/12/2014
This section details the steps involved in a typical build. It also describes the tools that orchestrate calls to build.exe, as well as other supporting tools that are used in creating your final image.
Inputs
The following inputs are used during the build:
- Environment variables
- Source code
- Configuration files (such as sources files, dirs. files, .def files, and .bib files)
Outputs
The build produces the following outputs:
- An image that you can download to and execute on the device
- A flat release directory that contains all of the modules in the image
- Many intermediate libraries
Batch Files
The build system uses the environment variables and configuration files to determine what to build and how to build it. %_WINCEROOT%\Public\Common\Oak\Misc\Wince.bat is responsible for setting environment variables that provide default values. The caller of wince.bat is responsible for passing the following three parameter values, shown in order:
- $(_TGTCPU): CPU architecture being used
- $(_TGTPROJ): OS design being used (for Windows Embedded Compact 7, this is always CEBase)
- $(_TGTPLAT): Platform (board support package) being built
You can create a build window by opening a command window and calling wince.bat with the parameters listed above. After the parameters are set, wince.bat calls other batch files to set up the rest of the environment.
Wince.bat is not the only batch file that the build system uses. Although wince.bat sets up the initial environment, the execution of the whole build system hinges on additional batch files. These batch files are located in %_WINCEROOT%\Public\Common\Oak\Misc, along with most of the other files that govern the build. To learn more about a build step or to understand the build in more detail, you can examine the batch files and build files directly.
The following figure shows the order of the batch file calls to blddemo.bat, which should help you understand the high-level build steps discussed in this section. In this figure, the calls to the batch files go depth-first, from top to bottom and then left to right, so the first six calls in the figure would be blddemo.bat, cebuild.bat, cebldtree.bat, cebuild1.bat, build.exe, and sysgen.bat. The number in each tile before the file name gives the order of execution.
.png "Build process batch file calls")
Build Steps
Using the environment set up by wince.bat, the source code, and the configuration files, and the build batch files in %_WINCEROOT%\Public\Common\Oak\Misc, the build process can start in earnest. The build process is an ordered waterfall of steps, with each one feeding the next.
The following figure shows the steps.
Note
The [-c] syntax denotes that -c is optional.
.png "Build process steps")
The steps are described in the topics shown in the following table:
| Topic | Description |
|---|---|
How operating system code is compiled, usually as a separate step from the other build steps. |
|
How libraries created during the Build OS step are linked together. |
|
What occurs when build.exe runs in the %_WINCEROOT%\Platform\Common directory. |
|
What occurs when build.exe runs in the %_WINCEROOT%\Platform\$(_TGTPLAT) directory. |
|
How files are copied to the flat release directory. |
|
How the OS image is created. |
Building "Clean"
By default, build.exe compiles only if targets are out of date; that is, if the time stamps for the sources files do not match the .lib files that they produced. As discussed previously, calling build.exe with the -c flag (the "clean" option) forces a recompile and relink. You can force a recompile all throughout the build process by calling blddemo -c, although this is not commonly done.
Blddemo "clean" deletes $(SG_OUTPUT_ROOT), causing the Sysgen OS step to write to an empty directory. It is important to pass the "clean" flag when SYSGEN_ variables change so that stale binaries do not remain in the $(SG_OUTPUT_ROOT). Similarly, blddemo "cleanplat" marks the binaries in %_WINCEROOT%\Platform\Common and %_WINCEROOT%\Platform\$(_TGTPLAT) for deletion. .bif files determine whether %_WINCEROOT%\Platform\Common and %_WINCEROOT%\Platform\$(_TGTPLAT) are up to date, and "cleanplat" removes these .bif files, triggering a call to build.exe. The binaries previously marked for deletion are overwritten by the new binaries that build.exe created. The file %_WINCEROOT%\Public\Common\Oak\Misc\CleanOS.bat is responsible for interpreting the "clean" and "cleanplat" flags.
Miscellaneous Useful Build Variables
- WINCEREL: When set, jobs will move most files to the flat release directory as they are built instead of in a large batch when buildrel executes.
- WINCECOD: Instructs the compiler to generate .cod files during compilation for each source file compiled. These .cod files are large files that provide an assembly-level description of the compiled code. They can be useful for understanding compiler optimizations.
- BUILD_MULTIPROCESSOR: This variable’s value specifies the number of threads that build.exe is allowed to run simultaneously. If it is not set, build.exe minimizes build time by using multiple threads based on the number of CPUs in the system. Setting this value to 1 can be useful for debugging intermittent build failures, which are often the result of synchronization issues in sources files.