{"id":26497,"date":"2020-09-14T16:30:22","date_gmt":"2020-09-14T16:30:22","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=26497"},"modified":"2020-09-15T17:55:38","modified_gmt":"2020-09-15T17:55:38","slug":"standard-c20-modules-support-with-msvc-in-visual-studio-2019-version-16-8","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/standard-c20-modules-support-with-msvc-in-visual-studio-2019-version-16-8\/","title":{"rendered":"Standard C++20 Modules support with MSVC in Visual Studio 2019 version 16.8"},"content":{"rendered":"<p><em>Please see our <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/a-multitude-of-updates-in-visual-studio-2019-version-16-8-preview-3\/\">Visual Studio 2019 version 16.8 Preview 3 release notes<\/a> for more of our latest features.<\/em><\/p>\n<p>It has been some time since our <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/c-modules-conformance-improvements-with-msvc-in-visual-studio-2019-16-5\/\">last update<\/a> regarding C++ Modules conformance. The toolset, project system, and IDE teams have been hard at work to create a first class C++ Modules experience in Visual Studio 2019. There is a lot to share, so let&#8217;s get right into it:<\/p>\n<h2>What&#8217;s new?<\/h2>\n<ul>\n<li><a href=\"#std-latest\"><code>\/std:c++latest<\/code> Implies C++ Modules.<\/a><\/li>\n<li><a href=\"#private-module-fragments\">Private Module fragments<\/a> are a new form of API encapsulation for primary Module interfaces.<\/li>\n<li><a href=\"#include-translation\">Include translation<\/a> allows for easy adoption of header units without changing existing code.<\/li>\n<li><a href=\"#module-linkage\">Module linkage<\/a> is a new type of linkage enforced by the back-end and linker.<\/li>\n<li><a href=\"#project-system\">Project system<\/a> changes to enable C++ Module scenarios.<\/li>\n<li><a href=\"#intellisense\">IntelliSense<\/a> updates.<\/li>\n<\/ul>\n<h4><span id=\"std-latest\"><code>\/std:c++latest<\/code> Implies C++ Modules<\/span><\/h4>\n<p>Since MSVC began down the path of implementing the Modules TS the toolset has always required the use of <code>\/experimental:module<\/code> on any compilation. Since the merge of Modules into the C++20 standard (we can <a href=\"https:\/\/herbsutter.com\/2020\/09\/06\/c20-approved-c23-meetings-and-schedule-update\/\">officially<\/a> say C++20 now!) the compiler has been working towards C++20 Modules conformance until precisely such a time that we can confidently roll Modules into <code>\/std:c++latest<\/code>. That time is now!<\/p>\n<p>There are a few caveats to implying C++ Modules under <code>\/std:c++latest<\/code>:<\/p>\n<ul>\n<li><code>\/std:c++latest<\/code> now implies <code>\/permissive-<\/code>. This means that customers currently relying on the permissive behavior of the compiler in combination with <code>\/std:c++latest<\/code> are required to now apply <code>\/permissive<\/code> on the command line. <b>Note:<\/b> enabling <code>\/permissive<\/code> also disables the use of Modules.<\/li>\n<li>Now that Modules are rolled into the latest language mode <em>some<\/em> code is subject to breakage due to <code>module<\/code> and <code>import<\/code> being converted into keywords. We have <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/cpp\/import-export-module?view=vs-2019#remarks\">documented some of the common scenarios<\/a>. The paper MSVC implements in order to convert <code>module<\/code> and <code>import<\/code> into keywords has even more scenarios: <a href=\"http:\/\/www.open-std.org\/jtc1\/sc22\/wg21\/docs\/papers\/2019\/p1857r1.html\">P1857R1<\/a>.<\/li>\n<li>The <code>std.*<\/code> Modules which ship with Visual Studio will not be available through <code>\/std:c++latest<\/code> alone. The standard library Modules have not yet been standardized and as such remain experimental. To continue using the standard library Modules users will need <code>\/experimental:module<\/code> as part of their command line options.<\/li>\n<\/ul>\n<h4><span id=\"private-module-fragments\">Private Module Fragments<\/span><\/h4>\n<p>C++20 added a new section to a primary Module interface known as the private Module fragment, <a href=\"http:\/\/eel.is\/c%2B%2Bdraft\/module.private.frag\">[module.private.frag]<\/a>. Private Module fragments allow authors to truly hide details of a library without having to create a separate C++ source file to contain implementation details. Imagine a scenario where a PIMPL pattern is used in a primary Module interface:<\/p>\n<pre class=\"\">module;\r\n#include &lt;memory&gt;\r\nexport module m;\r\nstruct Impl;\r\n\r\nexport\r\nclass S {\r\npublic:\r\n  S();\r\n  ~S();\r\n  void do_stuff();\r\n  Impl* get() const { return impl.get(); }\r\nprivate:\r\n  std::unique_ptr&lt;Impl&gt; impl;\r\n};\r\n\r\nmodule :private; \/\/ Everything beyond this point is not available to importers of 'm'.\r\n\r\nstruct Impl {\r\n  void do_stuff() { }\r\n};\r\n\r\nS::S():\r\n  impl{ std::make_unique&lt;Impl&gt;() }\r\n{\r\n}\r\n\r\nS::~S() { }\r\n\r\nvoid S::do_stuff() {\r\n  impl-&gt;do_stuff();\r\n}<\/pre>\n<p>And on the import side:<\/p>\n<pre class=\"\">import m;\r\n\r\nint main() {\r\n    S s;\r\n    s.do_stuff();         \/\/ OK.\r\n    s.get();              \/\/ OK: pointer to incomplete type.\r\n    auto impl = *s.get(); \/\/ ill-formed: use of undefined type 'Impl'.\r\n}<\/pre>\n<p>The private Module partition is an abstraction barrier shielding the consumer of the containing Module from anything defined in the purview of the private partition, effectively enabling single-&#8220;header&#8221; libraries with better hygiene, improved encapsulation, and reduced build system administrivia.<\/p>\n<h4><span id=\"include-translation\">Include Translation<\/span><\/h4>\n<p>With the introduction of <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/c-modules-conformance-improvements-with-msvc-in-visual-studio-2019-16-5\/#header-units\">header units<\/a> comes header include translation, <a href=\"http:\/\/eel.is\/c%2B%2Bdraft\/cpp.include#7\">[cpp.include]\/7<\/a> enables the compiler to translate <code>#include<\/code> directives into <code>import<\/code> directives provided the header-name designates an importable header (to MSVC, a header unit is made an importable header through the use of <code>\/headerUnit<\/code>). This switch can be enabled through <b>C\/C++ -&gt; All Options -&gt; Additional Options<\/b> and adding <code>\/translateInclude<\/code>. In future releases, users will have the choice of selecting specific headers that should be subject to include translation, instead of an all-or-nothing switch.<\/p>\n<h4><span id=\"module-linkage\">Module Linkage<\/span><\/h4>\n<p>C++ Modules demands more from the toolset beyond simply parsing (front-end). C++20 introduces a new flavor of linkage, &#8220;module linkage&#8221; <a href=\"http:\/\/eel.is\/c++draft\/basic.link#2.2\">[basic.link]\/2.2<\/a>. A proof-of-concept, using only front-end name mangling, implementation of Module linkage developed during the Modules Technical Specification (TS) era has proven to be imperfect, and inefficient at scale. Starting with Visual Studio 2019 16.8, the compiler and linker work together in order to enforce module linkage semantics (without the front-end name mangling workaround). The new linker work means that users can more freely author code using named Modules without being concerned with possible name collision issues while gaining stronger odr guarantees not offered by any other language facility.<\/p>\n<h5>Strong Ownership<\/h5>\n<p>The MSVC toolset has also adopted a <em>strong ownership<\/em> model for the purposes of program linkage. The strong ownership model brings certainty and avoids clashes of linkage names by empowering the linker to attach exported entities to their owning Modules. This capability allows MSVC to rule out undefined behavior stemming from linking different Modules (maybe revisions of the same Module) reporting similar declarations of different entities in the same program.<\/p>\n<p>For instance, consider the following example that is formally left undefined behavior (in practical terms):<\/p>\n<p><code>m.ixx<\/code><\/p>\n<pre class=\"\">export module m;\r\nexport\r\nint munge(int a, int b) {\r\n    return a + b;\r\n}<\/pre>\n<p><code>n.ixx<\/code><\/p>\n<pre class=\"\">export module n;\r\nexport\r\nint munge(int a, int b) {\r\n    return a - b;\r\n}<\/pre>\n<p><code>libM.cpp<\/code> Also a header file which forward declares <code>libm_munge<\/code><\/p>\n<pre class=\"\">import m;\r\n\r\nint libm_munge(int a, int b) {\r\n    return munge(a, b);\r\n}<\/pre>\n<p><code>main.cpp<\/code><\/p>\n<pre class=\"\">#include \"libM.h\"\r\nimport n; \/\/ Note: do not import 'm'.\r\nint main() {\r\n    if (munge(1, 2) != -1)\r\n        return 1;\r\n    if (libm_munge(1, 2) != 3) \/\/ Note uses Module 'm' version of 'munge'.\r\n        return 1;\r\n}<\/pre>\n<p>In practice and in general, one wouldn&#8217;t write code purposefully like that, but it is hard to avoid in practice under code migration, evolution, and maintenance. Before strong module ownership semantics, a program such as this would not be possible (with two external linkage names of <code>munge<\/code>). Strong ownership buys this new odr guarantee. There is a great paper <a href=\"http:\/\/www.open-std.org\/jtc1\/sc22\/wg21\/docs\/papers\/2016\/p0142r0.pdf\">&#8220;A Module System for C++&#8221;<\/a> which details rationale behind strong ownership.<\/p>\n<h4><span id=\"project-system\">Project System<\/span><\/h4>\n<p>Quite possibly the most essential part of using C++ Modules is having a build system which can cope with the requirements of C++ Modules build while providing an experience for users without a steep learning curve. The VC Project System team has been working closely with the compiler toolset team to bring an experience with automatic Modules and header units support minimizing user work to set them up.<\/p>\n<p>The files with .ixx or .cppm extensions are considered &#8220;Module interface&#8221; source. But ultimately it is controlled by <b>CompileAs<\/b> property:\n<img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2020\/09\/property1.jpg\" \/><\/p>\n<p>If you want to build a header unit for a .h file, you need to change its item type to be &#8220;C\/C++ compiler&#8221; as by default .h files are in &#8220;C\/C++ header&#8221; group and are not passed to the compiler. &#8220;C\/C++ compiler&#8221; files with .h extension are considered &#8220;header units&#8221; by default.\n<img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2020\/09\/property2.jpg\" \/><\/p>\n<p>The project build will automatically scan the Modules and Header Unit files (according to their Compile As setting), for other Module and Header Units dependencies in the same project, and build them in the correct dependency order.<\/p>\n<p>To reference a Module or a header unit produced by another project, just add a reference to that project. All &#8220;public&#8221; Modules and header units from referenced projects are automatically available for referencing in code.<\/p>\n<p>A project can control which Modules and headers (including the ones built as header units) are considered &#8220;public&#8221; by modifying the following properties:\n<img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2020\/09\/property3.jpg\" \/><\/p>\n<p>This short video gives a brief look of the workflow. The only manual work done was setting the C++ language standard to <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/reference\/std-specify-language-standard-version?view=vs-2019#to-set-this-compiler-option-in-the-visual-studio-development-environment\"><code>\/std:c++latest<\/code><\/a>.\n<img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2020\/09\/VSGif.gif\" \/><\/p>\n<h4><span id=\"compiler-switch-overhaul\">Compiler Switch Overhaul<\/span><\/h4>\n<p>The experimental phase of many <code>\/module:*<\/code> prefixed switches is over so we have moved them into a permanent home under a new name:<\/p>\n<table>\n<tbody>\n<tr>\n<th>Old<\/th>\n<th>New<\/th>\n<\/tr>\n<tr>\n<td><code>\/module:interface<\/code><\/td>\n<td><code>\/interface<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:internalPartition<\/code><\/td>\n<td><code>\/internalPartition<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:reference<\/code><\/td>\n<td><code>\/reference<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:search<\/code><\/td>\n<td><code>\/ifcSearchDir<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:stdIfcDir<\/code><\/td>\n<td><code>\/stdIfcDir<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:output<\/code><\/td>\n<td><code>\/ifcOutput<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:ifcOnly<\/code><\/td>\n<td><code>\/ifcOnly<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:exportHeader<\/code><\/td>\n<td><code>\/exportHeader<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:showResolvedHeader<\/code><\/td>\n<td><code>\/showResolvedHeader<\/code><\/td>\n<\/tr>\n<tr>\n<td><code>\/module:validateChecksum[-]<\/code><\/td>\n<td><code>\/validateIfcChecksum[-]<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>Build systems and users wishing to use the 16.8 toolset should take note of the new changes.<\/p>\n<h4><span id=\"intellisense\">IntelliSense<\/span><\/h4>\n<p>Visual C++ would not be&#8230; visual without IntelliSense. In 16.8 we&#8217;re adding full support for using IntelliSense in modules, both for writing Module interfaces (.ixx) and getting IntelliSense from imported Modules and header units. IntelliSense support for imported Modules will not be available in Preview 3 but we plan to enable it in an upcoming Preview. Please stay tuned for our CppCon demo which will feature IntelliSense usage!<\/p>\n<p>The toolset team has worked hard to ensure that the C++ Module format emitted by the compiler is well-documented and stable for use in the IntelliSense engine. It is MSVC which is responsible for building the IFC file which is then used by the IDE. The ability for other tools to consume the MSVC IFC format is crucial to a healthy ecosystem, and the IntelliSense engine using the IFC output is the first step in that direction.<\/p>\n<h4>Closing<\/h4>\n<p>We urge you to go out and try using Visual Studio 2019 with Modules. 16.8 Preview 3 will be available through the <a href=\"https:\/\/visualstudio.microsoft.com\/downloads\/\">Visual Studio 2019 downloads<\/a> page!<\/p>\n<p>As always, we welcome your feedback. Feel free to send any comments through e-mail at <a href=\"mailto:visualcpp@microsoft.com\">visualcpp@microsoft.com<\/a> or through <a href=\"https:\/\/twitter.com\/visualc\">Twitter @visualc<\/a>. Also, feel free to follow me on Twitter <a href=\"https:\/\/twitter.com\/starfreakclone\">@starfreakclone<\/a>.<\/p>\n<p>If you encounter other problems with MSVC in VS 2019 please let us know via the <a href=\"https:\/\/docs.microsoft.com\/en-us\/visualstudio\/ide\/how-to-report-a-problem-with-visual-studio?view=vs-2019\">Report a Problem<\/a> option, either from the installer or the Visual Studio IDE itself. For suggestions or bug reports, let us know through <a href=\"https:\/\/developercommunity.visualstudio.com\/\">DevComm.<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Please see our Visual Studio 2019 version 16.8 Preview 3 release notes for more of our latest features. It has been some time since our last update regarding C++ Modules conformance. The toolset, project system, and IDE teams have been hard at work to create a first class C++ Modules experience in Visual Studio 2019. [&hellip;]<\/p>\n","protected":false},"author":39620,"featured_media":35994,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[270,1],"tags":[8,3882,140,100,2064,14,246],"class_list":["post-26497","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-announcement","category-cplusplus","tag-announcement","tag-buildsystem","tag-c","tag-c-language","tag-c20","tag-intellisense","tag-modules"],"acf":[],"blog_post_summary":"<p>Please see our Visual Studio 2019 version 16.8 Preview 3 release notes for more of our latest features. It has been some time since our last update regarding C++ Modules conformance. The toolset, project system, and IDE teams have been hard at work to create a first class C++ Modules experience in Visual Studio 2019. [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/26497","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/39620"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=26497"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/26497\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/35994"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=26497"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=26497"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=26497"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}