If you check the folders and files of a standard OS design, such as C:\Wince6OO\OSDesigns\OSDesignl, you will find that the project includes no Dirs files by default. If you include subprojects for custom components and applications, you will find a Sources file in each subproject's root folder instead. The Sources file provides more detailed information about the source-code files, including build directives, which a Dirs file cannot provide. However, a source-code directory can only contain one Dirs file or one Sources file, not both. That means that a directory with a Sources file cannot contain subdirectories with more code. During the build process, Nmake.exe uses the Sources files to determine what file type to build (.lib, .dll, or .exe), and how to build it. Similar to Dirs files, Sources files expect you to specify declarations in a single line, unless you terminate the line with a backslash to continue the declaration on the next line.
The following listing shows the content of a Sources file in the Device Emulator BSP. By default, you can find this file in the C:\Wince600\Platform\DeviceEmulator \Src\Drivers\Pccard folder.
WINCEOEM=1
TARGETNAME=pcc_smdk2410
TARGETTYPE=DYNLINK
RELEASETYPE=PLATFORM
TARGETLIBS=$(_COMMONSDKROOT)\lib\$(_CPUINDPATH)\coredll.lib \
$(_SYSGENOAKROOT)\lib\$(_CPUINDPATH)\ceddk.lib
SOURCELIBS=$(_SYSGENOAKROOT)\lib\$(_CPUINDPATH)\pcc_com.lib
DEFFILE=pcc_smdk2410.def
DLLENTRY=_DllEntryCRTStartup
INCLUDES=$(_PUBLICROOT)\common\oak\drivers\pccard\common;$(INCLUDES)
SOURCES= \
Init.cpp \
PDSocket.cpp \
PcmSock.cpp \
PcmWin.cpp
#xref VIGUID {549CAC8D_8AF0_4789_9ACF_2BB92 599470D}
#xref VSGUID {0601CE65_BF4D_453A_966B_E20250AD2E8E}
You can define the following directives in a Sources file:
■ TARGETNAME This is the name of the target file, without file name extension.
■ TARGETTYPE Defines the type of file to be built, as follows:
■ DYNLINK A dynamic-link library (.dll).
■ LIBRARY A static-link library (.lib).
■ PROGRAM An executable file (.exe).
■ NOTARGET Build no file.
■ RELEASETYPE Specifies the directory where Nmake.exe places the target file, as follows:
■ PLATFORM PLATFORM\<BSP Name>\<Target>.
■ OAK, SDK, DDK %_PROJECTROOT%\Oak\<Target>.
■ LOCAL The current directory.
■ CUSTOM A directory specified in TARGETPATH.
■ MANAGED %_PROJECTROOT%\Oak\<Target>\Managed.
■ TARGETPATH Defines the path for RELEASETYPE=CUSTOM.
■ SOURCELIBS Specifies libraries to be linked with the target file specified in TARGETNAME to create the final binary output. This option is typically used for creating a .lib file but not .dll or .exe files.
■ TARGETLIBS Specifies additional libraries and object files to link to the final binary output, typically used for creating .dll or .exe files but not for .lib files.
■ INCLUDES Lists additional directories to search for include files.
■ SOURCES Defines the source files to be used for this particular component.
■ ADEFINES Specifies parameters for the assembler.
■ CDEFINES Specifies parameters for the compiler, which can be used as additional DEFINE statements for use in IFDEF statements.
■ LDEFINES Sets linker definitions.
■ RDEFINES Specifies DEFINE statements for the resource compiler.
■ DLLENTRY Defines the entry point for a DLL.
■ DEFFILE Defines the .def file which contains a DLL's exported symbols.
■ EXEENTRY Sets the entry point of an executable file.
■ SKIPBUILD Marks the build of the target as successful without an actual build of the target.
■ WINCETARGETFILE0 Specifies nonstandard files that should be built before building the current directory.
■ WINCETARGETFILES This macro definition specifies nonstandard target files that Build.exe should build after Build.exe links all other targets in the current directory.
■ WINCE_OVERRIDE_CFLAGS Defines compiler flags to override default settings.
■ WINCECPU Specifies that the code requires a certain CPU type and should only be built for that particular CPU.
In addition to the standard directives, Windows Embedded CE Sources files support the directives PRELINK_PASS_CMD and POSTLINK_PASS_CMD. You can use these directives to perform custom actions based on command-line tools or batch files before and after the build process, such as PRELINK_PASS_CMD = pre_action.bat and POSTLINK_PASS_CMD = post_action.bat. This is useful, for example, if you want to copy additional files to the release directory when developing a custom application.
Makefile Files
If you look closer at the contents of a subproject folder, you can also find a file named Makefile to provide default preprocessing directives, commands, macros, and other expressions to Nmake.exe. However, in Windows Embedded CE, this Makefile includes only a single line that references %_MAKEENVROOT%\Makefile.def. By default, the environment variable %_MAKEENVROOT% points to the C:\Wince6OO\Public\Common\Oak\Misc folder and the Makefile.def file in this location is the standard Makefile for all CE components, so you should not modify this file. Among other things, the Makefile.def file contains include statements to pull in Sources file, such as !INCLUDE $(MAKEDIR)\sources, which specify the Sources file from the subproject folder. You should edit the Sources file in the subproject folder to adjust the way Nmake.exe builds the target file.
Lesson Summary
The Windows Embedded CE 6.0 R2 development environment relies on Makefile, Sources, and Dirs files to control how Build.exe and Nmake.exe compile and link source code into functional binary components for the run-time image. You can use Dirs files to define the source code directories included in the build process or Sources files to specify compile and build directives in greater detail. The Makefile, on the other hand, requires no customization. It merely references the default Makefile.def file with general preprocessing directives, commands, macros, and other processing instructions for the build system. You must thoroughly understand the purpose of files and how they control the build process if you want to clone public catalog items or create new components efficiently.
Lesson 3: Analyzing Build Results
You are certain to encounter build errors during the software-development cycle. In fact, it is not uncommon to use compile errors as a syntax check for source code, although IntelliSense® and other coding aids available in Visual Studio 2005 help to reduce the amount of typos and other syntax errors. Syntax errors are relatively uncomplicated to fix because you can double-click the corresponding error message in the Output window and jump right to the critical line in the source code file. However, compiler errors are only one type of build errors that can occur. Other common build errors are math errors, expression evaluation errors, linker errors, and errors related to run-time image configuration files. In addition to error messages, the build system also generates status messages and warnings to help you analyze and diagnose build issues. The amount of information generated during the build process can be overwhelming. You need to know the different types and general format of build messages if you want to identify, locate, and solve build errors efficiently.