[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/ChuanqiXu9 closed 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/ChuanqiXu9 updated
https://github.com/llvm/llvm-project/pull/80687
>From 19065e2e25e8bbd735b157239702e4394659bbc7 Mon Sep 17 00:00:00 2001
From: Chuanqi Xu
Date: Mon, 5 Feb 2024 22:31:19 +0800
Subject: [PATCH 1/2] [docs] [C++20] [Modules] Ideas for transiting to modules
---
clang/docs/StandardCPlusPlusModules.rst | 339
1 file changed, 339 insertions(+)
diff --git a/clang/docs/StandardCPlusPlusModules.rst
b/clang/docs/StandardCPlusPlusModules.rst
index c322805d8db5bc..f4c3c4f0d8813c 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
+new ABI format.
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/dwblaikie approved this pull request. Seems ok 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
ChuanqiXu9 wrote: I'd like to land this in 2 weeks if no more comments come in. 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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:
What's the motivation for doing this? Given the challenges it presents to
downstream usage of the library?
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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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.
dwblaikie wrote:
```suggestion
interface unit file to match changes to the headers in the future.
```
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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
+new ABI format. This is the job of the additional part of the interface unit:
+
+.. code-block:: c++
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+In case the
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
+new ABI format. This is the job of the additional part of the interface unit:
+
+.. code-block:: c++
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+In case the
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
+new ABI format. This is the job of the additional part of the interface unit:
+
+.. code-block:: c++
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+In case the
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
dwblaikie wrote:
```suggestion
Remember that the ABI is changed and we need to compile our source files into
the
```
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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
+new ABI format. This is the job of the additional part of the interface unit:
+
+.. code-block:: c++
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+In case the
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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 dwblaikie wrote: ```suggestion For many existing libraries, it may be a breaking change to refactor them ``` 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
+new ABI format. This is the job of the additional part of the interface unit:
+
+.. code-block:: c++
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+In case the
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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**. dwblaikie wrote: ```suggestion **Note that the this section is only about helpful ideas instead of requirement from clang**. ``` 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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:
```suggestion
The style prevents the users from including your headers and importing your
modules at the same time
in the same repo.
```
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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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,
dwblaikie wrote:
```suggestion
As the example shows, you need to include all the headers containing
declarations that need
to be exported and `using` such declarations in an `export` block. Then,
basically,
```
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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
@@ -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 dwblaikie wrote: ```suggestion into modules completely. So many existing libraries will need to provide headers and module ``` 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/dwblaikie commented: Generally seems like good stuff to write down - I'm not sure about the ABI breaking version (that mostly seems like it would make more problems than solutions). Commented on some minor grammatical issues. 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/dwblaikie edited 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/ChuanqiXu9 updated
https://github.com/llvm/llvm-project/pull/80687
>From 2fcbdb034613ea6fdea4ce9efd5656116edb2ca1 Mon Sep 17 00:00:00 2001
From: Chuanqi Xu
Date: Mon, 5 Feb 2024 22:31:19 +0800
Subject: [PATCH] [docs] [C++20] [Modules] Ideas for transiting to modules
---
clang/docs/StandardCPlusPlusModules.rst | 339
1 file changed, 339 insertions(+)
diff --git a/clang/docs/StandardCPlusPlusModules.rst
b/clang/docs/StandardCPlusPlusModules.rst
index c322805d8db5b..f4c3c4f0d8813 100644
--- a/clang/docs/StandardCPlusPlusModules.rst
+++ b/clang/docs/StandardCPlusPlusModules.rst
@@ -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.
+
+The pattern for ABI breaking style is similar with 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
+ #include "header_1.h"
+ #include "header_2.h"
+ ...
+ #include "header_n.h"
+
+ #if the number of .cpp files in your project are small
+ module :private;
+ #include "source_1.cpp"
+ #include "source_2.cpp"
+ ...
+ #include "source_n.cpp"
+ #else // the number of .cpp files in your project are a lot
+ // Using all the declarations from thirdparty libraries which are
+ // used in the .cpp files.
+ namespace third_party_namespace {
+using third_party_decl_used_in_cpp_1;
+using third_party_decl_used_in_cpp_2;
+...
+using third_party_decl_used_in_cpp_n;
+ }
+ #endif
+
+(And add `EXPORT` and conditional include to the headers as suggested in the
export
+extern-C++ style section)
+
+Remember that the ABI get changed and we need to compile our source files into
the
+new ABI format. This is
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/ChuanqiXu9 edited 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
[clang] [docs] [C++20] [Modules] Ideas for transitioning to modules (PR #80687)
https://github.com/ChuanqiXu9 edited 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
