{"id":26946,"date":"2020-10-29T15:00:54","date_gmt":"2020-10-29T15:00:54","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=26946"},"modified":"2022-08-11T20:54:55","modified_gmt":"2022-08-11T20:54:55","slug":"a-tour-of-cpp-modules-in-visual-studio","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/a-tour-of-cpp-modules-in-visual-studio\/","title":{"rendered":"A Tour of C++ Modules in Visual Studio"},"content":{"rendered":"

<\/i>Content outdated<\/strong><\/p> For up-to-date documentation see Overview of modules in C++<\/span><\/span><\/a>.<\/div>C++ module support has arrived in Visual Studio! Grab the latest Visual Studio Preview<\/a> if you want to try it out. C++ modules<\/a> can help you compartmentalize your code, speed up build times, and they work seamlessly, side-by-side with your existing code.<\/p>\n

This preview only supports C++ modules in the IDE for MSBuild projects. While the MSVC toolset is supported by any build system, Visual Studio\u2019s IDE support for CMake doesn\u2019t support C++ modules yet. We will let you know once it is! As always, please try it out and let us know if you have any feedback.<\/p>\n

Module Basics<\/h2>\n

C++ modules allow you to closely control what is made available to the translation units that consume them. Unlike headers, they won\u2019t leak macro definitions or private implementation details (no ridiculous prefixes needed). Also, unlike headers, they are built once and then can be consumed many times across your projects, reducing build overhead.<\/p>\n

C++20 introduces new keywords to define and consume modules and Visual Studio uses a new file type \u201c.ixx\u201d to define a module\u2019s interface. Read on for the details.<\/p>\n

Getting Started with Modules in Visual Studio<\/h2>\n

If you created a brand-new project in the latest preview, you don\u2019t need to do anything. However, before you can add or consume modules in existing projects you need to make sure you are using the latest C++ Language Standard.<\/p>\n

To do this, set the C++ Language Standard to \u201cPreview \/std:c++latest\u201d. If you have multiple projects in your solution, remember to do this for all of them.<\/p>\n

\"General<\/a><\/p>\n

And that\u2019s it! You are ready to use C++ modules with Visual Studio.<\/p>\n

Creating Modules<\/h3>\n

To add a module to a project you will need to create a module interface. These are normal C++ source files with the extension \u201c.ixx\u201d. They can include headers, import other modules, and will include the exported definitions of your module. You can add as many of these to a project as you want.<\/p>\n

\"Add<\/a><\/p>\n

Here\u2019s how this then looks in the Solution Explorer. In this example, the fib<\/code> and printer<\/code> projects both define C++ modules.<\/p>\n

\"Solution<\/a><\/p>\n

Note:<\/em><\/strong> While this example shows all module interfaces in \u201c.ixx\u201d files, any C++ source file can be treated as a module interface. To do this, set the \u201cCompile As\u201d property on a source file to \u201cCompile As Module\u201d. The \u201cCompile As\u201d property can be found on the \u201cAdvanced\u201d tab on any source file’s properties page.<\/p>\n

Exporting Modules<\/h3>\n

So, what actually goes into a module interface? The example below defines a simple module called DefaultPrinter<\/code> and exports a single struct:<\/p>\n

module; \/\/begins global module fragment\r\n\r\n#include <iostream>\r\n\r\nexport module DefaultPrinter;\r\n\r\nexport struct DefaultPrinter\r\n{\r\n    void print_element(int e)\r\n    {\r\n        std::cout << e << \" \";\r\n    }\r\n\r\n    void print_separator()\r\n    {\r\n        std::cout << \", \";\r\n    }\r\n\r\n    void print_eol()\r\n    {\r\n        std::cout << '\\n';\r\n    }\r\n};\r\n<\/pre>\n
To break the example down a bit, you can see the new export syntax on lines 1, 5, and 7. Line 1 specifies that this is a module interface. Line 5 defines and exports the module itself and line 7 exports a struct. Each module can export many items, such structs, classes, functions, and templates.<\/p>\n
Module interfaces can include headers and import other modules. When they are imported, they will not leak any details from these included headers or modules unless you explicitly import them. This isolation can help avoid naming collisions and leaking implementation details. You can safely define macros and use namespaces in module interfaces too. They will not leak like traditional headers.<\/p>\n
To\u00a0#include<\/code> headers in a module interface, ensure you put them in the\u00a0global module fragment<\/em> between\u00a0module;<\/code> and\u00a0export module mymodule;<\/code>.<\/p>\n
This example puts the implementation in the module\u2019s interface, but that is optional. If you look back at the solution explorer before you can see the fibgen.ixx interface has a corresponding implementation in fibgen.cpp.<\/p>\n
Its interface looks like this:<\/p>\n
export module FibGenerator;\r\nexport fib gen_fib(int start, int &len);\r\n<\/pre>\n
With a corresponding implementation:<\/p>\n
module FibGenerator;\r\n\r\nfib gen_fib(int start, int &len)\r\n{\r\n\t\/\/...\r\n}\r\n<\/pre>\n
Here, the interface defines the module name and exports gen_fib<\/code>. The corresponding implementation uses the module<\/code> keyword to define which module the implementation belongs to so everything can be combined into a cohesive unit automatically at build time.<\/p>\n
Consuming Modules<\/h3>\n
To consume modules, use the new import<\/code> keyword.<\/p>\n
module;\r\n#include <ranges>\r\n#include <concepts>\r\n\r\nimport DefaultPrinter;\r\n\r\nstruct DefaultFormatter\r\n{\r\n    template<is_series S, is_printer T>\r\n    void format(T t, S s)\r\n    {\r\n        while (!s.done())\r\n        {\r\n            t.print_element(s.next());\r\n            t.print_separator();\r\n        }\r\n        t.print_eol();\r\n    }\r\n};<\/pre>\n
All exported items from the module interface will be available for use. This example makes use of the DefaultPrinter<\/code> module in the first example, importing it on line 5.<\/p>\n
Your code can consume modules in the same project or any referenced ones automatically (using project-to-project references<\/a> to static library projects).<\/p>\n
Consuming Modules from Other Modules<\/h4>\n
You can also import modules from another module interface. Here is an example that expands on the DefaultPrinter<\/code> module above:<\/p>\n
module;\r\n#include <iostream>\r\nimport DefaultPrinter;\r\n\r\nexport module TabbedPrinter;\r\n\r\nexport struct TabbedPrinter : DefaultPrinter\r\n{\r\n    void print_separator()\r\n    {\r\n        std::cout << \"\\t\";\r\n    }\r\n};<\/pre>\n
This example imports the DefaultPrinter<\/code> module above and overrides its print_separator<\/code> function. Other code can now import this TabbedPrinter<\/code> without needing to worry about the details of DefaultPrinter<\/code>. Visual Studio will make sure everything is built in the right order.<\/p>\n
External Modules<\/h3>\n
It is also possible to reference modules that exist on disk, instead of ones belonging to another project in the solution. Care needs to be taken here, however, because modules are compiled, binary files. You must make sure they are compatible with the way you are building your projects.<\/p>\n
You can tell Visual Studio to look for modules on disk by editing the Additional Module Dependencies property:<\/p>\n
\"C\/C++<\/a><\/p>\n
IntelliSense and Modules<\/h2>\n
All the IntelliSense features you know and love also work with modules. Features like code completion, parameter help, Find All References, Go To Definition and Declaration, rename, and more all work across solutions the way you would expect when you use modules.<\/p>\n
Here you can see Find All References and Peek Definition working with our TabbedPrinter<\/code> module above. For instance, it can show all references of the DefaultPrinter<\/code>\u00a0structure exported from the DefaultPrinter<\/code>\u00a0module and display its definition:<\/p>\n
Find All References<\/b>\n\"Find<\/a><\/p>\n
Peek Definition<\/b>\n\"Peek<\/a><\/p>\n
You can also Go To or Peek the Definition of a module itself from anywhere that imports it:<\/p>\n
\"Peek<\/a><\/p>\n
See Modules in Action<\/h2>\n
To see all of this in action, check out our modules demo from CppCon 2020<\/a>. There are many other demos of the latest Visual Studio and C++20 features in action too if you are interested.<\/p>\n