Cloning public code: An example

For some strange reason, people are still changing public code and doing build and sysgen's on their Windows CE tree (read this to learn why this is a bad thing). Changing code in the PUBLIC and PRIVATE trees might seem like a shortcut but actually it is everything but a shortcut. When you clone the code before changing it in place you will save yourself hours and hours of build time. A targeted build of a cloned driver takes seconds, a clean build and sysgen takes hours.

Cloning is not difficult at all, so there is really no reason to change PUBLIC or PRIVATE code. To prove that it is not difficult (once you know what you are doing) I will show you how to clone PUBLIC code in this blog post. Note that there is an article by Steve Maillet and Mike Hall in MSDN about cloning public code too. They split the clone into a "LIB" part and a "DLL" part. I don't really like that method; I just merge the sources file into one that creates the DLL in one go. Have a look at the "split" method here.

I chose to clone NETUI, since this component is responsible for a lot of dialog boxes that you may want to change to match your systems specifications.

I am cloning NETUI on a Windows CE 6.0 tree, but it works exactly the same on a Windows CE 5.0 tree (apart from the OSDesign folder which is called PBWorkspaces in CE 5.0).

Prerequisites: A sysgenned OSDesign with the "Network UI" component included.

Let's start!

Copy the entire /WINCE600/PUBLIC/COMMON/OAK/DRIVERS/NETUI folder to your OSDesign, for instance /WINCE600/OSDesigns/MyOS/MyOS
Open a build window (in Platform Builder / VS2005 click "Open Release Directory in Build Window" from the menu "Build"
In the build window, type:

cd..
cd..
cd netui

Now type:

sysgen_capture -p common netui

This command will output a set of files in the current directory.
Since we only want to build netui, you can delete:

sources.btdrt
sources.ceddk
sources.iphlpapi
sources.k.iphlpapi
sources.ws2
sources.ws2k

Now intelligently merge sources. with sources.netui (we make the changes in the sources. file):
Make a backup of the sources. file (copy to sources.org) so you can always go back if needed
We are trying to build a DLL, so change TARGETTYPE=LIBRARY to TARGETTYPE=DYNLINK
We are building NETUI as a project in our workspace, so set the RELEASETYPE to LOCAL (RELEASETYPE=LOCAL)
We are not building a LIB anymore, so there's no need to preprocess the def file. Remove the following lines:

WINCETARGETFILE0=$(_RELEASELIBDIR)/$(TARGETDEFNAME).def
PREPROCESSDEFFILE=1

And add this line to tell the build system to use the local def file for the exports:

DEFFILE=$(TARGETDEFNAME).def

We don't need the resource file later (because we are not creating a lib that has to be transformed into a dll later), so remove the COPYRES=1 line and the WINCETARGETFILES line pointing to the res.
OSDesign SubProjects get build last, so we don't need to copy SYNCHRONIZE_DRAIN=1 from sources.netui to our sources. file
Since we are now building a DLL, copy the DLLENTRY line from sources.netui to sources.
Now move the entire SOURCELIBS and TARGETLIBS from sources.netui to sources.
and delete any references to netui (netui.lib/netui.res) itself (because we are building that now)
Change the paths to the target libraries from using the PUBLIC sysgened libraries to the libraries sysgened to your workspace, so change $(_SYSGENSDKROOT)/ to $(_PROJECTROOT)/cesysgen/sdk/ and $(_SYSGENOAKROOT)/ to $(_PROJECTROOT)/cesysgen/oak/
You can also delete the #xref lines, they are remains of older days (CE 2.11 era).
Now try to build (by typing "build" in the build window you still have open)
oops! Doesn't build. It can't find the standard include files... Add the following to the top of the sources file:

_ISVINCPATH=$(_WINCEROOT)/public/common/sdk/inc;
_OEMINCPATH=$(_WINCEROOT)/public/common/ddk/inc;$(_WINCEROOT)/public/common/oak/inc;$(_WINCEROOT)/public/common/sdk/inc;

And since this project is building OEM code (a kernel component) set WINCEOEM=1 to indicate we want to use the _OEMINCPATH (so if you really want to you can delete the _ISVINCPATH since we don't use that one).
Try to build again:

BUILD: [01:0000000048:ERRORE] /WINCE600/OSDesigns/MyOS/MyOS/NETUI/./btmgmtui.cpp(39) : fatal error C1083: Cannot open include file: '../bluetooth/sample/btenum/btenum.hxx': No such file or directory

So, one of the sources files is trying to include a header on a relative path. Since NETUI came from /WINCE600/PUBLIC/COMMON/OAK/DRIVERS/NETUI this path must be /WINCE600/PUBLIC/COMMON/OAK/DRIVERS/BLUETOOTH

Now there are 3 ways to solving this: Either add the /WINCE600/PUBLIC/COMMON/OAK/DRIVERS/NETUI folder to the include path (add INCLUDES=$(INCLUDES);/WINCE600/PUBLIC/COMMON/OAK/DRIVERS/NETUI) so that the header file can be found off the relative path, or change the source file including the header to use a full path to the header file, or copy the btenum.hxx file into the NETUI folder and change the source file including the header to use the local header file. I think the last option is the cleanest, so let's copy /WINCE600/PUBLIC/COMMON/OAK/DRIVERS/BLUETOOTH/SAMPLE/BTENUM/btenum.hxx to /WINCE600/OSDesigns/MyOS/MyOS/NETUI/btenum.hxx and change btmgmtui.cpp to #include "btenum.hxx"

Build again: 0 Warnings,  0 Errors. Whuuhooo!

Now there is one final thing we have to add to the NETUI sources. file. We have to tell the build system we want to copy the final binary to the _FLATRELEASEDIR so our netui.dll will overwrite the default one from the PUBLIC/COMMON folder. Add WINCEREL=1 to the top of the sources. file.
Now add the NETUI project to your workspace. In the Platform Builder VS IDE click "Add Existing Subproject..." from the "Project" menu. Browse to the /WINCE600/OSDesigns/MyOS/MyOS/NETUI folder, select "Sources/Dirs Files" from the "Files of type" dropdown list, select the sources. file, and click "Open"
In the Solution Explorer window you can now find your NETUI component under the "SubProjects" node. Right click NETUI and click "Rebuild" to see if you can build the project from the IDE. It should all build fine.
If all builds fine, you can delete the sources.netui and the sources.org files since you no longer need them now.
The "Insert existing project" action created a couple of files for you. One of those files is a bib file. BIB files are used to indicate which files need to be included in the image. Since we cloned NETUI, but did not remove it from the OSDesign features, we now have 2 references to NETUI in the combined BIB files (one is in COMMON.BIB and the other in our newly generated NETUI.BIB). We don't need an extra reference in the BIB files, all we want is overwrite the default NETUI.DLL in the _FLATRELEASEDIR, so you can remove this reference from the newly generated NETUI.bib.
Now you can change whatever you need to change in NETUI without worrying about messing up the PUBLIC portion of the WINCE tree or having to do a "Clean Build and Sysgen".

If you have followed all the steps above your final NETUI sources. file should look like this:

_ISVINCPATH=$(_WINCEROOT)/public/common/sdk/inc;
_OEMINCPATH=$(_WINCEROOT)/public/common/ddk/inc;$(_WINCEROOT)/public/common/oak/inc;$(_WINCEROOT)/public/common/sdk/inc;
 
WINCEOEM=1
WINCEREL=1
 
TARGETNAME=netui
TARGETTYPE=DYNLINK
RELEASETYPE=LOCAL
 
TARGETDEFNAME=$(TARGETNAME)
DEFFILE=$(TARGETDEFNAME).def
 
DLLENTRY=_DllEntryCRTStartup
 
CONDITIONAL_INCLUDES=prshtp.h
 
SOURCELIBS=
 
TARGETLIBS=/
    $(_PUBLICROOT)/common/oak/lib/$(_CPUINDPATH)/btenum.lib /
    $(_PROJECTROOT)/cesysgen/sdk/lib/$(_CPUINDPATH)/iphlpapi.lib /
    $(_PROJECTROOT)/cesysgen/oak/lib/$(_CPUINDPATH)/btdrt.lib /
    $(_PROJECTROOT)/cesysgen/sdk/lib/$(_CPUINDPATH)/ws2.lib /
    $(_PROJECTROOT)/cesysgen/oak/lib/$(_CPUINDPATH)/ceddk.lib /
    $(_PROJECTROOT)/cesysgen/sdk/lib/$(_CPUINDPATH)/coredll.lib
 
SOURCES= /
    netui.c /
    getip.c /
    ipaddr.c /
    getuser.c /
    linecnfg.c /
    wnet.c /
    netcard.c /
    certui.cpp  /
    showcert.cpp /
    eaptlscfg.cpp /
    network.c /
    transdlg.c /
    reg.c /
    util.c /
    wzcui.c /
    wzcprops.c /
    btmgmtui.cpp /
    WzcQuickCfgUi.c /
    IpQuickCfgUi.c /
    QuickConfigUi.c /
    WzcLogging.c /
    WzcPopup.c /
    netui.rc  /
    wnet_wrapper.cpp /
    netui_wrapper.cpp /
    getuser_wrapper.cpp /
    gwes_wrapper.cpp /
    getip_wrapper.cpp /
    linecnfg_wrapper.cpp /
    transdlg_wrapper.cpp /
    network_wrapper.cpp /
    netcard_wrapper.cpp
 
FILE_VIEW_PARAMETER_FOLDER= /
    NETUI.bib /
    NETUI.reg /
    NETUI.dat /
    NETUI.db /
    ProjSysgen.bat /
 
FILE_VIEW_ROOT_FOLDER= /
    prelink.bat /
    postlink.bat /
 
PRELINK_PASS_CMD=prelink.bat
POSTLINK_PASS_CMD=postlink.bat

Reference: http://guruce.com/blogpost/cloningpubliccodeanexample