diff options
Diffstat (limited to 'src/engine/SCons/Tool/msvc.xml')
| -rw-r--r-- | src/engine/SCons/Tool/msvc.xml | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/src/engine/SCons/Tool/msvc.xml b/src/engine/SCons/Tool/msvc.xml new file mode 100644 index 0000000..c744903 --- /dev/null +++ b/src/engine/SCons/Tool/msvc.xml @@ -0,0 +1,316 @@ +<!-- +Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation + +This file is processed by the bin/SConsDoc.py module. +See its __doc__ string for a discussion of the format. +--> +<tool name="msvc"> +<summary> +Sets construction variables for the Microsoft Visual C/C++ compiler. +</summary> +<sets> +CCPDBFLAGS +CCPCHFLAGS +<!--CCCOMFLAGS--> +CC +CCFLAGS +CFLAGS +CCCOM +SHCC +SHCCFLAGS +SHCFLAGS +SHCCCOM +CXX +CXXFLAGS +CXXCOM +SHCXX +SHCXXFLAGS +SHCXXCOM +CPPDEFPREFIX +CPPDEFSUFFIX +INCPREFIX +INCSUFFIX +<!--STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME--> +RC +RCFLAGS +RCCOM +BUILDERS +OBJPREFIX +OBJSUFFIX +SHOBJPREFIX +SHOBJSUFFIX +CFILESUFFIX +CXXFILESUFFIX +PCHPDBFLAGS +PCHCOM +</sets> +<uses> +CCCOMSTR +SHCCCOMSTR +CXXCOMSTR +SHCXXCOMSTR +PCH +PCHSTOP +PDB +</uses> +</tool> + +<builder name="PCH"> +<summary> +Builds a Microsoft Visual C++ precompiled header. +Calling this builder method +returns a list of two targets: the PCH as the first element, and the object +file as the second element. Normally the object file is ignored. +This builder method is only +provided when Microsoft Visual C++ is being used as the compiler. +The PCH builder method is generally used in +conjuction with the PCH construction variable to force object files to use +the precompiled header: + +<example> +env['PCH'] = env.PCH('StdAfx.cpp')[0] +</example> +</summary> +</builder> + +<builder name="RES"> +<summary> +Builds a Microsoft Visual C++ resource file. +This builder method is only provided +when Microsoft Visual C++ or MinGW is being used as the compiler. The +<filename>.res</filename> +(or +<filename>.o</filename> +for MinGW) suffix is added to the target name if no other suffix is given. +The source +file is scanned for implicit dependencies as though it were a C file. +Example: + +<example> +env.RES('resource.rc') +</example> +</summary> +</builder> + +<cvar name="CCPCHFLAGS"> +<summary> +Options added to the compiler command line +to support building with precompiled headers. +The default value expands expands to the appropriate +Microsoft Visual C++ command-line options +when the &cv-link-PCH; construction variable is set. +</summary> +</cvar> + +<cvar name="CCPDBFLAGS"> +<summary> +Options added to the compiler command line +to support storing debugging information in a +Microsoft Visual C++ PDB file. +The default value expands expands to appropriate +Microsoft Visual C++ command-line options +when the &cv-link-PDB; construction variable is set. + +The Visual C++ compiler option that SCons uses by default +to generate PDB information is <option>/Z7</option>. +This works correctly with parallel (<option>-j</option>) builds +because it embeds the debug information in the intermediate object files, +as opposed to sharing a single PDB file between multiple object files. +This is also the only way to get debug information +embedded into a static library. +Using the <option>/Zi</option> instead may yield improved +link-time performance, +although parallel builds will no longer work. + +You can generate PDB files with the <option>/Zi</option> +switch by overriding the default &cv-link-CCPDBFLAGS; variable as follows: + +<example> +env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}'] +</example> + +An alternative would be to use the <option>/Zi</option> +to put the debugging information in a separate <filename>.pdb</filename> +file for each object file by overriding +the &cv-link-CCPDBFLAGS; variable as follows: + +<example> +env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb' +</example> +</summary> +</cvar> + +<cvar name="MSVC_BATCH"> +<summary> +When set to any true value, +specifies that &SCons; should batch +compilation of object files +when calling the Microsoft Visual C/C++ compiler. +All compilations of source files from the same source directory +that generate target files in a same output directory +and were configured in &SCons; using the same construction environment +will be built in a single call to the compiler. +Only source files that have changed since their +object files were built will be passed to each compiler invocation +(via the &cv-link-CHANGED_SOURCES; construction variable). +Any compilations where the object (target) file base name +(minus the <filename>.obj</filename>) +does not match the source file base name +will be compiled separately. +</summary> +</cvar> + +<cvar name="PCH"> +<summary> +The Microsoft Visual C++ precompiled header that will be used when compiling +object files. This variable is ignored by tools other than Microsoft Visual C++. +When this variable is +defined SCons will add options to the compiler command line to +cause it to use the precompiled header, and will also set up the +dependencies for the PCH file. +Example: + +<example> +env['PCH'] = 'StdAfx.pch' +</example> +</summary> +</cvar> + +<cvar name="PCHCOM"> +<summary> +The command line used by the +&b-PCH; +builder to generated a precompiled header. +</summary> +</cvar> + +<cvar name="PCHCOMSTR"> +<summary> +The string displayed when generating a precompiled header. +If this is not set, then &cv-link-PCHCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="PCHPDBFLAGS"> +<summary> +A construction variable that, when expanded, +adds the <literal>/yD</literal> flag to the command line +only if the &cv-PDB; construction variable is set. +</summary> +</cvar> + +<cvar name="PCHSTOP"> +<summary> +This variable specifies how much of a source file is precompiled. This +variable is ignored by tools other than Microsoft Visual C++, or when +the PCH variable is not being used. When this variable is define it +must be a string that is the name of the header that +is included at the end of the precompiled portion of the source files, or +the empty string if the "#pragma hrdstop" construct is being used: + +<example> +env['PCHSTOP'] = 'StdAfx.h' +</example> +</summary> +</cvar> + +<cvar name="RC"> +<summary> +The resource compiler used to build +a Microsoft Visual C++ resource file. +</summary> +</cvar> + +<cvar name="RCCOM"> +<summary> +The command line used to build +a Microsoft Visual C++ resource file. +</summary> +</cvar> + +<cvar name="RCCOMSTR"> +<summary> +The string displayed when invoking the resource compiler +to build a Microsoft Visual C++ resource file. +If this is not set, then &cv-link-RCCOM; (the command line) is displayed. +</summary> +</cvar> + +<cvar name="RCFLAGS"> +<summary> +The flags passed to the resource compiler by the RES builder. +</summary> +</cvar> + +<cvar name="RCINCFLAGS"> +<summary> +An automatically-generated construction variable +containing the command-line options +for specifying directories to be searched +by the resource compiler. +The value of &cv-RCINCFLAGS; is created +by appending &cv-RCINCPREFIX; and &cv-RCINCSUFFIX; +to the beginning and end +of each directory in &cv-CPPPATH;. +</summary> +</cvar> + +<cvar name="RCINCPREFIX"> +<summary> +The prefix (flag) used to specify an include directory +on the resource compiler command line. +This will be appended to the beginning of each directory +in the &cv-CPPPATH; construction variable +when the &cv-RCINCFLAGS; variable is expanded. +</summary> +</cvar> + +<cvar name="RCINCSUFFIX"> +<summary> +The suffix used to specify an include directory +on the resource compiler command line. +This will be appended to the end of each directory +in the &cv-CPPPATH; construction variable +when the &cv-RCINCFLAGS; variable is expanded. +</summary> +</cvar> + +<cvar name="MSVC_VERSION"> +<summary> +Sets the preferred version of Microsoft Visual C/C++ to use. + +If &cv-MSVC_VERSION; is not set, +&SCons; will (by default) select the latest version +of Visual C/C++ installed on your system. +If the specified version isn't installed, +tool initialization will fail. +</summary> +</cvar> + +<cvar name="HOST_ARCH"> +<summary> +Sets the host architecture for Visual Studio compiler. If not set, +default to the detected host architecture: note that this may depend +on the python you are using. + +Valid values are the same as for &cv-TARGET_ARCH;. + +This is currently only used on Windows, but in the future it will be +used on other OSes as well. +</summary> +</cvar> +<cvar name="TARGET_ARCH"> +<summary> +Sets the target architecture for Visual Studio compiler (i.e. the arch +of the binaries generated by the compiler). If not set, default to +&cv-HOST_ARCH;. +This is currently only used on Windows, but in the future it will be +used on other OSes as well. + +Valid values for Windows are 'x86', 'i386' (for 32 bits); +'amd64', 'emt64', 'x86_64' (64 bits); +and 'ia64' (Itanium). +For example, if you want to compile 64-bit binaries, you would set +TARGET_ARCH='x86_64' in your SCons environment. +</summary> +</cvar> |