windows-nt/Source/XPSP1/NT/sdktools/build/build.htm

325 lines
17 KiB
HTML
Raw Normal View History

2020-09-26 03:20:57 -05:00
<HTML>
<BODY>
<A NAME=BASEDIR><H3>BASEDIR</H3></A>
The BASEDIR macro refers to the base of the source tree.
By default,
<PRE> BASEDIR=$(_NTDRIVE)$(_NTROOT)</PRE>
The following three statements are equivalent, but using the third one is recommended.
<PRE>
TARGETLIBS=d:\nt\public\sdk\lib\*\kernel32.lib
TARGETLIBS=$(BASEDIR)\public\sdk\lib\*\kernel32.lib
TARGETLIBS=$(<A HREF=#SDK_LIB_PATH>SDK_LIB_PATH</A>)\kernel32.lib
</PRE>
sources
dirs
makefile
makefile.inc
makefile.def
makefile.plt
build.dat
objects.mac
<A NAME=BUILD_DEFAULT_TARGETS><H3>BUILD_DEFAULT_TARGETS</H3></A>
This envirnoment variable specifies the platform for which you are building. This variables allows the possibly of cross platform compilation, when such compilers are available.
Here is an exmaple of this environment variable:
<PRE> BUILD_DEFAULT_TARGETS=-axp64</PRE>
<A NAME=BUILD_DEFAULT><H3>BUILD_DEFAULT</H3></A>
This envirnoment variable specifies the default options used by build.exe
Here is an example of this environment variable:
<PRE> BUILD_DEFAULT=-eswM -nmake -i</PRE>
<A NAME=BUILD_MAKE_PROGRAM><H3>BUILD_MAKE_PROGRAM</H3></A>
This envirnoment variable specifies the default program make executed by build.exe to in order to compile a directory.
The default value of this environment variable should be nmake.exe.
<A NAME=BUILD_OTPIONS><H3>BUILD_OPTIONS</H3></A>
By default, build.exe will traverse the entire source tree, processing the directories listed in the DIRS section of the dirs file.
This envirnoment variable specifies which of the optional directories, listed under </A HREF=#OPTIONAL_DIRS>OPTIONAL_DIRS</A> should be processed by build.exe
Here are some examples of this environment variable:
<PRE> BUILD_OPTIONS=OptDir1 OptDir2</PRE>
would cause build to also process all OptDir1 and OptDir2 directories listed under an OPTIONAL_DIRS section.
<PRE> BUILD_OPTIONS=~OptDir1 OptDir2</PRE>
would cause build to all OptDir2 directories listed under an OPTIONAL_DIRS section, but force it to skip over all OptDir1 directories, whether listed in the DIRS or OPTIONAL_DIRS section of a dirs file.
<A NAME=CRT_INC_PATH><H3>CRT_INC_PATH</H3></A>
<P>This envirnoment variable specifies the location of the C Runtime header files. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\sdk\inc\crt</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the C Runtime header files.<BR>
This macro should no be redefined from within a sources file.</P>
<A NAME=CRT_LIB_PATH><H3>CRT_LIB_PATH</H3></A>
<P>This envirnoment variable specifies the location of the C Runtime libraries. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\sdk\lib\crt</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the C runtime libraries.<BR>
This macro should no be redefined from within a sources file.</P>
<P>Here is an example of the usage of this macro:</P>
<PRE> TARGETLIB=$(CRT_LIB_PATH)\libcntpr.lib \<BR> $(SDK_LIB_PATH)\advapi32.lib</PRE>
<A NAME=DDK_INC_PATH><H3>DDK_INC_PATH</H3></A>
<P>This macro specifies the location of the DDK header files. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\ddk\inc</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the DDK header files.<BR>
This macro should no be redefined from within a sources file.</P>
<A NAME=DDK_LIB_DEST><H3>DDK_LIB_DEST</H3></A>
<P>This macro specifies the destination location of a DDK library. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\ddk\lib\*</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the DDK libraries.<BR>
This macro should no be redefined from within a sources file.</P>
<P>Here is an example of the usage of this macro:</P>
<PRE> TARGETPATHLIB=$(DDK_LIB_DEST)\ndis.lib</PRE>
<A NAME=DDK_LIB_PATH><H3>DDK_LIB_PATH</H3></A>
<P>This macro specifies the location of the DDK libraries. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\ddk\lib</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the DDK libraries.<BR>
This macro should no be redefined from within a sources file.</P>
<P>Here is an example of the usage of this macro:</P>
<PRE> TARGETLIB=$(DDK_LIB_PATH)\ndis.lib \<BR> $(DDK_LIB_PATH)\tdikrnl.lib</PRE>
<A NAME=DDK_LIB_PATH><H3>DDK_LIB_PATH</H3></A>
<P>This macro specifies the location of the DDK libraries. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\ddk\lib</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the DDK libraries.<BR>
This macro should no be redefined from within a sources file.</P>
<P>Here is an example of the usage of this macro:</P>
<PRE> TARGETLIB=$(DDK_LIB_PATH)\ndis.lib \<BR> $(DDK_LIB_PATH)\tdikrnl.lib</PRE>
<A NAME=MASTER_VERSION_FILE><H3>MASTER_VERSION_FILE</H3></A>
This macro contains the name of the master version file for Windows 2000.
It contains, among other things, the default operating system version number
which all binaries should have defined in the resource section.
The default value of this variable is $(<A HREF=#SDK_INC_PATH>SDK_INC_PATH</A>)\ntverp.h
You should not override this value in your environment variables unless your component is not integrated in the Windows 2000 product (please contact BryanT for more information).
<A NAME=OAK_INC_PATH><H3>OAK_INC_PATH</H3></A>
<P>This macro specifies the location of the OAK header files. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\oak\inc</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the OAK header files.<BR>
This macro should no be redefined from within a sources file.</P>
<A NAME=PRIVATE_INC_PATH><H3>PRIVATE_INC_PATH</H3></A>
<P>This macro specifies the location of the private windows 2000 header files. The default value of this macro is:</P>
<PRE> $(BASEDIR)\private\inc</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the private windows 2000 header files.<BR>
This macro should no be redefined from within a sources file.</P>
<A NAME=SDK_LIB_DEST><H3>SDK_LIB_DEST</H3></A>
<P>This macro specifies the destination location of a SDK library. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\sdk\lib\*</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the SDK libraries.<BR>
This macro should no be redefined from within a sources file.</P>
<P>Here is an example of the usage of this macro:</P>
<PRE> TARGETPATHLIB=$(SDK_LIB_DEST)\kernel32.lib</PRE>
<A NAME=SDK_LIB_PATH><H3>SDK_LIB_PATH</H3></A>
<P>This macro specifies the location of the SDK libraries. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\sdk\lib</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the SDK libraries.<BR>
This macro should no be redefined from within a sources file.</P>
<P>Here is an example of the usage of this macro:</P>
<PRE> TARGETLIB=$(SDK_LIB_PATH)\kernel32.lib \<BR> $(SDK_LIB_PATH)\advapi32.lib</PRE>
<A NAME=WDM_INC_PATH><H3>WDM_INC_PATH</H3></A>
<P>This macro specifies the location of the WDM header file. The default value of this macro is:</P>
<PRE> $(BASEDIR)\public\ddk\inc\wdm</PRE>
<P>Set this macro in your environment variables if you wish to override the default location of the WDM header files.<BR>
This macro should no be redefined from within a sources file.</P>
<A NAME=C_DEFINES><H3>C_DEFINES - <SMALL>optional</SMALL></H3></A>
Use this macro to specify switches you want passed to the compiler.
Typically, they are compiler #defines.
You might specify:
<PRE> C_DEFINES = -DENABLE_FEATURE1</PRE>
to define ENABLE_FEATURE1 to the compiler.
C_DEFINES gets passed to both the C compiler and the MIDL compiler.
Therefore, you cannot put compiler optimization or other machine or
tool specific switches in the C_DEFINES macro.
Use <A HREF=#MSC_OPTIMIZATION>MSC_OPTIMIZATION</A> for C compiler only optimizations
See also <A HREF=#ASM_DEFINES>ASM_DEFINES</A>, <A HREF=#RC_DEFINES>RC_DEFINES</A>
<A NAME=DLLORDER><H3>DLLORDER - <SMALL>optional</SMALL></H3></A>
When you are building a DLL, you can specify an order file that will be passed
to the linker. This order file lists the order in which functions should be
layed out in the image.
This is the same as <A HREF=#NTPROFILEINPUT>NTPROFILEINPUT</A> except that
a full name for the profile can be specified.
<A NAME=EXEPROFILEINPUT><H3>EXEPROFILEINPUT - <SMALL>obsolete</SMALL></H3></A>
Use <A HREF=#NTPROFILEINPUT>NTPROFILEINPUT</A> instead.
<A NAME=INCLUDES><H3>INCLUDES - <SMALL>optional</SMALL></H3></A>
<P>Build.exe use a default list of public include directories from which to search for header files.
The default list of include directories is dependent on the value of <A HREF=#TARGETTYPE>TARGETTYPE</A> in the sources file.</P>
<P>Use the INCLUDES macro to indicate an additional list of private include directories to be searched for include files during compilation.
Separate the entries in this list with a semicolon.
Path names can be absolute or relative.</P>
For example:
<PRE>
INCLUDES=..\inc;..\..\inc
INCLUDES=$(INCLUDES); \
h; \
..\headers;
</PRE>
The INCLUDES macro is read by build.exe and passed to the MAKE program.
The list of directories in the INCULDES macro will have precedence over the default include directories.
<A NAME=MAJORCOMP><H3>MAJORCOMP - <SMALL>obsolete</SMALL></H3></A>
Please remove from your sources file
<A NAME=MINORCOMP><H3>MINORCOMP - <SMALL>obsolete</SMALL></H3></A>
Please remove from your sources file
<A NAME=NO_NTDLL><H3>NO_NTDLL - <SMALL>optional</SMALL></H3></A>
Set this macro to 0 to force your binary <I>not</I> to link against NTDLL.LIB.
<A NAME=NTPROFILEINPUT><H3>NTPROFILEINPUT - <SMALL>optional</SMALL></H3></A>
When you are building a DLL, you can specify an order file that will be passed
to the linker. This order file lists the order in which functions should be
layed out in the image.
To use the profile, specify the following in your sources file:
<PRE> NTPROFILEINPUT=1</PRE>
If you set this value, build.exe expect to find
<PRE> $(TARGETNAME).prf</PRE>
in the current subdirectory.
<P> See also <A HREF=#DLLORDER>DLLORDER</A></P>
<A NAME=PNP_POWER><H3>PNP_POWER - <SMALL>obsolete</SMALL></H3></A>
Please remove from your sources file
<A NAME=SOURCES><H3>SOURCES - <SMALL>required</SMALL></H3></A>
<P>The SOURCES macro is the most important macro in a sources file.
It specifies the list of files to be compiled.
Build.exe will look at these files and generate a dependency list.
For any source file whose dependencies changed, build.exe will rebuild
this file.</P>
<P>Use this macro to list your source filenames (except for the file containing
main in the case where <A HREF=#UMAPPL>UMAPPL</A> or <A HREF=#UMTEST>UMTEST</A>
is used. Include the filename extension and separate the entries in this list
with spaces or tabs.</P>
<A NAME=TARGETEXT><H3>TARGETEXT - <SMALL>optional</SMALL></H3></A>
Set this macro to specify the extension name (such as .cpl) when you want your binary to have something other than the default extension generated by <A HREF=#TARGETTYPE>TARGETTYPE</A>.
If you specify something unexpected, you will see a message "Unexpected Target Ext." If you want an extension added to the Build Utility, contact Bryan Tuttle (bryant).
<A NAME=TARGETLIBS><H3>TARGETLIBS - <SMALL>required</SMALL></H3></A>
<P>Set this macro to specify the set of libraries with which your final image must be linked.</P>
If your components generates a library (.lib) and this library must link in code from other libraries, use the <A HREF=#LINKLIBS>LINKLIBS</A> macro.
Use LINKLIBS only for the case that meets the following conditions:
You are building a dynamic link.
You are exporting something that's defined in some other component library that you also build.
In your dirs file in the subdirectory above, you have ordered it so that the component libraries are around before you build the dynamic link.
There is a similar macro called UMLIBSUMLIBS that you can use if you are building UMAPPLs.
<A NAME=TARGETNAME><H3>TARGETNAME - <SMALL>required</SMALL></H3></A>
Use this macro to specify the name of the binary being built, excluding the filename extension.
You must have this macro in your sources file.
<A NAME=TARGETPATH><H3>TARGETPATH - <SMALL>required</SMALL></H3></A>
Use this macro to specify the target directory in which the resulting binary will be placed.
Notice that object files always end up in the obj subdirectory. Object file can only be generated in the <A HREF=#$(O)>$(O)</A> directory.
You must have this macro in your sources file. For example:
<PRE> TARGETPATH=obj</PRE>
See Also <A HREF=#TARGETPATHLIB>TARGETPATHLIB</A>
<A NAME=TARGETPATHLIB><H3>TARGETPATHLIB - <SMALL>optional</SMALL></H3></A>
Set this value to specify where to put the import library associated with this binary. <BR>
When you are building a DLL, you create the DLL itself and you create an import library that other images can use to reference functions exported by your DLL. <BR>
<PRE> TARGETPATHLIB=$(SDK_LIB_PATH)mydll.lib</PRE>
<P>Setting <A HREF=#TARGETPATH>TARGETPATH</A> independently from TARGETPATHLIB allows the binary to be kept in the
current directory, while the .lib and .exp files can be shared with other components. </P>
<A NAME=TARGETTYPE><H3>TARGETTYPE - <SMALL>required</SMALL></H3></A>
Use this macro to specify the type of binary being built. This is typically LIBRARY or
DYNLINK (for DLLs), but can take other values. This is a required field in the sources file.
TARGETTYPE allows build.exe to select appropriate defaults for include paths and link options.
You must have this macro in your sources file.
The valid values for TARGETYPE include:
<TABLE CELLPADDING=3 BORDER=3>
<TR VALIGN=TOP><TH> TARGETTYPE values </TH><TH> File Extension </TH><TH> Description </TH>
<TR VALIGN=TOP><TD><A NAME=PROGLIB>PROGLIB</A> </TD><TD> .exe </TD><TD> Executable program which also exports functions for other programs. </TD></TR>
<TR VALIGN=TOP><TD><A NAME=PROGRAM>PROGRAM</A> </TD><TD> .exe </TD><TD> Simple user mode program. </TD></TR>
<TR VALIGN=TOP><TD><A NAME=DYNLINK>DYNLINK</A> </TD><TD> .dll </TD><TD> Dynamic Link Library (dll). </TD></TR>
<TR VALIGN=TOP><TD><A NAME=LIBRARY>LIBRARY</A> </TD><TD> .lib </TD><TD> Component library whose code will be linked into another binary (such as a dll). </TD></TR>
<TR VALIGN=TOP><TD><A NAME=DRIVER_LIBRARY>DRIVER_LIBRARY</A> </TD><TD> .lib </TD><TD> Component library for a driver. The only difference with the LIBRARY type is that the default header file include path is different. </TD></TR>
<TR VALIGN=TOP><TD><A NAME=DRIVER>DRIVER</A> </TD><TD> .sys </TD><TD> Kernel mode driver.
<TR VALIGN=TOP><TD><A NAME=EXPORT_DRIVER>EXPORT_DRIVER</A> </TD><TD> .sys </TD><TD> Kernel mode driver which also exports routines other drivers can link against and call. </TD></TR>
<TR VALIGN=TOP><TD><A NAME=HAL>HAL</A> </TD><TD> .dll </TD><TD> Hardware Abstraction Layer (HAL) </TD></TR>
<TR VALIGN=TOP><TD><A NAME=BOOTPGM>BOOTPGM</A> </TD><TD> .exe </TD><TD> Kernel mode driver. </TD></TR>
<TR VALIGN=TOP><TD><A NAME=MINIPORT>MINIPORT</A> </TD><TD> .sys </TD><TD> Kernel mode driver which does not link against ntoskrnl.lib or hal.lib. </TD></TR>
<TR VALIGN=TOP><TD><A NAME=GDI_DRIVER>GDI_DRIVER</A> </TD><TD> .dll </TD><TD> Kernel mode driver which only links against win32k.sys (Display or print driver). </TD></TR>
</TABLE>
<A NAME=UMAPPL><H3>UMAPPL</H3></A>
<A NAME=UMAPPLEXT><H3>UMAPPLEXT</H3></A>
Use this macro to specify the extension name (for example .COM or .SCR) that
will be appended to the name specified in <A HREF=#UMAPPL>UMAPPL</A>.
Use UMAPPLEXT when you want the extension to be something other than .exe.
Contact Bryan Tuttle if you need to add a new type of extension.
<A NAME=UMLIBS><H3>UMLIBS</H3></A>
<A NAME=UMTEST><H3>UMTEST</H3></A>
<H2>Sample Driver Sources File</H2>
<PRE>
<A HREF=#TARGETNAME>TARGETNAME</A>=sample
<A HREF=#TARGETPATH>TARGETPATH</A>=obj
<A HREF=#TARGETTYPE>TARGETTYPE</A>=<A HREF=#DRIVER>DRIVER</A>
<A HREF=#TARGETLIBS>TARGETLIBS</A>=$(<A HREF=#DDK_LIB_PATH>DDK_LIB_PATH</A>)\videoprt.lib
<A HREF=#SOURCES>SOURCES</A>=file1.c \<BR> file2.c \<BR> file3.c
</PRE>
</BODY></HTML>