%scons; %builders-mod; %functions-mod; %tools-mod; %variables-mod; ]>

Sets &consvars; for Microsoft Visual Studio.

MSVSPROJECTCOM MSVSSOLUTIONCOM MSVSSCONSCRIPT MSVSSCONS MSVSSCONSFLAGS MSVSSCONSCOM MSVSBUILDCOM MSVSREBUILDCOM MSVSCLEANCOM MSVSENCODING

Build a &MSVC; project file and solution file. Builds a &MSVC; project file based on the version of Visual Studio (or to be more precise, of MSBuild) that is configured: either the latest installed version, or the version specified by &cv-link-MSVC_VERSION; in the current &consenv;. For Visual Studio 6.0 a .dsp file is generated. For Visual Studio versions 2002-2008, a .vcproj file is generated. For Visual Studio 2010 and later a .vcxproj file is generated. Note there are multiple versioning schemes involved in the Microsoft compilation environment - see the description of &cv-link-MSVC_VERSION; for equivalences. Note &SCons; does not know how to construct project files for other languages (e.g. .csproj for C#, .vbproj for Visual Basic or .pyproject for Python). For the .vcxproj file, the underlying format is the MSBuild XML Schema, and the details conform to: https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure. The generated solution file enables Visual Studio to understand the project structure, and allows building it using MSBuild to call back to &SCons;. The project file encodes a toolset version that has been selected by &SCons; as described above. Since recent Visual Studio versions support multiple concurrent toolsets, use &cv-link-MSVC_VERSION; to select the desired one if it does not match the &SCons; default. The project file also includes entries which describe how to call &SCons; to build the project from within Visual Studio (or from an MSBuild command line). In some situations &SCons; may generate this incorrectly - notably when using the scons-local distribution, which is not installed in a way that that matches the default invocation line. If so, the &cv-link-SCONS_HOME; &consvar; can be used to describe the right way to locate the &SCons; code so that it can be imported. By default, a matching solution file for the project is also generated. This behavior may be disabled by specifying auto_build_solution=0 to the &b-MSVSProject; builder. The solution file can also be independently generated by calling the &b-MSVSSolution; builder, such as in the case where a solution should describe multiple projects. See the &b-link-MSVSSolution; description for further information. The &b-MSVSProject; builder accepts several keyword arguments describing lists of filenames to be placed into the project file. Currently, srcs, incs, localincs, resources, and misc are recognized. The names are intended to be self-explanatory, but note that the filenames need to be specified as strings, not as &SCons; File Nodes (for example if you generate files for inclusion by using the &f-link-Glob; function, the results should be converted to a list of strings before passing them to &b-MSVSProject;). This is because Visual Studio and MSBuild know nothing about &SCons; Node types. Each of the filename lists are individually optional, but at least one list must be specified for the resulting project file to be non-empty. In addition to the above lists of values, the following values may be specified as keyword arguments: target The name of the target .dsp or .vcproj file. The correct suffix for the version of Visual Studio must be used, but the &cv-link-MSVSPROJECTSUFFIX; &consvar; will be defined to the correct value (see example below). variant The name of this particular variant. Except for Visual Studio 6 projects, this can also be a list of variant names. These are typically things like "Debug" or "Release", but really can be anything you want. For Visual Studio 7 projects, they may also specify a target platform separated from the variant name by a | (vertical pipe) character: Debug|Xbox. The default target platform is Win32. Multiple calls to &b-MSVSProject; with different variants are allowed; all variants will be added to the project file with their appropriate build targets and sources. cmdargs Additional command line arguments for the different variants. The number of cmdargs entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. cppdefines Preprocessor definitions for the different variants. The number of cppdefines entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, &SCons; will use the invoking environment's &cv-link-CPPDEFINES; entry for all variants. cppflags Compiler flags for the different variants. If a /std:c++ flag is found then /Zc:__cplusplus is appended to the flags if not already found, this ensures that Intellisense uses the /std:c++ switch. The number of cppflags entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, SCons will combine the invoking environment's &cv-link-CCFLAGS;, &cv-link-CXXFLAGS;, &cv-link-CPPFLAGS; entries for all variants. cpppaths Compiler include paths for the different variants. The number of cpppaths entries must match the number of variant entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, SCons will use the invoking environment's &cv-link-CPPPATH; entry for all variants. buildtarget An optional string, node, or list of strings or nodes (one per build variant), to tell the Visual Studio debugger what output target to use in what build variant. The number of buildtarget entries must match the number of variant entries. runfile The name of the file that Visual Studio 7 and later will run and debug. This appears as the value of the Output field in the resulting &MSVC; project file. If this is not specified, the default is the same as the specified buildtarget value. &SCons; and Microsoft Visual Studio understand projects in different ways, and the mapping is sometimes imperfect: Because &SCons; always executes its build commands from the directory in which the &SConstruct; file is located, if you generate a project file in a different directory than the directory of the &SConstruct; file, users will not be able to double-click on the file name in compilation error messages displayed in the Visual Studio console output window. This can be remedied by adding the &MSVC; /FC compiler option to the &cv-link-CCFLAGS; variable so that the compiler will print the full path name of any files that cause compilation errors. If the project file is only used to teach the Visual Studio project browser about the file layout there should be no issues, However, Visual Studio should not be used to make changes to the project structure, build options, etc. as these will (a) not feed back to the &SCons; description of the project and (b) be lost if &SCons; regenerates the project file. The SConscript files should remain the definitive description of the build. If the project file is used to drive MSBuild (such as selecting "build" from the Visual Studio interface) you lose the direct control of target selection and command-line options you would have if launching the build directly from &SCons;, because these will be hard-coded in the project file to the values specified in the &b-MSVSProject; call. You can regain some of this control by defining multiple variants, using multiple &b-MSVSProject; calls to arrange different build targets, arguments, defines, flags and paths for different variants. If the build is divided into a solution with multiple MSBuild projects the mapping is further strained. In this case, it is important not to set Visual Studio to do parallel builds, as it will then launch the separate project builds in parallel, and &SCons; does not work well if called that way. Instead, you can set up the &SCons; build for parallel building - see the &f-link-SetOption; function for how to do this with num_jobs. Example usage: barsrcs = ['bar.cpp'] barincs = ['bar.h'] barlocalincs = ['StdAfx.h'] barresources = ['bar.rc', 'resource.h'] barmisc = ['bar_readme.txt'] dll = env.SharedLibrary(target='bar.dll', source=barsrcs) buildtarget = [s for s in dll if str(s).endswith('dll')] env.MSVSProject( target='Bar' + env['MSVSPROJECTSUFFIX'], srcs=barsrcs, incs=barincs, localincs=barlocalincs, resources=barresources, misc=barmisc, buildtarget=buildtarget, variant='Release', ) DebugSettings A dictionary of debug settings that get written to the .vcproj.user or the .vcxproj.user file, depending on the version installed. As for cmdargs, you can specify a DebugSettings dictionary per variant. If you give only one, it will be propagated to all variants. Changed in version 2.4: Added the optional DebugSettings parameter. Currently, only Visual Studio v9.0 and Visual Studio version v11 are implemented, for other versions no file is generated. To generate the user file, you just need to add a DebugSettings dictionary to the environment with the right parameters for your MSVS version. If the dictionary is empty, or does not contain any good value, no file will be generated. Following is a more contrived example, involving the setup of a project for variants and DebugSettings: # Assuming you store your defaults in a file vars = Variables('variables.py') msvcver = vars.args.get('vc', '9') # Check command args to force one Microsoft Visual Studio version if msvcver == '9' or msvcver == '11': env = Environment(MSVC_VERSION=msvcver + '.0', MSVC_BATCH=False) else: env = Environment() AddOption( '--userfile', action='store_true', dest='userfile', default=False, help="Create Visual C++ project file", ) # # 1. Configure your Debug Setting dictionary with options you want in the list # of allowed options, for instance if you want to create a user file to launch # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9): # V9DebugSettings = { 'Command': 'c:\\myapp\\using\\thisdll.exe', 'WorkingDirectory': 'c:\\myapp\\using\\', 'CommandArguments': '-p password', # 'Attach':'false', # 'DebuggerType':'3', # 'Remote':'1', # 'RemoteMachine': None, # 'RemoteCommand': None, # 'HttpUrl': None, # 'PDBPath': None, # 'SQLDebugging': None, # 'Environment': '', # 'EnvironmentMerge':'true', # 'DebuggerFlavor': None, # 'MPIRunCommand': None, # 'MPIRunArguments': None, # 'MPIRunWorkingDirectory': None, # 'ApplicationCommand': None, # 'ApplicationArguments': None, # 'ShimCommand': None, # 'MPIAcceptMode': None, # 'MPIAcceptFilter': None, } # # 2. Because there are a lot of different options depending on the Microsoft # Visual Studio version, if you use more than one version you have to # define a dictionary per version, for instance if you want to create a user # file to launch a specific application for testing your dll with Microsoft # Visual Studio 2012 (v11): # V10DebugSettings = { 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe', 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\', 'LocalDebuggerCommandArguments': '-p password', # 'LocalDebuggerEnvironment': None, # 'DebuggerFlavor': 'WindowsLocalDebugger', # 'LocalDebuggerAttach': None, # 'LocalDebuggerDebuggerType': None, # 'LocalDebuggerMergeEnvironment': None, # 'LocalDebuggerSQLDebugging': None, # 'RemoteDebuggerCommand': None, # 'RemoteDebuggerCommandArguments': None, # 'RemoteDebuggerWorkingDirectory': None, # 'RemoteDebuggerServerName': None, # 'RemoteDebuggerConnection': None, # 'RemoteDebuggerDebuggerType': None, # 'RemoteDebuggerAttach': None, # 'RemoteDebuggerSQLDebugging': None, # 'DeploymentDirectory': None, # 'AdditionalFiles': None, # 'RemoteDebuggerDeployDebugCppRuntime': None, # 'WebBrowserDebuggerHttpUrl': None, # 'WebBrowserDebuggerDebuggerType': None, # 'WebServiceDebuggerHttpUrl': None, # 'WebServiceDebuggerDebuggerType': None, # 'WebServiceDebuggerSQLDebugging': None, } # # 3. Select the dictionary you want depending on the version of Visual Studio # Files you want to generate. # if not env.GetOption('userfile'): dbgSettings = None elif env.get('MSVC_VERSION', None) == '9.0': dbgSettings = V9DebugSettings elif env.get('MSVC_VERSION', None) == '11.0': dbgSettings = V10DebugSettings else: dbgSettings = None # # 4. Add the dictionary to the DebugSettings keyword. # barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp'] barincs = ['targetver.h'] barlocalincs = ['StdAfx.h'] barresources = ['bar.rc', 'resource.h'] barmisc = ['ReadMe.txt'] dll = env.SharedLibrary(target='bar.dll', source=barsrcs) env.MSVSProject( target='Bar' + env['MSVSPROJECTSUFFIX'], srcs=barsrcs, incs=barincs, localincs=barlocalincs, resources=barresources, misc=barmisc, buildtarget=[dll[0]] * 2, variant=('Debug|Win32', 'Release|Win32'), cmdargs=f'vc={msvcver}', DebugSettings=(dbgSettings, {}), )

Build a Microsoft Visual Studio Solution file. Builds a Visual Studio solution file based on the version of Visual Studio that is configured: either the latest installed version, or the version specified by &cv-link-MSVC_VERSION; in the &consenv;. For Visual Studio 6, a .dsw file is generated. For Visual Studio .NET 2002 and later, it will generate a .sln file. Note there are multiple versioning schemes involved in the Microsoft compilation environment - see the description of &cv-link-MSVC_VERSION; for equivalences. The solution file is a container for one or more projects, and follows the format described at https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file. The following values must be specified: target The name of the target .dsw or .sln file. The correct suffix for the version of Visual Studio must be used, but the value &cv-link-MSVSSOLUTIONSUFFIX; will be defined to the correct value (see example below). variant The name of this particular variant, or a list of variant names (the latter is only supported for MSVS 7 solutions). These are typically things like "Debug" or "Release", but really can be anything you want. For MSVS 7 they may also specify target platform, like this "Debug|Xbox". Default platform is Win32. projects A list of project file names, or Project nodes returned by calls to the &b-link-MSVSProject; Builder, to be placed into the solution file. Note that these filenames need to be specified as strings, NOT as &SCons; File Nodes. This is because the solution file will be interpreted by MSBuild and by Visual Studio, which know nothing about &SCons; Node types. In addition to the mandatory arguments above, the following optional values may be specified as keyword arguments: auto_filter_projects Under certain circumstances, solution file names or solution file nodes may be present in the projects argument list. When solution file names or nodes are present in the projects argument list, the generated solution file may contain erroneous Project records resulting in VS IDE error messages when opening the generated solution file. By default, an exception is raised when a solution file name or solution file node is detected in the projects argument list. The accepted values for auto_filter_projects are: None An exception is raised when a solution file name or solution file node is detected in the projects argument list. None is the default value. True or evaluates True Automatically remove solution file names and solution file nodes from the projects argument list. False or evaluates False Leave the solution file names and solution file nodes in the projects argument list. An exception is not raised. When opening the generated solution file with the VS IDE, the VS IDE will likely report that there are erroneous Project records that are not supported or that need to be modified. Example Usage: env.MSVSSolution( target="Bar" + env["MSVSSOLUTIONSUFFIX"], projects=["bar" + env["MSVSPROJECTSUFFIX"]], variant="Release", )

When the Microsoft Visual Studio tools are initialized, they set up this dictionary with the following keys: VERSION the version of MSVS being used (can be set via &cv-link-MSVC_VERSION;) VERSIONS the available versions of MSVS installed VCINSTALLDIR installed directory of &MSVC; VSINSTALLDIR installed directory of Visual Studio FRAMEWORKDIR installed directory of the .NET framework FRAMEWORKVERSIONS list of installed versions of the .NET framework, sorted latest to oldest. FRAMEWORKVERSION latest installed version of the .NET framework FRAMEWORKSDKDIR installed location of the .NET SDK. PLATFORMSDKDIR installed location of the Platform SDK. PLATFORMSDK_MODULES dictionary of installed Platform SDK modules, where the dictionary keys are keywords for the various modules, and the values are 2-tuples where the first is the release date, and the second is the version number. If a value is not set, it was not available in the registry. Visual Studio 2017 and later do not use the registry for primary storage of this information, so typically for these versions only PROJECTSUFFIX and SOLUTIONSUFFIX will be set.

Sets the architecture for which the generated project(s) should build. The default value is x86. amd64 is also supported by &SCons; for most Visual Studio versions. Since Visual Studio 2015 arm is supported, and since Visual Studio 2017 arm64 is supported. Trying to set &cv-MSVS_ARCH; to an architecture that's not supported for a given Visual Studio version will generate an error.

The string placed in a generated &MSVC; project file as the value of the ProjectGUID attribute. There is no default value. If not defined, a new GUID is generated.

The path name placed in a generated &MSVC; project file as the value of the SccAuxPath attribute if the MSVS_SCC_PROVIDER &consvar; is also set. There is no default value.

The root path of projects in your SCC workspace, i.e the path under which all project and solution files will be generated. It is used as a reference path from which the relative paths of the generated &MSVC; project and solution files are computed. The relative project file path is placed as the value of the SccLocalPath attribute of the project file and as the values of the SccProjectFilePathRelativizedFromConnection[i] (where [i] ranges from 0 to the number of projects in the solution) attributes of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. Similarly, the relative solution file path is placed as the values of the SccLocalPath[i] (where [i] ranges from 0 to the number of projects in the solution) attributes of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. This is used only if the MSVS_SCC_PROVIDER &consvar; is also set. The default value is the current working directory.

The project name placed in a generated &MSVC; project file as the value of the SccProjectName attribute if the MSVS_SCC_PROVIDER &consvar; is also set. In this case the string is also placed in the SccProjectName0 attribute of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. There is no default value.

The string placed in a generated &MSVC; project file as the value of the SccProvider attribute. The string is also placed in the SccProvider0 attribute of the GlobalSection(SourceCodeControl) section of the Microsoft Visual Studio solution file. There is no default value.

Set the preferred version of Microsoft Visual Studio to use. If &cv-MSVS_VERSION; is not set, &SCons; will (by default) select the latest version of Visual Studio installed on your system. So, if you have version 6 and version 7 (MSVS .NET) installed, it will prefer version 7. You can override this by specifying the &cv-link-MSVS_VERSION; variable when initializing the Environment, setting it to the appropriate version ('6.0' or '7.0', for example). If the specified version isn't installed, tool initialization will fail. Deprecated since 1.3.0: &cv-MSVS_VERSION; is deprecated in favor of &cv-link-MSVC_VERSION;. As a transitional aid, if &cv-MSVS_VERSION; is set and &cv-MSVC_VERSION; is not, &cv-MSVC_VERSION; will be initialized to the value of &cv-MSVS_VERSION;. An error is raised if both are set and have different values.

The build command line placed in a generated &MSVC; project file. The default is to have Visual Studio invoke &SCons; with any specified build targets.

The clean command line placed in a generated &MSVC; project file. The default is to have Visual Studio invoke &SCons; with the -c option to remove any specified targets.

The encoding string placed in a generated &MSVC; project file. The default is encoding Windows-1252.

The action used to generate &MSVC; project files.

The suffix used for &MSVC; project (DSP) files. The default value is .vcxproj when using Visual Studio 2010 and later, .vcproj when using Visual Studio versions between 2002 and 2008, and .dsp when using Visual Studio 6.0.

The rebuild command line placed in a generated &MSVC; project file. The default is to have Visual Studio invoke &SCons; with any specified rebuild targets.

The &SCons; used in generated &MSVC; project files. The default is the version of &SCons; being used to generate the project file.

The &SCons; flags used in generated &MSVC; project files.

The default &SCons; command used in generated &MSVC; project files.

The sconscript file (that is, &SConstruct; or &SConscript; file) that will be invoked by &MSVC; project files (through the &cv-link-MSVSSCONSCOM; variable). The default is the same sconscript file that contains the call to &b-link-MSVSProject; to build the project file.

The action used to generate Microsoft Visual Studio solution files.

The suffix used for Microsoft Visual Studio solution (DSW) files. The default value is .sln when using Visual Studio version 7.x (.NET 2002) and later, and .dsw when using Visual Studio 6.0.

The (optional) path to the &SCons; library directory, initialized from the external environment. If set, this is used to construct a shorter and more efficient search path in the &cv-link-MSVSSCONS; command line executed from C++ project files.