Standard C++20 Modules support with MSVC in Visual Studio 2019 version 16.8

Cameron DaCamara

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. There is a lot to share, so let’s get right into it:

What’s new?

• /std:c++latest Implies C++ Modules.
• Private Module fragments are a new form of API encapsulation for primary Module interfaces.
• Include translation allows for easy adoption of header units without changing existing code.
• Module linkage is a new type of linkage enforced by the back-end and linker.
• Project system changes to enable C++ Module scenarios.
• IntelliSense updates.

/std:c++latest Implies C++ Modules

Since MSVC began down the path of implementing the Modules TS the toolset has always required the use of /experimental:module on any compilation. Since the merge of Modules into the C++20 standard (we can officially 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 /std:c++latest. That time is now!

There are a few caveats to implying C++ Modules under /std:c++latest:

• /std:c++latest now implies /permissive-. This means that customers currently relying on the permissive behavior of the compiler in combination with /std:c++latest are required to now apply /permissive on the command line. Note: enabling /permissive also disables the use of Modules.
• Now that Modules are rolled into the latest language mode some code is subject to breakage due to module and import being converted into keywords. We have documented some of the common scenarios. The paper MSVC implements in order to convert module and import into keywords has even more scenarios: P1857R1.
• The std.* Modules which ship with Visual Studio will not be available through /std:c++latest 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 /experimental:module as part of their command line options.

Private Module Fragments

C++20 added a new section to a primary Module interface known as the private Module fragment, [module.private.frag]. 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:

module;
#include <memory>
export module m;
struct Impl;

export
class S {
public:
  S();
  ~S();
  void do_stuff();
  Impl* get() const { return impl.get(); }
private:
  std::unique_ptr<Impl> impl;
};

module :private; // Everything beyond this point is not available to importers of 'm'.

struct Impl {
  void do_stuff() { }
};

S::S():
  impl{ std::make_unique<Impl>() }
{
}

S::~S() { }

void S::do_stuff() {
  impl->do_stuff();
}

And on the import side:

import m;

int main() {
    S s;
    s.do_stuff();         // OK.
    s.get();              // OK: pointer to incomplete type.
    auto impl = *s.get(); // ill-formed: use of undefined type 'Impl'.
}

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-“header” libraries with better hygiene, improved encapsulation, and reduced build system administrivia.

Include Translation

With the introduction of header units comes header include translation, [cpp.include]/7 enables the compiler to translate #include directives into import directives provided the header-name designates an importable header (to MSVC, a header unit is made an importable header through the use of /headerUnit). This switch can be enabled through C/C++ -> All Options -> Additional Options and adding /translateInclude. 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.

Module Linkage

C++ Modules demands more from the toolset beyond simply parsing (front-end). C++20 introduces a new flavor of linkage, “module linkage” [basic.link]/2.2. 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.

Strong Ownership

The MSVC toolset has also adopted a strong ownership 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.

For instance, consider the following example that is formally left undefined behavior (in practical terms):

m.ixx

export module m;
export
int munge(int a, int b) {
    return a + b;
}

n.ixx

export module n;
export
int munge(int a, int b) {
    return a - b;
}

libM.cpp Also a header file which forward declares libm_munge

import m;

int libm_munge(int a, int b) {
    return munge(a, b);
}

main.cpp

#include "libM.h"
import n; // Note: do not import 'm'.
int main() {
    if (munge(1, 2) != -1)
        return 1;
    if (libm_munge(1, 2) != 3) // Note uses Module 'm' version of 'munge'.
        return 1;
}

In practice and in general, one wouldn’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 munge). Strong ownership buys this new odr guarantee. There is a great paper “A Module System for C++” which details rationale behind strong ownership.

Project System

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.

The files with .ixx or .cppm extensions are considered “Module interface” source. But ultimately it is controlled by CompileAs property:

If you want to build a header unit for a .h file, you need to change its item type to be “C/C++ compiler” as by default .h files are in “C/C++ header” group and are not passed to the compiler. “C/C++ compiler” files with .h extension are considered “header units” by default.

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.

To reference a Module or a header unit produced by another project, just add a reference to that project. All “public” Modules and header units from referenced projects are automatically available for referencing in code.

A project can control which Modules and headers (including the ones built as header units) are considered “public” by modifying the following properties:

This short video gives a brief look of the workflow. The only manual work done was setting the C++ language standard to /std:c++latest.

Compiler Switch Overhaul

The experimental phase of many /module:* prefixed switches is over so we have moved them into a permanent home under a new name:

Build systems and users wishing to use the 16.8 toolset should take note of the new changes.

IntelliSense

Visual C++ would not be… visual without IntelliSense. In 16.8 we’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!

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.

Closing

We urge you to go out and try using Visual Studio 2019 with Modules. 16.8 Preview 3 will be available through the Visual Studio 2019 downloads page!

As always, we welcome your feedback. Feel free to send any comments through e-mail at visualcpp@microsoft.com or through Twitter @visualc. Also, feel free to follow me on Twitter @starfreakclone.

If you encounter other problems with MSVC in VS 2019 please let us know via the Report a Problem option, either from the installer or the Visual Studio IDE itself. For suggestions or bug reports, let us know through DevComm.

Cameron DaCamara Senior Software Engineer, Visual C++

Follow