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.

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 default settings.build_type one.

  • arch (Optional, Defaulted to None): Use a custom architecture name instead of the settings.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 to True 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 this output_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): When None it will generate a file named conan_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 the build() 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): If True, it adjusts the compiler flags according to the build_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.

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().