MSBuild
Calls Visual Studio MSBuild command to build a .sln project:
from conans import ConanFile, MSBuild
class ExampleConan(ConanFile):
...
def build(self):
msbuild = MSBuild(self)
msbuild.build("MyProject.sln")
Internally the MSBuild
build helper uses VisualStudioBuildEnvironment to adjust the LIB
and CL
environment variables with all the
information from the requirements: include directories, library names, flags etc. and then calls MSBuild.
VisualStudioBuildEnvironment to adjust the
LIB
andCL
environment variables with all the information from the requirements: include directories, library names, flags etc.tools.msvc_build_command() [DEPRECATED] to call :command:
MSBuild
.
You can adjust all the information from the requirements accessing to the build_env
that it is a VisualStudioBuildEnvironment object:
from conans import ConanFile, MSBuild
class ExampleConan(ConanFile):
...
def build(self):
msbuild = MSBuild(self)
msbuild.build_env.include_paths.append("mycustom/directory/to/headers")
msbuild.build_env.lib_paths.append("mycustom/directory/to/libs")
msbuild.build_env.link_flags = []
msbuild.build("MyProject.sln")
To inject the flags corresponding to the compiler.runtime
, build_type
and
compiler.cppstd
settings, this build helper also generates a
properties file (in the build folder) that is passed to :command:MSBuild
with
:command:/p:ForceImportBeforeCppTargets="conan_build.props"
.
Constructor
class MSBuild(object):
def __init__(self, conanfile)
- Parameters:
conanfile (Required): ConanFile object. Usually
self
in a conanfile.py.
Attributes
build_env
A VisualStudioBuildEnvironment object with the needed environment variables.
Methods
build()
def build(self, project_file, targets=None, upgrade_project=True, build_type=None, arch=None,
parallel=True, force_vcvars=False, toolset=None, platforms=None, use_env=True,
vcvars_ver=None, winsdk_version=None, properties=None, output_binary_log=None,
property_file_name=None, verbosity=None, definitions=None,
user_property_file_name=None)
Builds Visual Studio project with the given parameters.
- Parameters:
project_file (Required): Path to the .sln file.
targets (Optional, Defaulted to
None
): Sets/target
flag to the specified list of targets to build.upgrade_project (Optional, Defaulted to
True
): Will call devenv /upgrade to upgrade the solution to your current Visual Studio.build_type (Optional, Defaulted to
None
): Sets/p:Configuration
flag to the specified value. It will override the value fromsettings.build_type
.arch (Optional, Defaulted to
None
): Sets/p:Platform
flag to the specified value. It will override the value fromsettings.arch
. This value (or thesettings.arch
one if not overridden) will be used as the key for themsvc_arch
dictionary that returns the final string used for the/p:Platform
flag (see platforms argument documentation below).parallel (Optional, Defaulted to
True
): Will use the configured number of cores in the conan.conf file or tools.cpu_count():In the solution: Building the solution with the projects in parallel. (
/m:
parameter).CL compiler: Building the sources in parallel. (
/MP:
compiler flag).
force_vcvars (Optional, Defaulted to
False
): Will ignore if the environment is already set for a different Visual Studio version.toolset (Optional, Defaulted to
None
): Sets/p:PlatformToolset
to the specified toolset. WhenNone
it will apply the settingcompiler.toolset
if specified. WhenFalse
it will skip adjusting the/p:PlatformToolset
.platforms (Optional, Defaulted to
None
): This dictionary will update the default one (seemsvc_arch
below) and will be used to get the mapping of architectures to platforms from the Conan naming to another one. It is useful for Visual Studio solutions that have a different naming in architectures. Example:platforms={"x86":"Win32"}
(Visual solution uses “Win32” instead of “x86”).msvc_arch = {'x86': 'x86', 'x86_64': 'x64', 'armv7': 'ARM', 'armv8': 'ARM64'}
use_env (Optional, Defaulted to
True
: Sets/p:UseEnv=true
flag. Note that this setting does not guarantee that environment variables from Conan will not be used by the compiler or linker. This is an MSBuild setting which simply specifies the behavior when environment variables conflict with equivalent properties from the project (via .vcxproj, .props or .targets files). Conan will still apply the relevant compiler and linker environment variables when spawning the MSBuild process. For example, ifuse_env=False
is specified and if there is noAdditionalDependencies
variable defined in the project, theLINK
environment variable passed by Conan will still be used by the linker because it technically doesn’t conflict with the project variable.vcvars_ver (Optional, Defaulted to
None
): Specifies the Visual Studio compiler toolset to use.winsdk_version (Optional, Defaulted to
None
): Specifies the version of the Windows SDK to use.properties (Optional, Defaulted to
None
): Dictionary with new properties, for each element in the dictionary{name: value}
it will append a/p:name="value"
option.output_binary_log (Optional, Defaulted to
None
): Sets/bl
flag. If set toTrue
then MSBuild will output a binary log file called msbuild.binlog in the working directory. It can also be used to set the name of log file like thisoutput_binary_log="my_log.binlog"
. This parameter is only supported starting from MSBuild version 15.3 and onwards.property_file_name (Optional, Defaulted to
None
): Setsp:ForceImportBeforeCppTargets
. WhenNone
it will generate a file named conan_build.props. You can specify a different name for the generated properties file.verbosity (Optional, Defaulted to
None
): Sets the/verbosity
flag to the specified verbosity level. Possible values are"quiet"
,"minimal"
,"normal"
,"detailed"
and"diagnostic"
.definitions (Optional, Defaulted to
None
): Dictionary with additional compiler definitions to be applied during the build. Use a dictionary with the desired key and its value set toNone
to set a compiler definition with no value.user_property_file_name (Optional, Defaulted to
None
): Filename or list of filenames of user properties files to be automatically passed to the build command. These files have priority over the conan_build.props file (user can override that file values), and if a list of file names is provided, later file names also have priority over the former ones. These filenames will be passed, together with conan_build.props files as/p:ForceImportBeforeCppTargets
argument.
Note
The MSBuild()
build helper will, before calling to MSBuild, call tools.vcvars_command() to adjust the environment
according to the settings. When cross-building from x64 to x86 the toolchain by default is x86
. If you want to use amd64_x86
instead, set the environment variable PreferredToolArchitecture=x64
.
get_command()
Returns a string command calling MSBuild.
def get_command(self, project_file, props_file_path=None, targets=None, upgrade_project=True,
build_type=None, arch=None, parallel=True, toolset=None, platforms=None,
use_env=False, properties=None, output_binary_log=None, verbosity=None,
user_property_file_name=None)
- Parameters:
props_file_path (Optional, Defaulted to
None
): Path to a property file to be included in the compilation command. This parameter is automatically set by thebuild()
method to set the runtime from settings.Same parameters as the
build()
method.
get_version()
Static method that returns the version of MSBuild for the specified settings.
def get_version(settings)
Result is returned in a conans.model.Version
object as it is evaluated by the command line. It will raise an exception if it cannot
resolve it to a valid result.
- Parameters:
settings (Required): Conanfile settings. Use
self.settings
.
VisualStudioBuildEnvironment
Prepares the needed environment variables to invoke the Visual Studio compiler. Use it together with tools.vcvars_command().
from conans import ConanFile, VisualStudioBuildEnvironment
class ExampleConan(ConanFile):
...
def build(self):
if self.settings.compiler == "Visual Studio":
env_build = VisualStudioBuildEnvironment(self)
with tools.environment_append(env_build.vars):
vcvars = tools.vcvars_command(self.settings)
self.run('%s && cl /c /EHsc hello.cpp' % vcvars)
self.run('%s && lib hello.obj -OUT:hello.lib' % vcvars
You can adjust the automatically filled attributes:
def build(self):
if self.settings.compiler == "Visual Studio":
env_build = VisualStudioBuildEnvironment(self)
env_build.include_paths.append("mycustom/directory/to/headers")
env_build.lib_paths.append("mycustom/directory/to/libs")
env_build.link_flags = []
with tools.environment_append(env_build.vars):
vcvars = tools.vcvars_command(self.settings)
self.run('%s && cl /c /EHsc hello.cpp' % vcvars)
self.run('%s && lib hello.obj -OUT:hello.lib' % vcvars
Constructor
class VisualStudioBuildEnvironment(object):
def __init__(self, conanfile, with_build_type_flags=True)
- Parameters:
conanfile (Required): ConanFile object. Usually
self
in a conanfile.py.with_build_type_flags (Optional, Defaulted to
True
): IfTrue
, it adjusts the compiler flags according to thebuild_type
setting. e.g: -Zi, -Ob0, -Od…
Environment variables
NAME |
DESCRIPTION |
---|---|
LIB |
Library paths separated with “;” |
CL |
“/I” flags with include directories, Runtime (/MT, /MD…), Definitions (/DXXX), and any other C and CXX flags. |
Attributes
include_paths
List with directories of include paths.
lib_paths
List with directories of libraries.
defines
List with definitions from requirements’ cpp_info.defines
.
runtime
List with directories from settings.compiler.runtime
.
flags
List with flags from requirements’ cpp_info.cflags
.
cxx_flags
List with cxx flags from requirements’ cpp_info.cxxflags
.
link_flags
List with linker flags from requirements’ cpp_info.sharedlinkflags
and cpp_info.exelinkflags
std
This property contains the flag corresponding to the C++ standard. If you are still using
the deprecated setting cppstd
(see How to manage C++ standard) and you are not providing
any value for this setting, the property will be None
.
parallel
Defaulted to False
.
Sets the flag /MP
in order to compile the sources in parallel using cores found by tools.cpu_count().
See also
Read more about tools.environment_append().