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
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")
Also, to inject the flags corresponding to the compiler.runtime
, build_type
and cppstd
settings, the build helper
generates a properties file (in the build folder) that is passed to msbuild
with /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)
Builds Visual Studio project with the given parameters.
- Parameters:
project_file (Required): Path to the .sln file.
targets (Optional, Defaulted to
None
): List of targets to build.upgrade_project (Optional, Defaulted to
True
): Will call devenv to upgrade the solution to your current Visual Studio.build_type (Optional, Defaulted to
None
): Use a custom build type name instead of the defaultsettings.build_type
one.arch (Optional, Defaulted to
None
): Use a custom architecture name instead of thesettings.arch
one. It will be used to build the/p:Configuration=
parameter of MSBuild. It can be used as the key of the platforms parameter. E.g.arch="x86", platforms={"x86": "i386"}
force_vcvars (Optional, Defaulted to
False
): Will ignore if the environment is already set for a different Visual Studio version.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)
toolset (Optional, Defaulted to
None
): Specify a toolset. Will append a/p:PlatformToolset
option.platforms (Optional, Defaulted to
None
): Dictionary with the mapping of archs/platforms from 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”). This dictionary will update the default one:msvc_arch = {'x86': 'x86', 'x86_64': 'x64', 'armv7': 'ARM', 'armv8': 'ARM64'}
use_env (Optional, Defaulted to
True
: Applies the argument/p:UseEnv=true
to the MSBuild call.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
): 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
): WhenNone
it will generate a file namedconan_build.props
. You can specify a different name for the generated properties file.
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)
- 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.cppflags
.
link_flags
List with linker flags from requirements’ cpp_info.sharedlinkflags
and cpp_info.exelinkflags
std
If the setting cppstd
is set, the property will contain the corresponding flag of the language
standard.
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().