Build from the Top Down (Compact 2013)

3/26/2014

This section details the steps involved in a typical Windows Embedded Compact 2013 build. It also describes the tools that coordinate calls to build.exe, as well as other supporting tools that you use to create 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:

1. $(_TGTCPU): CPU architecture being used
2. $(_TGTPROJ): OS design being used (for Windows Embedded Compact 2013, this is always CEBase)
3. $(_TGTPLAT): Platform (board support package) being built

To create a build window, open a command window and call 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 depends on additional batch files. These batch files are located in %_WINCEROOT%\Public\Common\Oak\Misc, along with most of the other files that control the build. To learn more about a build step or to understand the build in more detail, 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 that this section discusses. 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 are blddemo.bat, cebuild.bat, cebldtree.bat, cebuild1.bat, build.exe, and sysgen.bat. The number in each box before the file name gives the order of execution.

Build Steps

Using the environment set up by wince.bat, the source code, the configuration files, and the build batch files in %_WINCEROOT%\Public\Common\Oak\Misc, the build process can begin. The build process is an ordered series of steps, with completion of each step required before the next one can occur.

The following figure shows the steps, which are described in greater detail in the topics listed below under “In This Section.”

Note

The [-c] syntax denotes that -c is optional.

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. Files with the .bif extension determine whether %_WINCEROOT%\Platform\Common and %_WINCEROOT%\Platform\$(_TGTPLAT) are up to date, and "cleanplat" removes these 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 Build Variables

The following miscellaneous build variables are used to instruct jobs, the compiler, and specify the number of threads to run.

• WINCEREL: Instructs jobs to move most files to the flat release directory as they are built, instead of in a large batch when buildrel runs.
• WINCECOD: Instructs the compiler to generate .cod files during compilation for each source file that is 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 can 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.

In This Section

• Build Step: Build OS
  Describes how operating system code is compiled, usually as a separate step from the other build steps.

• Build Step: Sysgen OS
  Describes how libraries created during the Build OS step are linked together.

• Build Step: Build Platform\Common
  Describes what occurs when build.exe runs in the %_WINCEROOT%\Platform\Common directory.

• Build Step: Build Platform\$(_TGTPLAT)
  Describes what occurs when build.exe runs in the %_WINCEROOT%\Platform\$(_TGTPLAT) directory.

• Build Step: Copy All to Release Directory
  Describes how files are copied to the flat release directory.

• Build Step: Create Image
  Describes how the OS image is created.

See Also

Concepts

How the Build System Works
Compile and Link with the Build Tool