OLIVIER BLOCH

TECHNICAL EVANGELIST

MICROSOFT CORPORATION

To gain a high-level understanding of the CE OS Build System, enabling you to leverage its features to build what you

want in the most efficient manner possible

Definition:A repository of build tools, build scripts, source code and pre-built binaries that enable customers to build Windows CE OS images

Platform BuilderPlatform Builder implements thin UI over Build SystemBuilding from Platform Builder and Build System directly are identical

Microsoft Visual Studio 2005 for Smart Devices (VSD)

Share compiler technologySmart Device apps are CE-compatible

Platform Builder & VSD share common shell

VCBuildMSBuild

CE OS Build

Platform BuilderVisual Studiofor Devices

What you need to build an OS image:Microsoft Source Code (Core OS & BSPs)Build toolsThird-party BSP/appsA set of build environment variablesOutput: an image file that can run on a device CE OS images

The environment defines what gets built:Sysgen variables: the set of OS featuresImage variables: Kernel Dbg Support, Profiling, etc.Release directory: location of final imageProject directory: location of generated OS bitsBoard Support Platform (BSP): the hardware platformCPUDebug level: Debug, Release, ShipCoreOS: CE, PPC, SmartfonDefaults for all values except CoreOS, BSP and CPUSet of dependency trees (deptree)

ManuallySet Sysgen variablesSet Image variablesSet release directoryCall build environment initialization script (Wince.bat)

From Platform BuilderChose starting configuration and BSP(s) from New Project WizardChoose features (Sysgens) from catalogChoose Image settings

Where Build System files physically reside:Tree root (%WINCEROOT%)Release Directory (%_FLATRELEASEDIR%) –The final location of the generated image fileProject Directory (%_PROJECTROOT%) – The location of OS-generated files. Includes SDK files.Public Folder (%_WINCEROOT%\Public) –Microsoft Public CodeDependency Definition Files ((%_WINCEROOT%\Public\CEBASE\OAK\Misc) –Define the feature granularity and dependencies

Build Binaries (%WINCEROOT%\Public\Common\OAK\Bin\I386 ) – The tools to build the treeBuild Scripts (%WINCEROOT%\Public\Common\OAK\Misc) - Scripts that drive buildOEM Output (%_PROJECTROOT%\Cesysgen\OAK) -The OEM binary, libraries and header filesSDK Output (%_PROJECTROOT%\Cesysgen\OAK)-The SDK binary, libraries and header filesBSP Directory (%_WINCEROOT%\Platform)

Common Platform Code (%_WINCEROOT%\Platform\common) Microsoft Private Code (%_WINCEROOT%\Private)

Build – compile and link Sysgen – link the OS DLLs, generate headersBuildrel – Copy all files needed to generate the final image to release directoryMakeimg – Generate OS image from binaries, non-binary files, BIB and REG files

For each deptreeCompile PrivateCompile Public

For each deptreeSysgen

Compile and Sysgen BSP

Build Apps (PB Subprojects)

Build Release Directory Build OS Image

Source Code

BUILD

Static Libs & Resource

files

Build.exe compiles a tree

Compiled Deptree Sysgen Variables

Sysgen Phase

Custom Run-times SDK

Defined in Public\<Deptree>\Cesysgen\makefile

.BIB, .REG and .DAT Files Binaries and Files

Image Flags

Makeimg Phase

Run-Time Image (e.g., .BIN)

Makeimg.exe generates final OS image

Blddemo.bat

Cebuild.bat

BuildRel.bat

Makeimg.exe

Cebuild.bat

Build.exe

Sysgen.bat

Sysgen.bat

Cesysgen.bat

The key batch files that are called

Application developerDriver developerBSP developerPublic Microsoft code-based derivatives developer

Compile OS

Generate Run-

times & SDK

Build BSP Build Apps

Build Image

What gets built and how to invoke

Blddemo Blddemo -q Blddemo -qbsp

Compile OS

Generate Run-

times & SDK

Build BSP Build Apps

Build Image

What gets built and where personas start

PublicDerivatives

All: if sysgenschanged

BSP/DriversDeveloper

ApplicationDeveloper

Persona CommandPublic Derivatives Blddemo

BSP Author Blddemo -qbsp

BSP Driver Blddemo –qbsp

Apps / OS Driver Blddemo –qbspOR Targeted Build & Makeimg

All: On Sysgen Change Blddemo -q

Blddemo Compile each deptree, sysgen OS, compile and sysgen BSP, build PB Subprojects, buildrel & makeimgUse only if doing Microsoft derivativesPersona: Microsoft derivatives developer

Blddemo clean –qClean sysgen of OS, compile and sysgen BSP, build PB Subprojects, buildrel & makeimgUse if not doing MS derivatives or public code has not changed.Persona: All

Blddemo –qbspCompile and sysgen BSP, build PB Subprojects, buildrel &

makeimg. Personas: All. Minimal build for BSP, Drive and App developers. Use if feature set (SYSGENs) has not changed.

Blddemo –qbsp NOMAKEIMGCompile and sysgen BSP, build PB Subprojects, buildrelPersonas: All

Blddemo –qbsp NORELCompile and sysgen BSP, build PB Subprojects

Personas: All, use to quickly build BSP and apps

Using callouts to extend the build system:Setting Release DirectorySetting Project DirectoryBuild System Callouts

Developer environment calloutProject environment calloutDeveloper post-buildrel calloutProject post-buildrel calloutPre-makeimg calloutPost-makeimg callout

Build.exeSources/Dirs-based build systemProject author defines minimal makefilesnippet to drive buildMulti-passed based build driven by XML fileNMAKE-based

Makefile – Includes makefile.defMakefile.def – Master makefile for all generalized build rulesSources – User-defined macros to drive compilationSources.cmn – User-defined file for common settingsSources.default – Microsoft-defined file with defaultsSources.ce – Microsoft-defined file with defaults for CE

Sources.%ReleaseType% - Microsoft-defined file with release directory macrosMakefile.inc – User-defined file for custom build rules

Automatically included if user defines target file macros

Makefile Makefile.def

Common\oak\misc\Sources.default

$(BUILDROOT)\Sources.cmn

Sources

Common\oak\misc\Sources.ce

$(_PROJECTROOT)\oak\misc\makefile.inc

Common\oak\misc\Sources.$(_ReleaseType)

Makefile.inc

Scans files to create DB of file-level dependencies

Stored in %BuildRoot%\build.datTraverse dirs/sources build order structureCalls NMAKE for each target file(s) for each build pass

XML-driven build engine:Buildtable.xml – drives the build phaseOne set of passes per buildrootBuildroot is defined as the top level directory containing a dirs file

Scan CPP Files For Each Phase

Delete out of date targets

Call NMAKE to build target

Walks Dir order and builds each sources project

Can be auto-generated by PB wizardsMacros

SOURCESTARGETTYPETARGETNAME

Can use makefile.inc for custom build rules

Adding additional targets to your projectWINCETARGETFILE0

Build target that gets built firstUse pseudotargets

WINCETARGETFILES Build targets that get built lastDon’t use pseudotargets

PRELINK_PASS_CMDCallout before linkage

POSTLINK_PASS_CMD Callout after linkage

#In your sources file

#Pass 0 ruleWINCETARGETFILE0=AddCopyrights

#Additional Files to buildWINCETARGETFILES=.\DropDir\myheader.h

#Pre and post link callouts.#Callouts must return zero on successPOSTLINK_PASS_CMD=mypostlink.batPRELINK_PASS_CMD=myprelink.bat

#In your makefile.inc

#Make foo.idl if source or CR have changedAddCopyrights: foo.idl

Foo.idl : Raw.idl CopyrightHeader.txtcopy CopyrightHeader.txt Raw.idl Foo.idl

#Make myheader.h from source.hDropDir\myheader.h : source.h

SomeProcess source.h DropDir\myheader.h

#It a good practice to add a clean ruleCleanAll::

delete foo.idldelete DropDir\myheader.h

Dependency Tree (deptree)PB Subproject as a dirs directoryPB Subproject as a sources directoryBSP directory Platform/CommonMicrosoft Public directory

In some case entire debug OS is too largeEnable kernel debugger in retail builds (IMGNODEBUGGER not set)Set COMPILE_DEBUG=1 in sources project

This turns off Optimizations, defines DEBUG compiler flag but builds against Retail OSCan be wrapped in WINCESHIP macro

#In your sources file

#Use a ship flag to run off all Debug builds

!if “$(WINCESHIP)”==“”COMPILE_DEBUG=1!endif

Author and edit Smart Device Project in Visual StudioAdd VSD to OS design’s SolutionReference in sources fileAdd BIB and REG dataBuild CE OS design

Best practices for speeding up builds:Build on a separate drive (don’t build in system drive)Defragment drive periodicallyTurn off virus checking on build rootWindows Vista: turn off file indexing

What to check in if using source controlCheck in all public Microsoft code unless doing derivativesIf doing derivatives, don’t check in \lib\* and \target\* directories under deptrees

By its nature, the build is very automatable:Call Wince.bat and Blddemo.bat from scriptsBuild sources projects by calling Build.exe directlyPB OS Designs can also be built via automation

Time invested in understanding the Build System will pay dividendsPut code in the proper locationsDon’t modify public code unless you have toUse the shortest build command possibleDon’t build anything you don’t have to

© 2006 Microsoft Corporation. All rights reserved.This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.