You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: clang/docs/Modules.rst
+58-1
Original file line number
Diff line number
Diff line change
@@ -242,7 +242,7 @@ a module, one must write a ``module.modulemap`` file for that library. The
242
242
and is written in the module map language described below.
243
243
244
244
.. note::
245
-
For compatibility with previous releases, if a module map file named ``module.modulemap`` is not found, Clang will also search for a file named ``module.map``. This behavior is deprecated and we plan to eventually remove it.
245
+
For compatibility with previous releases, if a module map file named ``module.modulemap`` is not found, Clang will also search for a file named ``module.map``. This behavior is deprecated and we plan to eventually remove it.1
246
246
247
247
As an example, the module map file for the C standard library might look a bit like this:
248
248
@@ -730,6 +730,63 @@ Attributes are used in a number of places in the grammar to describe specific be
730
730
731
731
Any *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it.
732
732
733
+
Private Module Map Files
734
+
------------------------
735
+
Module map files are typically named ``module.modulemap`` and live
736
+
either alongside the headers they describe or in a parent directory of
737
+
the headers they describe. These module maps typically describe all of
738
+
the API for the library.
739
+
740
+
However, in some cases, the presence or absence of particular headers
741
+
is used to distinguish between the "public" and "private" APIs of a
742
+
particular library. For example, a library may contain the headers
743
+
``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
744
+
respectively. Additionally, ``Foo_Private.h`` may only be available on
745
+
some versions of library, and absent in others. One cannot easily
746
+
express this with a single module map file in the library:
747
+
748
+
.. parsed-literal::
749
+
750
+
module Foo {
751
+
header "Foo.h"
752
+
753
+
explicit module Private {
754
+
header "Foo_Private.h"
755
+
}
756
+
}
757
+
758
+
759
+
because the header ``Foo_Private.h`` won't always be available. The
760
+
module map file could be customized based on whether
761
+
``Foo_Private.h``is available or not, but doing so requires custom
762
+
build machinery.
763
+
764
+
Private module map files, which are named ``module.private.modulemap``
765
+
(or, for backward compatibility, ``module_private.map``), allow one to
766
+
augment the primary module map file with an additional submodule. For
767
+
example, we would split the module map file above into two module map
768
+
files:
769
+
770
+
.. parsed-literal::
771
+
772
+
/* module.modulemap */
773
+
module Foo {
774
+
header "Foo.h"
775
+
}
776
+
777
+
/* module.private.modulemap */
778
+
explicit module Foo.Private {
779
+
header "Foo_Private.h"
780
+
}
781
+
782
+
783
+
When a ``module.private.modulemap`` file is found alongside a
784
+
``module.modulemap`` file, it is loaded after the ``module.modulemap``
785
+
file. In our example library, the ``module.private.modulemap`` file
786
+
would be available when ``Foo_Private.h`` is available, making it
787
+
easier to split a library's public and private APIs along header
788
+
boundaries.
789
+
733
790
Modularizing a Platform
734
791
=======================
735
792
To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system).
0 commit comments