================ @@ -610,6 +610,345 @@ the following style significantly: The key part of the tip is to reduce the duplications from the text includes. +Ideas for converting to modules +------------------------------- + +For new libraries, we encourage them to use modules completely from day one if possible. +This will be pretty helpful to make the whole ecosystems to get ready. + +For many existing libraries, it may be a breaking change to refactor themselves +into modules completely. So that many existing libraries need to provide headers and module +interfaces for a while to not break existing users. +Here we provide some ideas to ease the transition process for existing libraries. +**Note that the this section is only about helping ideas instead of requirement from clang**. + +Let's start with the case that there is no dependency or no dependent libraries providing +modules for your library. + +ABI non-breaking styles +~~~~~~~~~~~~~~~~~~~~~~~ + +export-using style +^^^^^^^^^^^^^^^^^^ + +.. code-block:: c++ + + module; + #include "header_1.h" + #include "header_2.h" + ... + #include "header_n.h" + export module your_library; + export namespace your_namespace { + using decl_1; + using decl_2; + ... + using decl_n; + } + +As the example shows, you need to include all the headers containing declarations needs +to be exported and `using` such declarations in an `export` block. Then, basically, +we're done. + +export extern-C++ style +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c++ + + module; + #include "third_party/A/headers.h" + #include "third_party/B/headers.h" + ... + #include "third_party/Z/headers.h" + export module your_library; + #define IN_MODULE_INTERFACE + extern "C++" { + #include "header_1.h" + #include "header_2.h" + ... + #include "header_n.h" + } + +Then in your headers (from ``header_1.h`` to ``header_n.h``), you need to define the macro: + +.. code-block:: c++ + + #ifdef IN_MODULE_INTERFACE + #define EXPORT export + #else + #define EXPORT + #endif + +And you should put ``EXPORT`` to the beginning of the declarations you want to export. + +Also it is suggested to refactor your headers to include thirdparty headers conditionally: + +.. code-block:: c++ + + + #ifndef IN_MODULE_INTERFACE + #include "third_party/A/headers.h" + + #endif + + #include "header_x.h" + + ... + +This may be helpful to get better diagnostic messages if you forgot to update your module +interface unit file during maintaining. + +The reasoning for the practice is that the declarations in the language linkage are considered +to be attached to the global module. So the ABI of your library in the modular version +wouldn't change. + +While this style looks not as convenient as the export-using style, it is easier to convert +to other styles. + +ABI breaking style +~~~~~~~~~~~~~~~~~~ + +The term ``ABI breaking`` sounds terrifying generally. But you may want it here if you want +to force your users to introduce your library in a consistent way. E.g., they either include +your headers all the way or import your modules all the way. +The style prevents the users to include your headers and import your modules at the same time +in the same repo. ---------------- dwblaikie wrote:
I would imagine this is generally an anti-goal for most people, or would create maintenance challenges - because if your library is used by other libraries - some of those users might be using C++20 modules, and some might not be. And then if you want to depend on all those libraries together in some other library/program, it'd be unfortunate if you were stuck/not able to do that due to the very opinionated original library that said "only use headers or only use modules, don't mix and match". https://github.com/llvm/llvm-project/pull/80687 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits