What to build when...
A question that keeps coming back on the newsgroups 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!".
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"!
The first and most important thing to do is to delete two options from the Platform Builder Build menu: Build and Sysgen and Rebuild and Clean Sysgen. These commands will build the entire tree (so including any source in PUBLIC and PRIVATE). For us normal developers these commands do not make any sense. If you're not in the CE development team working at Microsoft you simply don't have all the source code. Rebuilding the entire tree may work, but it will override any installed QFE (QFE's contain updated binaries and sometimes, but not always, updated source code). After rebuilding the entire tree you will sooner or later encounter strange errors that are either very hard to fix, or just impossible to fix. There is no way to revert back to a clean tree once you've done a (Re)Build and (Clean) Sysgen. The only way is to completely remove Windows CE and reinstall. Don't forget to reinstall all QFE's after that as well (download the QFEInstaller tool to help with that).
Now you know why you often see me shouting NEVER EVER DO A BUILD AND SYSGEN! in the newsgroups...
The original Advanced Build Commands menu
- Step 1.
Right click on the toolbar and click Customize...- Step 2.
Click on menu Build, submenu Advanced Build Commands, then right click on Build and Sysgen and click Delete- Step 3.
Do the same for Rebuild and Clean Sysgen- Step 4.
Close the Customize window. The Advanced Build Commands menu should now have only 4 options: [Sysgen], [Clean Sysgen], [Build Current BSP and Subprojects] and [Rebuild Current BSP and Subprojects].
If you are still using Platform Builder for Windows CE 5.0 the instructions stay the same except the Build menu is Build OS and there's no submenu (everything is under the Build OS menu).
I know that some developers working with CE change code in the PUBLIC and PRIVATE trees. If you do that you need to do a build and sysgen to include your changes in your kernels BUT: You will end up with a corrupted CE installation. If you need to change PUBLIC or PRIVATE code you have to clone the code. Cloning code is in most cases not much more than a simple copy. Copy the sources you want to change to a folder in your BSP, change the sources file so that it builds a DLL instead of a lib and voila, you're done. I know I make it sound easier than it is, but taking a shortcut and modifying code in the PUBLIC or PRIVATE trees will prove to be a long way around in the long run.
Phew! Now that we got that out of the way let's see what build command we've got to use in what situation:
- Change Platform Settings: Make image
- Change driver source code in your BSP: Build the driver and Make Image
- Change multiple source code files in your BSP: Build the BSP and Make Image
- Change platform.reg, bib, dat or db files in your BSP: Sysgen BSP, Copy Files to Release Directory, Build All Projects and Make Image
- 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 Projects and Make Image
- Change the workspace configuration (add or delete a component): Sysgen the entire workspace
If you change any Platform Settings (like IMGNOKITL, IMGNODEBUGGER, IMGPROFILER) all you have to do is a 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.
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.
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 Projects) 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).
Only difference with previous situation is that you now have to build the BSP to include the source code changes.
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.
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" as "blddemo" without "-q" is a Build and Sysgen!
I hope this blog post will help you speed up your builds and lower your frustration with the build system!
Good luck!
No comments:
Post a Comment