What to build when in WEC2013

[This is an update of a blog post I wrote a long time ago. Check the comments under that post if you have any questions (or comment on this post if your question is not answered in the old post)]

A question that keeps coming back on the forums is "I changed some code, but it does not end up in my image", or "I changed some registry values in platform.reg, but if I look at the device registry, it's not there!", or even "Why does a kernel build take so long?".

The source of these problems is build-related. You've got to understand the build system in order to know exactly what to do. This blog post aims to give you a clear handle on "What to build when"!

At first glance, WEC2013 seems to only offer two build command: "Build Solution" and "Rebuild Solution". There are however a lot more variations that can save you a tremendous amount of time in your day-to-day work with Visual Studio 2013 and Platform Builder.

Before we dive into build system commands and how to use them I'd like to make sure you understand you should never modify code in the PUBLIC or PRIVATE trees. If you need to change functionality in those code trees it is very important you clone that code to your BSP folder or OS Design folder first. The main reason is that changing code in the PUBLIC or PRIVATE folder will not result in the code changes to be automatically build and included in your kernel image. You'd have to manually build that code, make sure the updated libraries, dlls and/or exes are in the right place, and then rebuild your kernel. The reason why this can cause many problems is because any WEC update may overwrite your code changes and maintenance is a nightmare.

So, keep this in mind:

Never change code in the PUBLIC or PRIVATE trees; always clone to your BSP or OS Design first!

For help with this process see the following blog posts:

Cloning public code: An example
Manual Clone of Public Code
Cloning CalibrUi in Windows CE 6.0 (this may need some updating for WEC2013 but it will give you an idea)

In all the versions before WEC2013 Microsoft included build commands in the Advanced Build menu that would execute "blddemo" without the "-q" parameter. This results in the ENTIRE WINCEX00 tree being built, thereby overwriting many libraries, DLLs and EXEs that shipped as binary with CE/EC. After years of protest by all the embedded MVPs we finally managed to convince MS that these commands should be erased from the IDE. However, you can of course still execute blddemo without -q on the command line. This command is, and always has been, very dangerous because sometimes the binaries do not match the actual source code. This can happen when an update updates some libraries, but not the source code. This *should* not happen, but it does happen over and over again. Executing "blddemo" without the "-q" parameter will result in your CE tree being in an undetermined state and the only solution is a complete uninstall and reinstall of CE/EC. So, if you're working from the command line; NEVER EVER execute blddemo without the -q parameter! If you're not working from the command line; no worries!

Phew! Now that we got that out of the way let's see what build command we've got to use in what situation:

WEC2013 Build Commands

• Create a new OS Design (or add a new build configuration to an existing OS Design): Sysgen (Build Solution)

Since a new OS Design doesn't have anything in its build configuration's output folders (same with a new build configuration) you'll have to sysgen the entire solution (for that build configuration). The longest process, but luckily you don't have to do this many times (see below).

• Change Platform Settings: Make image


If you change any Platform Settings (like IMGNOKITL, IMGNODEBUGGER, IMGPROFILER) all you have to do is a Make Image.

• Change driver source code in your BSP: Build the driver and Make Image

If you change driver source code, all you have to do is just build the driver (WINCEREL must be set to 1 but it is set by default so unless you changed it there's no need to worry) and do a makeimg. If you only want to debug the driver you can also add the DLL to the Release Directory Modules list (menu Tools) and just restart the device (or reload the device driver on the device) without having to do a makeimg and download to device. Building just the driver is a simple right-click on the driver and Build in the IDE or "build" in the driver's folder on the command line.

• Change multiple source code files in your BSP: Build the BSP and Make Image

The safe option, this way you can't forget to rebuild anything. Building the BSP is a simple right-click on the PLATFORM\BSP folder and Build in the IDE or "build" in the BSP's root folder on the command line.

• Change platform.reg, bib, dat or db files in your BSP: Sysgen the BSP, Copy Files to Release Directory, Build All Subprojects and Make Image

A lot of steps, but this will still not take longer than a couple of minutes. If you change any of the platform.* files we need to re-filter (Sysgen) those files and make sure the filtered files are copied into the FLATRELEASEDIR (Copy Files to Release Directory). That last action did however clear the project binaries from the FLATRELEASEDIR so we need to make sure those binaries and settings are getting copied into the FLATRELEASEDIR again (Build All Subprojects) and finally we are ready to Make Image. Now your registry changes will be in the image (check reginit.ini to make sure, last entry wins).

• Change some source files and platform.reg, bib, dat or db files in your BSP: Build and Sysgen the BSP, Copy Files to Release Directory, Build All Subprojects and Make Image

Only difference with previous situation is that you now have to build the BSP to include the source code changes.

The "Build and Sysgen BSP" command can be executed by right clicking your BSP root node in the Solution Explorer and choosing "Build and Sysgen (cebuild -qbsp)". Notice the -q in that command? That shows you it's a good command...

• Change the workspace configuration (add or delete a component): Sysgen the entire workspace (Build solution)

For most components a simple Sysgen is enough. For some components (like when changing from RAM based registry to Hive based Registry) a Clean Sysgen is needed. This action takes the longest (anywhere from 5 minutes for a small workspace configuration on a very fast machine to a couple of hours for a really big configuration and a very slow machine). A Sysgen is a right-click on the workspace, Advanced Build Commands->Sysgen in the IDE or "blddemo -q" on the command line.

• After installing one or multiple WEC updates: Clean Sysgen the entire workspace (Rebuild solution)

To make sure all components are re-linked with the (possibly updated) libraries a Clean Sysgen is needed. This action takes the longest (anywhere from 5 minutes for a small workspace configuration on a very fast machine to a couple of hours for a really big configuration and a very slow machine). A Clean Sysgen can be performed by choosing Rebuild Solution from the build menu, or choosing Advanced Build Commands->Clean Sysgen in the IDE or "blddemo clean -q" on the command line.

Sometimes it's easier to build from the command line. If you are unsure what command to type you can always perform the action in the IDE first and watch the 3rd line in the build output window starting with "Starting Build:". Behind the colon is the exact command line for that action, eg Sysgen on the BSP: "Starting Build: SysgenPlatform %_TARGETPLATROOT% preproc&&SysgenPlatform %_TARGETPLATROOT% postproc", so on the command line you would type "SysgenPlatform %_TARGETPLATROOT% preproc" followed by enter and the 2nd command "SysgenPlatform %_TARGETPLATROOT% postproc" followed by enter.

If you use the commandline, make sure you never forget "-q" when running "blddemo"!

I hope this blog post will help you speed up your builds and lower your frustration with the build system!

PS. Also check out this tip (works for WEC2013 too) to further improve build speed if your BSP is using code from the PLATFORM\COMMON\SRC\SOC folders.

Good luck!