From b306fc50b9d116c29a302870715c608c6dbf5bc6 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Mon, 11 Sep 2017 09:36:47 +0200 Subject: More C++ Modules documentation updates --- doc/manual.cli | 50 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 20 deletions(-) (limited to 'doc') diff --git a/doc/manual.cli b/doc/manual.cli index 8406956..3a68f66 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -1066,6 +1066,7 @@ f () extra_impl (); // Error. core (); // Ok. extra (); // Ok. + extra2 (); // Error. } \ @@ -1080,28 +1081,37 @@ interface unit and that is required when compiling any translation unit that imports this module (as well as the module's implementation units). So, in a nutshell, the main functionality of a build system when it comes to -modules support is figuring out the order in which all the units should be -compiled and making sure that every compilation is able to find the binary -module interfaces it needs. +modules support is figuring out the order in which all the translation units +should be compiled and making sure that every compilation is able to find the +binary module interfaces it needs. Predictably, the details are more complex. Compiling a module interface unit -produces two outputs: the binary module interface and the object file. Also, -all the compilers currently implement module re-export as a shallow reference -to the re-exported module name which means that their binary interfaces must -be discoverable as well, recursively. In fact, currently, all the imports are -handled like this, though a different implementation is at least plausible, if -unlikely. - -While the details vary between compilers, the contents of the binary -interfaces are generally sensible to the compiler options. If the options used -to produce the binary interface (for example, when building a library) are -sufficiently different compared to the ones used when compiling the module -consumers, the binary interface may be unusable. So while a build system -should strive to reuse existing binary interfaces, it should also be prepared -to compile its own versions \"on the side\". This suggests that modules are -not a distribution mechanism, that binary module interfaces should probably -not be installed, and that instead we should install and distribute module -interface sources. +produces two outputs: the binary module interface and the object file. The +latter contains object code for non-inline functions, global variables, etc., +that the interface unit may define. This object file has to be linked when +producing any binary (program or library) that uses this module. + +Also, all the compilers currently implement module re-export as a shallow +reference to the re-exported module name which means that their binary +interfaces must be discoverable as well, recursively. In fact, currently, all +the imports are handled like this, though a different implementation is at +least plausible, if unlikely. + +While the details vary between compilers, the contents of the module binary +interface can range from a stream of preprocessed tokens to something fairly +close to object code. As a result, binary interfaces can be sensitive to the +compiler options and if the options used to produce the binary interface (for +example, when building a library) are sufficiently different compared to the +ones used when compiling the module consumers, the binary interface may be +unusable. So while a build system should strive to reuse existing binary +interfaces, it should also be prepared to compile its own versions \"on the +side\". + +This also suggests that binary module interfaces are not a distribution +mechanism and should probably not be installed. Instead, we should install and +distribute module interface sources and build systems should be prepared to +compile them, again, on the side. + \h2#cxx-modules-build|Building Modules| -- cgit v1.1