{"id":7311,"date":"2015-12-03T10:21:00","date_gmt":"2015-12-03T10:21:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/vcblog\/2015\/12\/03\/c-modules-in-vs-2015-update-1\/"},"modified":"2019-02-18T18:04:54","modified_gmt":"2019-02-18T18:04:54","slug":"c-modules-in-vs-2015-update-1","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/c-modules-in-vs-2015-update-1\/","title":{"rendered":"C++ Modules in VS 2015 Update 1"},"content":{"rendered":"

\u70b9\u8fd9\u91cc\u770b\u4e2d\u6587\u7248<\/a><\/p>\n

[This post was written by Gabriel Dos Reis and Andrew Pardoe]<\/span><\/p>\n

Update: See this post on using the Standard Library via modules in MSVC<\/a>.<\/strong><\/p>\n

The VC++ team is excited to preview a new feature in VS 2015 Update 1: The first experimental implementation of<\/span>\u00a0<\/span>A Module System for C++<\/a><\/em>, proposed for C++17. That proposal was approved by the C++ standards Evolution Working Group for a C++17 Technical Specification at the Fall 2015 meeting in Kona, Hawai\u2019i. The\u00a0<\/span><\/span>draft wording for the Technical Specification<\/a>\u00a0<\/span>is under review by the C++ Standards Core Working Group.<\/span><\/p>\n

Modules are often talked about as a way to speed up compilation. But they have far more to offer than just build performance! C++ Modules can help you improve componentization of your code. In fact, componentization is an effective road to compilation and build throughput. Modules allow you to isolate your code from hard-to-debug preprocessor state. And they make it easier to develop tools to work with your code.<\/span><\/p>\n

Modules allow you to express the symbolic dependency your component is taking on providers of functionalities it needs, and the boundary of that dependency, directly in code. Modules eliminate the need for convoluted preprocessor voodoo to specify interfaces through header files. The preprocessor is there for you and works together with the modules system if you have no other choice but to work with macro-based interfaces, conditional compilation and code-generation. The preprocessor is a powerful beast with no structure and C++ Modules aren\u2019t designed to do everything that it does. The preprocessor\u2019s job is to generate pre-tokens for the lexer to consume. It has been put to creative usages, for more than 40 years, to generate various sorts of text, including HTML source documents.<\/span><\/p>\n

If you want to know more about the principles and rationale behind the design choices of C++ Modules, stop now and read the proposal:<\/span>\u00a0<\/span>A Module System for C++<\/a><\/em>\u00a0.There\u2019s also a great talk on C++ Modules by Gabriel Dos Reis from CppCon 2015. The video is on the\u00a0<\/span><\/span>CppCon YouTube channel<\/a>; the slides from the talk are also available in an<\/span>\u00a0<\/span>IsoCpp GitHub repo<\/a>. But if you want to jump right in and see what this feature has to offer, read on!<\/span><\/p>\n

The implementation in Visual C++ 2015 Update 1 is a preview of an ongoing effort so we\u2019re eager to hear your feedback.<\/strong>\u00a0<\/span>This is a chance for you to have impact on a major C++ feature. We want to build a C++ modules system that works for all developers with all compilers so please let us know if you have any feedback. You can reach us at<\/span>\u00a0<\/span>modules@microsoft.com<\/a>.<\/p>\n

Modules Support in Visual C++ 2015 Update 1<\/span><\/h2>\n

First, you should know that module support is completely guarded by a switch:\u00a0<\/span>\/experimental:module<\/em>. If you don\u2019t use this switch then the modules feature won\u2019t affect your code at all. Also, be aware that support for modules is only in the command-line tools right now. A lot of IDE functionality should just work but full IDE integration isn’t there yet. Also, this preview\u2019s focus is on componentization. As we advance in completing support for C++ language features, we will be increasing our focus to optimizing build throughput in the module support; without componentization first, it would be far too easy to duplicate a particular build logic without making significant dents into the fundamental problems.<\/span><\/p>\n

Producing Modules<\/span><\/h3>\n

Creating and using a module is straightforward: the developer merely declares a source file to contain the definition of a module by writing\u00a0<\/span><\/span>module M;<\/code>. She then announces what parts of the source file are part of the module\u2019s interface by preceding each and every single declaration of those entities with the<\/span>\u00a0<\/span>export<\/code>\u00a0<\/span>keyword.<\/span><\/p>\n

Any top-level declaration can be exported or any sequence of top-level declarations contained in braces. Modules do not define new namespaces or change name lookup rules in any way. They simply allow the developer to specify and publish the interface for a source file. So, there is really no new name lookup rules you need to learn.<\/span><\/p>\n

In this example, the functions\u00a0<\/span><\/span>f(int)<\/code>\u00a0<\/span>and<\/span>\u00a0<\/span>g(double, int)<\/code>\u00a0<\/span>are exported as part of the interface of<\/span>\u00a0<\/span>module M<\/code>.<\/span><\/p>\n

\/\/ file: foo.ixx<\/span>\nmodule M;<\/span>\nexport int<\/span> f(int<\/span> x<\/span>) <\/span>\n{ <\/span>\n\u00a0\u00a0\u00a0 return<\/span> 2 + x<\/span>; <\/span>\n} <\/span>\nexport double<\/span> g(double<\/span> y<\/span>, int <\/span>z<\/span>) <\/span>\n{ <\/span>\n\u00a0\u00a0\u00a0 return<\/span> y<\/span> * z<\/span>; <\/span>\n} <\/span><\/span><\/span><\/span><\/p>\n

The command line to compile the module interface is just\u00a0<\/span>cl \/c \/experimental:module foo.ixx<\/em>. The extension “ixx” is special. It tells the compiler that the content of the source file is supposed to be a module interface source code. If you want to use another extension on your interface file you also have to supply the switch\/module:interface<\/em>. (Note these switches are subject to change in the future!)<\/span><\/p>\n

When you compile a module interface file, you get an OBJ file as usual. The compiler also produces a file with extension “.ifc”(called an\u00a0<\/span>IFC file<\/em>) that contains a metadata description of the module interface. This is the only time that the module support produces anything additional to what a traditional compilation would do. The binary format of the IFC file will be open source; it is modelled after the<\/span>\u00a0<\/span>Internal Program Representation<\/a><\/em>\u00a0<\/span>work done by Gabriel Dos Reis and Bjarne Stroustrup a decade ago. The original implementation of the IPR is open source and can be found in the\u00a0<\/span><\/span>IPR repo on GitHub<\/a>.<\/span><\/p>\n

Consuming Modules<\/span><\/h3>\n

<\/a>To consume the module, the developer writes<\/span>\u00a0<\/span>import M;<\/code>\u00a0<\/span>at the top of a source file, thus making the declarations of<\/span>\u00a0<\/span>f(int)<\/code>\u00a0<\/span>and<\/span>\u00a0<\/span>g(double, int)<\/code>\u00a0<\/span>visible in the source file. The compiler switch to specify a compiled binary module interface file is\u00a0<\/span>\/module:reference<\/em>.<\/span><\/p>\n

\/\/ file: bar.cpp<\/span>\nimport<\/span>\u00a0M;\n<\/span>int main()<\/span><\/span><\/span>\n{\nf(5);\ng(0.0, 1);<\/span>\n\u00a0\u00a0\u00a0 return<\/span> 0; <\/span>\n} <\/span><\/span><\/span><\/span><\/p>\n

Compile bar.cpp with the command line\u00a0<\/span>cl \/experimental:module \/module:reference M.ifc bar.cpp foo.obj<\/em>. The function definitions for<\/span>\u00a0<\/span>f(int)<\/code>\u00a0<\/span>and\u00a0<\/span><\/span>g(double, int)<\/code>\u00a0<\/span>are available in bar.cpp because of the import statement. If there are too many reference files, or if you put all your IFC files in a given directory, you can instead use the compiler option\u00a0<\/span>\/module:search<\/em>\u00a0<\/span>which takes a directory name as its argument.<\/span><\/p>\n

Overview<\/span><\/h3>\n

At the file level, the source file containing the module definition is called foo.ixx. (The name of the module definition, M in our example, doesn\u2019t need to match the name of the file, foo.) Compiling foo.ixx creates M.ifc, the module interface file, which is a binary representation of the interface, in addition to foo.obj, the standard Windows object file.<\/span><\/p>\n

When consuming a module (with the\u00a0<\/span>\/module:reference<\/em>\u00a0<\/span>switch), the compiler reads in M.ifc to make the top-level exported names in the interface available to the source file currently being compiled, and the linker consumes foo.obj as usual.<\/span><\/p>\n

These three keywords and two switches are enough to let you experiment with C++ Modules. There are a few more switches available for transitional scenarios but they\u2019re not something to depend upon as they might change as the design evolves.<\/span><\/p>\n

Edit 4 Oct 2016: We’ve had some interest in specifying the output directory and interface file name. That option is simply \/module:output, as follows:\n\u00a0\u00a0cl \/experimental:module \/module:export \/module:name ModuleName \/module:wrapper C:\\Output\\path\\ModuleName.h <\/span>\/module:output C:\\Output\\path\\ModuleName.ifc<\/span><\/span> -c <source-file><\/span><\/p>\n

Convenience Functions<\/span><\/h2>\n

It’s important that C++ Modules be incrementally adoptable in your source code. We’ve created a few convenience functions to help with migration scenarios. All of these functions are being tested by teams inside of Microsoft. They will likely change based on internal and external developer feedback. We’ve also created some tooling to help manipulate module interface files that we’ll discuss in another blog post.<\/span><\/p>\n

Consuming Existing Legacy Header Files as Module Interfaces<\/span><\/h3>\n

Say you have an existing source file (in particular header file) that is well-behaved in terms of macros and preprocessor state. You’d like to make that header consumable as if it was a module interface. We’ve build a convenience into the compiler that allows you to pretend that all top-level declarations with external linkage in a C++ source file were marked as exported. You use the switches\u00a0<\/span>\/module:name<\/em>\u00a0<\/span>and\u00a0<\/span>\/module:export<\/em>\u00a0<\/span>to automatically create a compiled module interface (IFC) from a header. The argument to\u00a0<\/span>\/module:name<\/em>\u00a0<\/span>specifies the name of the module interface (.IFC) and the argument to\u00a0<\/span>\/module:export<\/em>\u00a0<\/span>specifies which header file should be consumed to create the module interface. Note that you currently have to include your header in a .cpp file (or rename your header) because of a limitation in our compiler’s file handling.<\/span><\/p>\n

\/\/ file: foo.cpp<\/span>\nint<\/span> f(int<\/span> x<\/span>) <\/span>\n{ <\/span>\n\u00a0\u00a0\u00a0 return<\/span> 2 + x<\/span>; <\/span>\n} <\/span>\ndouble<\/span> g(double<\/span> y<\/span>, int <\/span>z<\/span>) <\/span>\n{ <\/span>\n\u00a0\u00a0\u00a0 return<\/span> y<\/span> * z<\/span>; <\/span>\n} <\/span><\/span><\/span><\/p>\n

The command line\u00a0<\/span>cl \/c \/experimental:module \/module:name mymodule \/module:export foo.cpp<\/em>\u00a0<\/span>produces mymodule.ifc, an interface file with definitions for\u00a0<\/span><\/span>f(int)<\/code>\u00a0<\/span>and <\/span>g(double, int)<\/code>.<\/span><\/p>\n

Module Search Path<\/span><\/h3>\n

\/module:search<\/em>\u00a0<\/span>indicates a directory where the compiler should search for files referenced via\u00a0<\/span>\/module:reference<\/em>. For example, the compilation command line for bar.cpp above (in<\/span>\u00a0<\/span>Consuming Modules<\/a>) could have been written as\u00a0<\/span>cl \/experimental:module \/module:search . bar.cpp foo.obj<\/em>\u00a0<\/span>to search the current directory for the IFC file.<\/span><\/p>\n

Preserving Macros<\/span><\/h3>\n

Lastly, if your legacy source file defines macros that are essential to its consumers, you can have the compiler generate a wrapper header file containing an import declaration followed by a preprocessor definition of those macros. The compiler switch\u00a0<\/span>\/module:exportActiveMacros<\/em>\u00a0<\/span>exports all macro definitions that are active when the compiler finishes compiling the source file that defines the module. If you want to be selective you can use\u00a0<\/span>\/module:exportMacro\u00a0<\/span><\/em>instead, where\u00a0<\/span><\/em>designates the macro you want to be defined in the wrapper file. The name of the wrapper header file is specified via the switch\u00a0<\/span>\/module:wrapper<\/em>\u00a0<\/span>which takes a filename argument.<\/span><\/p>\n

\/\/ file: baz.h<\/span>\n#ifndef<\/span> BAR_INCLUDED<\/span>\n#define<\/span> number<\/span> 6<\/span>\nint<\/span> f(int<\/span> x<\/span>) <\/span>\n{ <\/span>\n\u00a0\u00a0\u00a0 return<\/span> 2 + x<\/span>; <\/span>\n} <\/span>\ndouble<\/span> g(double<\/span> y<\/span>, int <\/span>z<\/span>) <\/span>\n{ <\/span>\n\u00a0\u00a0\u00a0 return<\/span> y<\/span> * z<\/span>; <\/span>\n} <\/span>\n#endif<\/span> \/\/ BAR_INCLUDED<\/span><\/span><\/span><\/p>\n

\/\/ file: baz.cpp<\/span>\n#include<\/span> \u201cbaz.h\u201d<\/span><\/p>\n

Compiling the above source files with\u00a0<\/span>cl \/c \/experimental:module \/module:export \/module:name mymodule baz.cpp \/module:wrapper baz-wrapper.h \/module:exportActiveMacros <\/em>will produce mymodule.ifc, as expected, but will additionally produce a header file, baz-wrapper.h, containing the following:<\/span><\/p>\n

#ifndef<\/span> mymodule_WRAPPER_INCLUDED<\/span>\n#define<\/span> mymodule_WRAPPER_INCLUDED<\/span><\/span>\nimport mymodule;<\/span>\n#define<\/span> number<\/span> 6<\/span>\n#endif<\/span> \/\/ mymodule_WRAPPER_INCLUDED<\/span><\/span><\/span><\/p>\n

You can now include baz-wrapper.h instead of baz.h and get the componentization benefits of modules even if baz.h wasn\u2019t written as a module in the first place. This technique preserves your preprocessor state and gives you a chance to clean up any macros that you might not have realized were active at the time. Sadly, sorting through rogue preprocessor state is an all too common experience.<\/span><\/p>\n

Have Fun!<\/span><\/h2>\n

C++ Modules in VS 2015 Update 1 are an exciting feature, even in this early state. There\u2019s more goodness to come\u2014obviously we\u2019re lacking some basic functionality such as integration with the VS IDE and build system\u2014but we wanted to get something out there early so that our developer community could have a chance to impact the work in a big way. Please try out C++ Modules and let us know your thoughts at<\/span>\u00a0<\/span>modules@microsoft.com<\/a>.<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

\u70b9\u8fd9\u91cc\u770b\u4e2d\u6587\u7248 [This post was written by Gabriel Dos Reis and Andrew Pardoe] Update: See this post on using the Standard Library via modules in MSVC. The VC++ team is excited to preview a new feature in VS 2015 Update 1: The first experimental implementation of\u00a0A Module System for C++, proposed for C++17. That proposal was […]<\/p>\n","protected":false},"author":312,"featured_media":35994,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[48,140,100,151,246],"class_list":["post-7311","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-cplusplus","tag-build","tag-c","tag-c-language","tag-iso-c","tag-modules"],"acf":[],"blog_post_summary":"

\u70b9\u8fd9\u91cc\u770b\u4e2d\u6587\u7248 [This post was written by Gabriel Dos Reis and Andrew Pardoe] Update: See this post on using the Standard Library via modules in MSVC. The VC++ team is excited to preview a new feature in VS 2015 Update 1: The first experimental implementation of\u00a0A Module System for C++, proposed for C++17. That proposal was […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/7311","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\/312"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=7311"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/7311\/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=7311"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=7311"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=7311"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}