================
@@ -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.
----------------
ChuanqiXu9 wrote:
For example, if the library is in a closed-ended ecosystem (e.g., only
available to an organization internally), then we want to provide modules
interfaces for the library and we want our users to avoid the accidental
performance cost due to mixing use of include and import, then such pattern
helps. In case, the user repo A depends on a repo B and repo B include the
modularized library, the repo A can reach out repo B to refactor itself. I feel
such workflow can be understandable in a close ended organization.
It will bring some burden to users initially, but in the end it would bring
better quality. I understand this is not a helpful universally. But I feel it
may be helpful to people who want to bring stronger requirement to the usage of
their codes.
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
