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++latestImplies 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++latestnow implies/permissive-. This means that customers currently relying on the permissive behavior of the compiler in combination with/std:c++latestare required to now apply/permissiveon the command line. Note: enabling/permissivealso disables the use of Modules.- Now that Modules are rolled into the latest language mode some code is subject to breakage due to
moduleandimportbeing converted into keywords. We have documented some of the common scenarios. The paper MSVC implements in order to convertmoduleandimportinto keywords has even more scenarios: P1857R1. - The
std.*Modules which ship with Visual Studio will not be available through/std:c++latestalone. 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:moduleas 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:
| Old | New |
|---|---|
/module:interface |
/interface |
/module:internalPartition |
/internalPartition |
/module:reference |
/reference |
/module:search |
/ifcSearchDir |
/module:stdIfcDir |
/stdIfcDir |
/module:output |
/ifcOutput |
/module:ifcOnly |
/ifcOnly |
/module:exportHeader |
/exportHeader |
/module:showResolvedHeader |
/showResolvedHeader |
/module:validateChecksum[-] |
/validateIfcChecksum[-] |
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.
Thank you for your efforts! You talked about the build system in this article, and said it can scan the sources for module dependences. Is there a command-line parameter to generate dep files?
Headers and modules cannot be mixed ? I have a header file X.h and it cannot be converted to import. The same needs to be included in the .ixx file as well as in .cpp.And now that’s a linker error. Headerguard does not help
Can you confirm that in VS2019 16.8.0 Preview 5, the IDE parser is not able to parse code with imported modules ? I've spent like 3 hours trying to specify all kind of additional options at file-level, as you suggested, but in the end, while the project builds fine through the compiler/linker, the IDE is confused with code imported from modules. I either get no semantic color highlighting, or errors. Your video is stopping too...
Great! But have few questions:
1. is there a template available for visual studio?
2. why .ixx/.cppm and not .m...? it looks cleaner and simpler, is it allowed to use .m even?
3. when can we expect stl to be usable as module?
4. is it possible to have a main in a module?
Thanks
EDIT:
i tried, works but one big annoyance
<code>
import ; shows in red, and there is no code completion for that import..
and yeah, renamed...
Hello, a question about including 3rd party headers for “old” C++ with headers, for example nlohmann json.
If i include such header before module declaration it will result in internal compiler crash. Will it be fixed somehow or this must be fixed on library side by making module version of it ? 🙂
Are there known issues/remaining work with precompiled headers interacting with modules? Given a main.cpp that is "Not Using Precompiled Headers" and includes precomp.h, and precomp.h has "import MyModule;", it builds fine; but if I set main.cpp "Precompiled header" to "/Use (Yu)" (and corresponding precomp.cpp), I get error C2230: could not find module 'MyModule' from inside that same precomp.h. I totally get if there's an ordering dependency issue here with the build system (because precompiled headers...
Hi,
The strategy of converting project to module aware depends on implementation defined but very important feature, IMHO. Let's consider the following case - we change the implementation in module definition file but keep the interface untouched and we don't want to recompile the other files that import it. That allows us to drop source/header hell. Have you any plans to implement the feature?
See short discussion on stackoverflow .
Thanks.
Maybe more of a general question, but what about exporting a function which is defined in an internal partition? The standard doesn't seem to have too much to say about that, except that it allows it in implementation units. If I do it in a partition, the compiler will generate a slightly different symbol for it (so linkage will fail). I'm not sure if this is effectively prohibited or if it's something that will change...
If the definition in the internal partition has no reachable exported declaration, then that definition is effectively a declaration that has module linkage -- so, that is a programmer error.
Regarding your second question, an internal partition is never seen by consumers of the module, so it is not clear what you mean by "expose an internal datatype". If you just want to export the name of the class without its definition, then: (1) export...
I'm not sure I understand the reachability of an exported declaration - let's say I have an <code> in primary module interface and then in an internal partition I define it. This doesn't seem to work now - it will not link, even if I `import mod;` (no other way to import the primary?) in the partition. So that export declaration is not reachable - I suppose? Strangely, if I make the export declaration in...
Great improvment thanks!
I’ve noticed that linker warning:
LINK : warning LNK4301: ignoring ‘/INCREMENTAL’ because of the use of cxx modules
Is it something temporary or is there an issue by design and we’ll never get incremental link with c++ modules ?
Hi Onduril,
Yes, this linker warning is a known issue and one that is fixed with Preview 4. Stay tuned and thank you for trying out the new feature!
I noticed how modules now implies and requires /permissive-
If I want to port a library L to modules, but an application A which is using L will be updated to Visual Studio 2019 but with /permissive (i.e. not compatible with modules) – is it possible to somehow consume a module from L in A or is modularization of a library dependent on all downstream applications/users also not using /permissive mode?
Hi Mats,
Luckily there is still an avenue for combining /permissive and /permissive- with Modules in these "bridge" modes. Historically, we have had instances with programs needing both /permissive and /permissive- in different parts of a program, and the compiler does preserve ABI between the two. With Modules you must compiler with /permissive-, which is why it is now implied by /std:c++latest, but as long as an individual translation unit does not use any...
Hi,
Thanks, but I don’t quite understand this. What I need is to _use_ modules (i.e. import module) in my application A which is compiled using /permissive (not /permissive-). So what you’re saying is that I need to compile TUs that need to import a module from library L using /permissive- (while other TUs can continue using /permissive)?
Yes, if you are using a module functionality (e.g. import, export) in a TU, you need to use /permissive- for that TU.
ok – thanks 🙂