Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document that MSBuild is now able to automatically consume root props files of MSBuildToolchain & MSBuildDeps #2885

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions reference/conanfile/tools/microsoft.rst
Original file line number Diff line number Diff line change
Expand Up @@ -289,16 +289,28 @@ Available since: `1.32.0 <https://github.com/conan-io/conan/releases/tag/1.32.0>

The ``MSBuild`` build helper is a wrapper around the command line invocation of MSBuild. It will abstract the
calls like ``msbuild "MyProject.sln" /p:Configuration=<conf> /p:Platform=<platform>`` into Python method calls.
This helper externally injects root props files eventually generated by ``MSBuildToolchain`` and ``MSBuildDeps``.
Therefore manual edition of Visual Studio solutions is not required when you use this helper.

The ``MSBuild`` helper can be used like:
This helper is intended to be used in the ``build()`` method, to call msbuild command automatically
when a package is being built directly by Conan (create, install):

.. code:: python
.. code-block:: python

from conan import ConanFile
from conan.tools.microsoft import MSBuild
from conan.tools.microsoft import MSBuild, MSBuildDeps, MSBuildToolchain

class App(ConanFile):
settings = "os", "arch", "compiler", "build_type"
requires = "hello/0.1"
options = {"shared": [True, False], "fPIC": [True, False]}
default_options = {"shared": False, "fPIC": True}

def generate(self):
tc = MSBuildToolchain(self)
tc.generate()
deps = MSBuildDeps(self)
deps.generate()

def build(self):
msbuild = MSBuild(self)
Expand All @@ -308,7 +320,7 @@ The ``MSBuild.build()`` method internally implements a call to ``msbuild`` like:

.. code:: bash

$ <vcvars-cmd> && msbuild "MyProject.sln" /p:Configuration=<configuration> /p:Platform=<platform> /target=mytarget
$ <vcvars-cmd> && msbuild "MyProject.sln" /p:Configuration=<configuration> /p:Platform=<platform> /p:PlatformToolset=<toolset> /p:ForceImportBeforeCppTargets="<props_files>" /target=mytarget

Where:

Expand All @@ -317,6 +329,11 @@ Where:
but this will be configurable with ``msbuild.build_type``.
- ``platform`` is the architecture, a mapping from the ``settings.arch`` to the common 'x86', 'x64', 'ARM', 'ARM64'.
This is configurable with ``msbuild.platform``.
- ``toolset`` (since `1.57.0 <https://github.com/conan-io/conan/releases/tag/1.57.0>`_) is the platform toolset.
It's ``settings.compiler.toolset`` if defined, otherwise a mapping from ``settings.compiler.version`` to default
values like 'v142' or 'v143' etc. This is configurable with ``msbuild.toolset``.
- ``props_files`` (since `1.57.0 <https://github.com/conan-io/conan/releases/tag/1.57.0>`_) is a semi colon separated
list of root props files eventually generated by ``MSBuildToolchain`` and ``MSBuildDeps``.
- ``targets`` (since `1.52.0 <https://github.com/conan-io/conan/releases/tag/1.52.0>`_) is an optional argument,
defaults to ``None``, and otherwise it is a list of targets to build

Expand All @@ -329,6 +346,8 @@ You can customize the following attributes in case you need to change them:
- **build_type** (default ``settings.build_type``): Value for the ``/p:Configuration``.
- **platform** (default based on ``settings.arch`` to select one of these values: (``'x86', 'x64', 'ARM', 'ARM64'``):
Value for the ``/p:Platform``.
- **toolset** (since `1.57.0 <https://github.com/conan-io/conan/releases/tag/1.57.0>`_) (default ``settings.compiler.toolset``
if defined, otherwise based on ``settings.compiler.version``): Value for the ``/p:PlaftormToolset``.

Example:

Expand All @@ -344,6 +363,7 @@ Example:
msbuild = MSBuild(self)
msbuild.build_type = "MyRelease"
msbuild.platform = "MyPlatform"
msbuild.toolset = "MyToolset"
msbuild.build("MyProject.sln")


Expand Down